Automation Run Scripts

Automation Run Scripts enable administrators to automate user interface (UI) interactions on Android devices using JavaScript. Instead of manually interacting with a device, administrators can create automation scripts to perform repetitive tasks such as tapping buttons, entering text, scrolling through screens, navigating between pages, or interacting with Android applications.

Automation Run Scripts are especially useful when a required operation cannot be performed using standard SureMDM jobs or Android management APIs. By simulating user interactions through Android Accessibility Services, administrators can automate complex workflows and reduce the need for manual intervention.

Some common use cases include:

Configuring application settings after deployment.
Completing application setup or onboarding wizards.
Granting runtime permissions.
Automating login or registration processes.
Enabling or disabling application options.
Performing repetitive UI tasks across multiple devices.

Automation actions are created using the suremdmjs.automate() API and executed through the performAction() method. Multiple automation actions can also be combined to create complete workflows.

Prerequisites

Before creating or executing Automation Run Scripts, ensure that the following requirements are met.

Requirement	Description
Accessibility Service	SureMDM Accessibility Service must be enabled on the target Android device. Automation actions rely on Accessibility APIs to interact with the device UI.
Device Enrollment	The Android device must be enrolled in SureMDM in Device Owner (DO) or Device Administrator (DA) mode.
SureMDM Agent Version	SureMDM Agent version 29.61.05 or later must be installed on the device.
JavaScript Header	Every Automation Run Script must begin with the *!#suremdmjs* header.
Basic JavaScript Knowledge	Familiarity with JavaScript functions and callbacks is recommended for creating advanced automation workflows.

Important

Automation Run Scripts depend on Android Accessibility Services. If the SureMDM Accessibility Service is disabled or permission has not been granted:

Automation actions cannot interact with the device UI.
performAction() will not execute the requested automation task.
Run Script jobs will return a failure acknowledgement.
Any automation logic included within a Custom Property script will be skipped.

Before You Begin

Before writing your first Automation Run Script, it is helpful to understand how automation works. Unlike regular JavaScript functions, automation actions are not executed immediately when they are created. Each automation action first creates a Task object that describes the action to perform.

The task is executed only after it is passed to the performAction() method.

This design allows SureMDM to execute UI actions sequentially, wait for each action to complete, and continue with the next step only after the current action succeeds.

How Automation Works

Every Automation Run Script follows the same workflow.

Create Automation Task
          │
          ▼
Execute Task using performAction()
          │
          ▼
Wait for Automation Result
          │
     ┌────┴────┐
     ▼         ▼
  Success    Failure
     │         │
     ▼         ▼
  Execute    Handle
  Next Task   Error

The automation process consists of four simple steps.

Step 1 – Create an Automation Task

Choose an automation method based on the action you want to perform, such as clicking a button, entering text, scrolling the screen, or navigating back.

Each method creates a Task object.

Example:

var task = suremdmjs.automate().click("","OK");

At this stage, no action is performed on the device. The script has only prepared an automation task.

Step 2 – Execute the Task

To perform the automation, pass the task to the performAction() method.

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

The automation engine executes the requested action and waits until it completes.

Step 3 – Receive the Result

After execution, one of the callback functions is invoked.

Success Callback – Executed when the automation action completes successfully.
Failure Callback – Executed if the action fails or the requested UI element cannot be found within the timeout period.

Step 4 – Continue the Workflow

If additional actions are required, create and execute the next automation task inside the success callback. This approach ensures that each UI action is completed before the next one begins.

Understanding Automation Tasks

An Automation Task represents a single UI action that should be performed on the Android device.

Examples of automation tasks include:

Clicking a button.
Entering text into a text field.
Selecting a checkbox.
Swiping the screen.
Navigating back.
Pressing the Home button.

Creating a task does not perform the action immediately.

For example:

var task = suremdmjs.automate().click("","Allow");

The above code only creates a task that describes the action. To execute the task, it must be passed to performAction().

Understanding performAction()

The performAction() method executes an automation task created by one of the Automation APIs.

Syntax

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

Parameters

Parameter	Description
task	The automation task created using an Automation API.
onSuccess	Name of the JavaScript function to execute after the task completes successfully. Pass an empty string ("") if no success callback is required.
onFailure	Name of the JavaScript function to execute if the task fails or times out. Pass an empty string ("") if no failure callback is required.

Example

var task = suremdmjs.automate().click("","Continue");

suremdmjs.automate().performAction(task,"nextStep","showError");

Understanding Callback Functions

Automation actions execute asynchronously. This means the script continues running while the automation engine performs the requested action in the background.

Callback functions allow your script to respond after the automation has finished.

Success Callback

The success callback is executed when the automation action completes successfully.

function onSuccess() {
    suremdmjs.log("Action completed successfully.");
}

Use the success callback to execute the next automation task.

Failure Callback

The failure callback is executed when the requested action cannot be completed.

This may happen because:

The requested UI element does not exist.
The element does not appear before the timeout expires.
Accessibility permission is disabled.
The application is not in the expected state.

Example:

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

Callback Best Practices

Always define callback functions before using them in your script.
Use meaningful function names that describe the next action.
Chain automation tasks through success callbacks to ensure they execute in sequence.
Handle failures gracefully by logging an appropriate message or performing recovery actions.
If no callback is required, pass an empty string ("").

Available Automation Actions

The Automation API provides the following task methods.

Method	Description	Default Timeout
click()	Find element by text → click	30 seconds
clickWithTimeout()	Find element by text → click using a custom timeout	Custom
doubleClick()	Find element by text → double-click	30 seconds
search()	Find any candidate text (pipe-separated) — no click	Custom
checkbox()	Check or uncheck a checkbox by label	30 seconds
swipe()	Swipe up, down, left, or right	30 seconds
swipeCoordinates()	Swipe from one "x,y" position to another	20 seconds
scrollUntilClick()	Scroll until element is found → click	20 seconds
scrollUntilClick()	Scroll until element is found → click using a custom timeout	Custom
scrollUntilCheck()	Scroll until element is found or gone, then check/uncheck it	Custom
clickCoordinates()	Tap at "x,y" screen position	20 seconds
doubleTapCoordinates()	Double-tap at "x,y" screen position	20 seconds
longPress()	Find element by text → long press	30 seconds
longPressCoordinates()	Long press at "x,y" screen position	20 seconds
keyEvent()	Inject hardware key event by key code	—
pinchIn()	Pinch-in (zoom out) at screen center	—
pinchOut()	Pinch-out (zoom in) at screen center	—
goBack()	Press Back button	—
goHome()	Press Home button	—
typeText()	Focus field by label → type text	30 seconds

Writing Your First Automation Run Script

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

Example: Click a Button

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

The script starts with the SureMDM JavaScript header.
The run() function creates an automation task to click the OK button.
The task is executed using performAction().
If the button is found and clicked, the onSuccess() function is executed.
If the button cannot be found or the action fails, the onFailure() function is executed.

!#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:

Enters the username.
Enters the password.
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

!#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, "", "");
}

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, "", "");
}

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.

Prerequisites​

Before You Begin​

How Automation Works​

Step 1 – Create an Automation Task​

Step 2 – Execute the Task​

Step 3 – Receive the Result​

Step 4 – Continue the Workflow​

Understanding Automation Tasks​

Understanding performAction()​

Understanding Callback Functions​

Success Callback​

Failure Callback​

Callback Best Practices​

Available Automation Actions​

Writing Your First Automation Run Script​

Example: Click a Button​

Chaining Multiple Actions​

Examples​

Example 1: Configure SureLock Settings​

Example 2: Scroll to a Setting and Enable It​

Example 3: Wait for Application Installation​