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.

---

Two Types of Tasks

AndroMate distinguishes two 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

---

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:

1. Start at the START node (entry point of the workflow)
2. Execute the current task
3. Determine the next node:
4. Normal task → follow the "to" link
5. Conditional task → evaluate the condition, then follow "true" or "false"
6. Repeat from step 2 with the next node
7. 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

---

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