Building Configuration Files

Use these tabs to learn how to create JSON-based Configuration Files for MANTLE Mobile. Each tab covers a different aspect of configuration-building, from Recording your interactions on a single device to editing advanced features directly in the JSON.

RecordingView TypesCustom VariablesDevice FilesEditing Configuration FilesAdvanced Configuration File Features

Overview of Recording

The Record feature in MANTLE Mobile allows you to configure an application step-by-step on a single device. When you finish, MANTLE Mobile generates a JSON file containing every action taken (button presses, text entries, menu navigation, etc.). You can then deploy the same steps to multiple devices simultaneously.

This feature is accessed within Tools → Configuration Manager by selecting the Record New Configuration File button.

Important Notes

• Ensure USB Debugging is enabled on your device.
• The device must be added to the Device Management database.
• After each task, you’re prompted with "Did the Correct Action Happen?" Confirm the expected outcome before clicking Yes.

Recording Steps

1. Select Application to Open

   • Upon clicking Record in the Home tab, you’ll be prompted to choose the app you plan to configure.
   • Select the intended application and press Start then wait for MANTLE Mobile to launch that app on the device.
     

2. Choose Scroll or Touch
   - Touch is for tapping or entering text on an element.
   - Vertical Scroll or Horizontal Scroll lets you scroll if the target element isn’t visible.
   

3. Select View Number or Device File

   • Scrolling

     If you selected Vertical Scroll or Horizontal Scroll see Recording Scroll Actions for scrolling.
   • If you selected Touch, you’ll see a table of on-screen elements (Views) and their attributes:
     • View: index number
     • Text: displayed text
     • ID: the element’s identifier
     • Desc: descriptive text for accessibility, etc.
     • Actions: Touch, Long Touch, or Send Text
   • Pick the element you would like to interact with, then Continue.
     

4. Select Your Action

   • Touch: Tap the element (e.g., pressing a button).
   • Long_Touch: Long-press the element (e.g., holding down on a file).
   • Send_Text: Enter text into a field (e.g., username or password).
     

5. Label Your Task

   • Provide a descriptive label (e.g., “Enter Username”).
   • This label helps identify the task within the console log during a deployment.
     

6. After completion, MANTLE Mobile asks "Did the Correct Action Happen?"

   • Click Yes when you confirm the action was correct.

7. Continue or Finish

   • If you need more actions, select Yes to keep going.
   • If you choose No, MANTLE Mobile will generate the Configuration File with the recorded tasks.
     Save it with a .json extension.
     

Recording Scroll Actions

If you selected Vertical Scroll or Horizontal Scroll in Choose Scroll or Touch, you’ll be asked to pick a root view (usually the first ID under “Root”).

1. Enter the following information:
   • Text to Search For: The text MANTLE Mobile will look for while scrolling.
   • Max Number of Swipes: How many times it will scroll before giving up.
   • Long Hold the Selection?: Choose “Yes” for a long-press, or “No” for a normal tap.
   • On your device, scroll back to the top, then click Continue in MANTLE Mobile.
     
   • Watch the device to ensure the correct value is found while scrolling.

Understanding Views

A “View” is any element displayed on the screen. It can have various attributes:

• Text: The text the element shows (e.g., a button label).
• ID: An identifier assigned by the app developer.
• Desc: A descriptive string, often for accessibility or internal references.

MANTLE Mobile uses the first non-empty attribute (Text, ID, or Desc) as the “findType” value within each task of a Configuration File to locate the element during deployment.

Possible Actions

Each element has 3 options for how they can be interacted with.
- Touch: Simulate a tap on the element. (Pressing a button.)
- Long_Touch: Simulate a long-press. (Press and holding on a file in My Files to display additional options.)
- Send_Text: Type text into the element’s field. (Sending a username or password to a textfield.)

Per-Device Text Values

Custom Variables let you assign unique values (e.g., passwords or callsigns) to each device without exposing them in plain text in your Configuration File.
Additionally, they allow for a different text value to be sent for each device on the same SENT_TEXT step.

Setup Steps

1. In Device Management, Add New Device or Edit Selected Device.
2. • Name: The identifier you’ll refer to in a recorded step.
   • Value: The actual text to be sent for this device.

   Note

   Ensure every "Name" matches accross all devices and are in the same order.

   Click Add Custom Variable:

   

3. Enable Show Custom Variables to verify they’re assigned correctly:

4. Once custom variables have been added, you will be presented with them as options while using the Record feature within a Send_Text task. Choosing a Custom Variable will now send the value associated with it.
   

How It Works During Deployment

• Each device replaces the variable Name with its specific Value.
  Device A will enter “alpha,” while Device B enters “bravo” from a single task where "callsign" is specified.

