Automation Run Scripts

Automation Run Scripts allow administrators to automate interactions with the Android device UI using JavaScript. These scripts can perform actions such as clicking buttons, entering text, scrolling through screens, enabling settings, and navigating between applications without requiring physical access to the device.

Automation is particularly useful for configuring applications, completing setup wizards, automating repetitive tasks, or performing UI-based operations that are not available through device APIs.

Prerequisites

Before using Automation Run Scripts, ensure the following requirements are met:

• Accessibility Service is enabled on the target device.
• Device is enrolled in Device Owner (DO) or Device Administrator (DA) mode.
• SureMDM Agent version 29.61.05 or later is installed.

Important

Automation APIs depend on Android Accessibility Services. If Accessibility permission is not granted:

• performAction() cannot execute the requested action.
• Run Script jobs return a failure acknowledgement.
• Custom Property scripts silently skip the automation step.

How Automation Works

Every automation script follows the same workflow:

1. Create an automation task.
2. Execute the task.
3. Optionally perform another task when the current one completes.

Create Task  
     ↓  
Execute Task  
     ↓  
Success Callback  
     ↓  
Next Task  

Each automation action is represented as a Task object.

A task only describes what should happen. It does not execute until it is passed to performAction().

Step 1: Create a Task

Use one of the Automation API factory methods to create a task.

Syntax

var task = suremdmjs.automate().<action>(<parameters>);

Example

var task = suremdmjs.automate().click(
   "com.example.app",
   "Confirm"
);

The above example creates a task that clicks the Confirm button inside the specified application.

Step 2: Execute the Task

After creating the task, execute it using performAction().

The API provides two execution modes depending on where the script is used.

Run Script Mode

Use the following syntax inside a Run Script job.

suremdmjs.automate().performAction(
   task,
   "onSuccess",
   "onFailure"
);

Understanding Callbacks

Automation tasks execute asynchronously.

Once a task completes, performAction() can invoke callback functions to continue the automation flow.

Callbacks enable multiple UI actions to execute one after another instead of simultaneously.

Success Callback

Executed when the automation task completes successfully.

function onSuccess() {
   // Execute next task
}

Failure Callback

Executed when the task fails or times out.

function onFailure() {
   suremdmjs.log("Action failed");
}

Callback Rules

Rule	Description
Callback functions are optional	Pass an empty string ("") if not required.
Callback names must be passed as strings	"onSuccess"
Inline or anonymous functions are not supported	Define callbacks separately.
Use callbacks to build sequential workflows	Each task starts after the previous task succeeds.
Use RS_TASK only for the last automation step in a Run Script	Indicates completion of the automation job.

Important

Callback parameters must reference named JavaScript functions already defined in the script.

Available Automation Actions

The Automation API provides the following task methods.

Method	Description	Default Timeout
click()	Click a UI element by visible text	30 seconds
clickWithTimeout()	Click a UI element using a custom timeout	Custom
typeText()	Enter text into a field identified by label or hint	30 seconds
checkbox()	Check or uncheck a checkbox	30 seconds
search()	Wait until one of the specified texts appears	Custom
scrollUntilClick()	Scroll until an element is found and click it	20 seconds
scrollUntilCheck()	Scroll until an element is found without clicking	20 seconds
swipe()	Swipe up, down, left, or right	30 seconds
clickCoordinates()	Tap a screen location using X and Y coordinates	20 seconds
goBack()	Simulate the Android Back button	—
goHome()	Simulate the Android Home button	—

Writing Your First Automation Script

Every Automation Run Script must begin with the SureMDM JavaScript header.

!#suremdmjs

Example: Click a Button

The following example clicks an OK button and logs whether the operation succeeded.

!#suremdmjs
run();
 
function run() {
    var task = suremdmjs.automate().click("", "OK");
    suremdmjs.automate().performAction(task, "onOKClicked", "onOKFailed");
}
 
function onOKClicked() {
    suremdmjs.log("OK clicked successfully");
}
 
function onOKFailed() {
    suremdmjs.log("OK button was not found");
}

tip

Specify an application package name to search within a particular application. Pass an empty string ("") to search across all applications.

Chaining Multiple Actions

Complex automation is created by executing the next task inside the success callback of the previous task.

This ensures that each UI action starts only after the previous one has completed successfully.

