Tasks Overview

What is a Task?

A task is the fundamental execution unit in a workflow. Each task represents a single action performed on an Android device — executing a shell command, sending an HTTP request, comparing values, detecting errors, and more.

Tasks are the nodes of the workflow graph. The execution engine traverses this graph from the START node and runs each task in order until it reaches an END node.

Three Types of Tasks

AndroMate distinguishes three categories of tasks, which differ in how they connect to the rest of the workflow.

1. Normal Tasks

A normal task performs a specific action and has exactly one outgoing link. Once it finishes, the engine unconditionally moves to the next task defined by the "to" field.

Examples: CmdStage, HttpRequest, Sleep, TextReport, GetCurrentLocation, DnsLookup, SetVariable, NtpSync, ScreenAutomator, etc.

JSON link format:

{
  "from": "1",
  "to": "2"
}

Execution flow:

[Task 1] ──→ [Task 2] ──→ [Task 3] ──→ ...

Task Exceptions

Every normal task can raise an exception if something goes wrong (network failure, device error, timeout, invalid input, etc.). The runtime engine stores this exception in the execution context and associates it with the task that raised it.

An exception contains:

Field	Description
Error code	A numeric or string identifier for the error type
Description	A human-readable message explaining what went wrong
Task ID	The ID of the task that failed

The workflow does not stop automatically on an exception (unless the execution policy is STOP_ON_ERROR). You can explicitly inspect the last exception using the dedicated conditional task: Exception ?.

2. Conditional Tasks

A conditional task evaluates a condition and returns a boolean result (true or false). Based on this result, the engine routes execution to one of two different branches.

Examples: CompareStrings, CompareNumber, AndromateException

JSON link format:

{
  "from": "2",
  "true": "3",
  "false": "4"
}

Meaning:

Condition in task 2 evaluates to true → execute task 3
Condition in task 2 evaluates to false → execute task 4

Execution flow:

[Conditional Task]
    ├─→ TRUE  ──→ [Branch A]
    └─→ FALSE ──→ [Branch B]

Available Conditional Tasks

JSON Key	Display Name	Description
`CompareStrings`	Compare Strings	Compares two string values
`CompareNumber`	Compare Number	Compares two numeric values
`AndromateException`	Exception ?	Checks if the previous task raised an exception

3. Connector Tasks

A connector task looks like a normal task from the outside — it has exactly one outgoing link ("to"), and the engine always continues to it once the connector task finishes. What makes it different is that a connector task wraps a nested sub-workflow, embedded directly inside its own JSON entry under a "do" key, and runs that sub-workflow some number of times before continuing.

This is AndroMate's native way to express a loop — as an alternative to the manual technique of wiring a Links entry back to an earlier task id (still valid and still the only option for conditional/retry-style loops).

Examples: Iterate, ForEachElement

JSON link format (outer graph):

{
  "from": "1",
  "to": "2"
}

Same as a normal task — the connector task's own looping is entirely internal; it never introduces extra outgoing paths in the outer graph.

The nested sub-workflow ("do"):

{
  "do": {
    "StartSubTask": [{ "id": "sub-0" }],
    "TextReport": [{ "id": "sub-1", "texte": "iteration", "texte_type": 0 }],
    "End": [{ "id": "sub-100" }],
    "Links": [
      { "from": "sub-0", "to": "sub-1" },
      { "from": "sub-1", "to": "sub-100" }
    ]
  }
}

The sub-workflow's entry point is StartSubTask, not Start — it only carries an "id", no variables/Time_out/exec_policy (those belong solely to the outer workflow's real Start).
It has its own End and Links, scoped to the sub-workflow's own task ids — give sub-workflow ids a distinct naming pattern (e.g. a sub- prefix) so they never collide with outer graph ids.
Any task type can be used inside "do", including another connector task (nested loops).
Variables are shared, not scoped: the sub-workflow reads and writes the exact same variable dictionary as the outer workflow. A variable declared in the outer Start.variables is visible inside "do", and any output produced by a task inside "do" is immediately visible to tasks after the connector task in the outer graph.

Execution flow (Iterate example):

[Connector Task] ──runs "do" sub-workflow N times──┐
                                                     │
        ┌────────────────────────────────────────────┘
        ▼
[Next Task in outer graph] ──→ ...

Available Connector Tasks