Per-Device File Assignments

Device Files work similarly to **Custom Variables. They let you assign a unique file to each device. For example, each device might need a different .ovpn profile file.

Setup Steps

1. Import Unique Files

   • In the File Manager, import any needed files (e.g., multiple .ovpn files).
     

2. Assign Files to Devices

   • In Device Management, Add or Edit a device.
   • Under Device Files, pick which file belongs to that device.
     

3. Select the File in Recording

   • Once each device has a Unique File selected, you can use the Record feature.
   • Now, during a Touch task, scroll to the bottom of the “Select Your View Number or Device File” list and you will see additional values.
   • Look for entries starting with “File” (e.g., File1) and choose the one you would like to use for this task.
     

How It Works During Deployment

• Each device uses its assigned file automatically. If Device 1 has open_prof_1.ovpn and Device 2 has open_prof_2.ovpn, the same recorded “Touch File” task with "File1" specified will select it's assigned Unique File.

Editing Configuration Files

To edit existing Configuration Files, select the file you would like to edit and click Edit Selected Configuration File.

This will open a screen with every task listed for the selected Configuration File.

From here, you can Insert, Delete, and Edit tasks. When you select a task, the menu below Edit Selected Task will update with the options available for that task. To add options, you can select an option from the Add new field dropdown.
Once you are finished configuring a task, select Save Task Changes.
Once you are finished configuring all tasks withink the Configuration File, select Submit Changes as New Configuration File and you will be prompted to save.

Available options are:

• Label: (Required) This value is used to identify the task within the log during a provision.
• Task Type: (Required) There are 4 available Task Types:
  • View: Used to interact with the screen by touch or sending text with setText.
  • Device: Used to send device commands. (BACK or HOME).
  • Vertical Scroll: Allows for scrolling down to touch a field with a specified text value.
  • Horizontal Scroll: Allows for scrolling right to touch a field with a specified text value.
    For Scroll tasks, the following additional fields are required:
    • Maximum Swipes: Set the maximum amount of swipes to look for the Find value before failure.
    • Scroll ID: Specify the ID of the window to scroll within. This can be found when creating a Scroll task via Record.
    • Press and Hold: When the Find value is found during a scroll, specify how many milliseconds to hold the selection.
• Find: (Required for View and Scroll tasks) Used to specify the field to interact with by the Find Type.
• Find Type: (Required for View tasks) Used to specify what type of value the Find value can be found by (ID, TEXT, or DESCRIPTION).
• Action: (Required for View and Device tasks) Used to specify how to interact with the found value (touch, setText, BACK, HOME).
• Text to Send (Required for setText) Used to set what text is sent to a specified Text Field.
• Wait After Execute: Used to specify an amount of seconds to wait before executing the next task.
• Optional: Used to set a task as optional. Optional tasks will attempt to execute an amount of tries specified by Maximum Attempts before continuing to the next task if unsuccessful. This is useful for handling pop-ups that only occur occasionally.
• OS Limit: Used to restrict a task to only execute for the specified Android OS version(s).
• Model Limit: Used to restrict a task to only execute for the specified Device Model(s).
• Reboot: Used for tasks that trigger a reboot. After executing a Reboot task, the provision will pause and wait for the device to finish rebooting before continuing to the next task.
• Conditional: (Advanced) Conditional tasks will attempt to find the outer task view up to the Maximum Attempts. If the view is not found, it will search for the Conditional View Value by the Conditional View Type. On the condition that this view is found, the tasks configured within Edit Conditional Tasks will execute before attempting to find the outer task view again. This is useful for occasional pop ups that require multiple tasks to clear.
  For configuring conditional tasks, see Advanced Configuration File Features.

Creating Conditional Tasks

Conditional tasks will attempt to find the outer task view up to the Maximum Attempts. If the view is not found, it will search for the Conditional View Value by the Conditional View Type. On the condition that this view is found, the tasks configured within Edit Conditional Tasks will execute before attempting to find the outer task view again. This is useful for occasional pop ups that require multiple tasks to clear.

A conditional workflow can be configured manually by inserting tasks, or by using the Record feature by selecting Record Conditional Tasks.

To Record Conditional Tasks:
- Ensure the obscuring screen is visible on the device and press Yes to continue.

- Select a view to identify the Condition to begin the conditional tasks. (Example: The title of a pop-up.). Select Continue. - You will then begin recording the tasks that are to be executed to remove the obscurring window. (See Recording). - Once complete, you will be prompted to save a new Configuration File. This new file will be identical to the original failed Configuration File with a conditional task replacing the original failed task. With this new Configuration File, on devices where this pop-up occurs, the tasks you recorded will execute to remove the pop up. Devices without this pop up will continue as normal.