The following example:

1. Enters the username
2. Enters the password
3. Clicks Sign In

!#suremdmjs
loginToApp();
 
function loginToApp() {
    var task = suremdmjs.automate().typeText("com.example.app", "Username", "admin");
    suremdmjs.automate().performAction(task, "onUserTyped", "");
}
 
function onUserTyped() {
    var task = suremdmjs.automate().typeText("com.example.app", "Password", "P@ssword1");
    suremdmjs.automate().performAction(task, "onPassTyped", "");
}
 
function onPassTyped() {
    var task = suremdmjs.automate().click("", "Sign In");
    suremdmjs.automate().performAction(task, "onSignedIn", "onSignInFailed");
}
 
function onSignedIn()    { 
    suremdmjs.log("Login successful"); 
}


function onSignInFailed(){ 
    suremdmjs.log("Sign In button not found"); 
}

Examples

The following examples demonstrate common automation scenarios.

Example 1: Configure SureLock Settings

This example:

• Navigates back through multiple screens
• Enters the SureLock administrator password
• Opens SureLock Settings
• Verifies that the Suppress Notification Panel option is visible
• Marks the final automation step using RS_TASK

!#suremdmjs
var task = suremdmjs.automate().goBack();
suremdmjs.automate().performAction(task, "pressBack", "");
 
function pressBack() {
    var t = suremdmjs.automate().goBack();
    suremdmjs.automate().performAction(t, "pressBack1", "");
}
function pressBack1() {
    var t = suremdmjs.automate().goBack();
    suremdmjs.automate().performAction(t, "pressBack2", "");
}
function pressBack2() {
    var t = suremdmjs.automate().goBack();
    suremdmjs.automate().performAction(t, "enterPassword", "");
}
 
function enterPassword() {
    // 3-second delay so the password dialog fully renders before we type
    setTimeout(function() {
        var t = suremdmjs.automate().typeText("com.nix", "Enter Password…", "0000");
        suremdmjs.automate().performAction(t, "onClickOK", "");
    }, 3000);
}
 
function onClickOK() {
    var t = suremdmjs.automate().click("", "OK");
    suremdmjs.automate().performAction(t, "onClickSurelockSettings", "");
}
 
function onClickSurelockSettings() {
    var t = suremdmjs.automate().click("", "SureLock Settings");
    suremdmjs.automate().performAction(t, "enableSuppressNotification", "");
}
 
function enableSuppressNotification() {
    // Final step — pass "RS_TASK" to signal RunScript job completion
    var t = suremdmjs.automate().scrollUntilCheck("", "up", "Suppress Notification Panel", true);
    suremdmjs.automate().performAction(t, "RS_TASK", "", "");
}

Example 2: Scroll to a Setting and Enable It

This example:

• Scrolls to Developer Options
• Enables the Stay Awake checkbox
• Returns to the previous screen

!#suremdmjs
applyOption();
 
function applyOption() {
    var task = suremdmjs.automate().scrollUntilClick("", "down", "Developer Options");
    suremdmjs.automate().performAction(task, "onDevOptionsOpen", "");
}
 
function onDevOptionsOpen() {
    var task = suremdmjs.automate().checkbox("", "Stay awake", true);
    suremdmjs.automate().performAction(task, "onChecked", "");
}
 
function onChecked() {
    var task = suremdmjs.automate().goBack();
    suremdmjs.automate().performAction(task, "RS_TASK", "", "");
}

Example 3: Wait for Application Installation

This example waits up to five minutes for any installation completion message before returning to the home screen.

!#suremdmjs
waitForInstall();
 
function waitForInstall() {
    // Wait up to 5 minutes for any known completion message
    var task = suremdmjs.automate().search("", "Installation complete|App installed|Done", 300000);
    suremdmjs.automate().performAction(task, "onInstalled", "onInstallTimeout");
}
 
function onInstalled() {
    suremdmjs.log("App installed — returning to home screen");
    var task = suremdmjs.automate().goHome();
    suremdmjs.automate().performAction(task, "", "");
}
 
function onInstallTimeout() {
    suremdmjs.log("Installation did not complete within 5 minutes");
}

If none of the messages appear before the timeout expires, the failure callback is executed.

tip

Separate multiple search values using the pipe (|) character.