JSON Key	Display Name	Description
`Iterate`	Iterate	Runs the `"do"` sub-workflow once per integer from `start_index` to `end_index` inclusive, exposing the current value in `iteration_variable_input`
`ForEachElement`	For Each Element	Runs the `"do"` sub-workflow once per element of a list variable, exposing the current element in `element_variable_input`

See the Iterate and For Each Element task pages for full parameter and exception details.

The `Exception ?` Task (`AndromateException`)

The Exception ? task is a special conditional task dedicated to error handling. It inspects the execution context to determine whether the last executed task produced an exception.

Returns true — the previous task failed (an exception was raised)
Returns false — the previous task completed successfully (no exception)

Place it after any task that could fail to detect errors and branch accordingly. It can also capture the exception details into workflow variables for reporting or further processing:

JSON Field	Description
`code_output`	Variable to store the error code
`description_output`	Variable to store the error description
`task_id_output`	Variable to store the ID of the failed task

JSON example:

{
  "CmdStage": [
    {
      "id": "1",
      "title": "Run Ping",
      "cmd_text": "ping -c 1 8.8.8.8"
    }
  ],

  "AndromateException": [
    {
      "id": "2",
      "title": "Exception ?",
      "code_output": "$error_code",
      "description_output": "$error_desc",
      "task_id_output": "$failed_task_id"
    }
  ],

  "TextReport": [
    {
      "id": "3",
      "title": "Log Error",
      "texte": "Task $failed_task_id failed: [$error_code] $error_desc"
    },
    {
      "id": "4",
      "title": "Log Success",
      "texte": "Ping completed successfully"
    }
  ],

  "End": [{ "id": "100", "title": "End" }],

  "Links": [
    { "from": "0", "to": "1" },
    { "from": "1", "to": "2" },
    { "from": "2", "true": "3", "false": "4" },
    { "from": "3", "to": "100" },
    { "from": "4", "to": "100" }
  ]
}

Workflow Execution as a Graph

Workflows are represented as directed graphs. The execution engine traverses them following this algorithm:

Start at the START node (entry point of the workflow)
Execute the current task
Determine the next node:
Normal task → follow the "to" link
Conditional task → evaluate the condition, then follow "true" or "false"
Connector task → run its nested "do" sub-workflow to completion (possibly multiple times), then follow the "to" link
Repeat from step 2 with the next node
Stop when reaching an END node

The graph supports loops (a conditional task pointing back to an earlier task), useful for retry logic or polling. A maximum of 5000 iterations is enforced to prevent infinite loops.

flowchart TD
    START([▶ START]) --> T1[Normal Task 1]
    T1 --> T2[Normal Task 2]
    T2 --> COND{Conditional Task}
    COND -->|TRUE| T3[Branch A Task]
    COND -->|FALSE| T4[Branch B Task]
    T3 --> END([⏹ END])
    T4 --> END

    style START fill:#e3f2fd
    style END fill:#c8e6c9
    style COND fill:#fff9c4
    style T3 fill:#e0f0e0
    style T4 fill:#ffe0e0

Link Format Summary

Task Type	JSON Fields	Outgoing Paths	Behaviour
Normal Task	`"from"`, `"to"`	1	Always continues to `"to"`
Conditional Task	`"from"`, `"true"`, `"false"`	2	Routes to `"true"` or `"false"` based on evaluation
Connector Task	`"from"`, `"to"` (outer) + `"do"` (nested sub-workflow)	1	Runs the `"do"` sub-workflow to completion, possibly multiple times, then always continues to `"to"`

Associated Normal Link

Every normal task is connected with a normal link. It has exactly one outgoing path — the workflow always continues to "to" regardless of the task result.

{ "from": "1", "to": "2" }

Field	Description
`"from"`	ID of the current normal task
`"to"`	ID of the next task to execute

Associated Conditional Link

Every conditional task is connected with a conditional link. It has exactly two outgoing paths — the engine evaluates the boolean result and routes accordingly.

{ "from": "2", "true": "3", "false": "4" }

Field	Description
`"from"`	ID of the conditional task
`"true"`	ID of the task to execute when the condition evaluates to `true`
`"false"`	ID of the task to execute when the condition evaluates to `false`

Associated Connector Link

Every connector task is connected with a normal link in the outer graph — exactly like a normal task, one outgoing path via "to". The looping behaviour lives entirely inside the task's own "do" field, not in the link.

{ "from": "1", "to": "2" }

Field	Description
`"from"`	ID of the connector task
`"to"`	ID of the next task to execute, once the `"do"` sub-workflow has finished running