---
alias: user-guide-automation-tasks-index
render_macros: false
tags:
- automation tasks
description: "Tasks are visual blocks with names, inputs, and outputs, enabling specific actions within workflows"
---

# Tasks

A **Task** is a visual block that performs a specific function. In programming terms, it can be described as a function or a method, because it has a name, input and output values, and performs an action.

The images below show the **Code** task in the Data Flow Designer, the Control Flow Designer, and its settings page.

=== "Data Flow"

    ![Data Flow Task Example (Code Task)](./images/code-task-data-flow.png)

    1. Name
    2. Description
    3. ID
    4. Settings (button)
    5. Inputs
    6. Outputs

=== "Control Flow"

    ![Control Flow Task Example (Code Task)](./images/code-task-control-flow.png)

    1. Task in Workflow Designer
    2. Task Details Pane
    3. Settings (button)
    4. Name
    5. Caption
    6. ID
    7. Color, driver, and task settings
    8. Inputs
    9. Outputs

=== "Settings"

    ![Task (Code Task) Settings Example](./images/code-task-settings.png)

    The settings wizard is the same in both designers. The **General** tab holds the name, description, color, and when applicable the driver of the task, the inputs and outputs tabs (named **Inputs** and **Outputs** by default) hold its inputs and outputs, and the remaining tabs hold task-specific settings, such as **Code** for the Code task.

## Workflow Types

Data Flow and Control Flow are two workflow types, each with its own designer and execution model:

- Data Flow connects tasks through data links, so information visibly flows from task to task as the workflow runs. It does not require a single deterministic start and finish, and one task can trigger several others in parallel.
- Control Flow arranges tasks as a sequence of statements with an enforced start and finish, closer to a program. It focuses on the order in which actions happen rather than on the movement of data between them.

The same task can behave differently per workflow type, as described below. Also, a task available in only one workflow designer may not appear in the task list of the other one. For instructions or details on how to set up a workflow (data flow or control flow), see the [[user-guide-automation-controller-workflow-custom]] guide.

When a task reference page includes a **Details** table, the **Workflow** row of that table states which designers the task supports.

### Data Flow

The task is drawn as a block with one port per input and one port per output. You wire the ports to other tasks, and the order of execution follows the links you draw. A non-event task runs when its `Activate` input receives a true value, and several branches can run in parallel from the same output.

![Data Flow Designer with File Driver Setup tasks](./images/designer-data-flow.png)

### Control Flow

The task is drawn as a statement in a sequence. Inputs become arguments you fill in on the block or on the right pane, and outputs become values later statements can read. The task runs when the preceding task completes, so there is no `Activate` port to wire.

![Control Flow Designer with File Driver Setup tasks](./images/designer-control-flow.png)

Each task declares how it is rendered in this designer. The block type sets the role of the task in the sequence. The following table presents the supported block types:

| Type          | Role                                                                                 |
| ------------- | ------------------------------------------------------------------------------------ |
| `Start`       | Starts the workflow. A trigger task, such as **On Equipment Event**, uses this type. |
| `Function`    | Runs one step and continues with the next one. Most tasks use this type.             |
| `ControlFlow` | Directs the sequence through branches, as **Condition** and **Switch** tasks do.     |
| `End`         | Ends the workflow.                                                                   |

Table: Control Flow block types

The caption of the block is a sentence rather than the task name, and it can include the value of a setting, an input, or an output. For example, a **Condition** block is captioned with the condition it evaluates, so the sequence reads as a description of what the workflow does.

A `ControlFlow` block also declares its branches, which are the paths the sequence can take out of the block.

!!! note
    Errors are not handled by wiring the Error output as in Data Flow. Place the statements inside a [[user-guide-automation-task-core-try-catch|TryCatch]] block, which intercepts the exceptions raised by the statements it contains.

### Choosing a Designer

For the questions that decide the designer of a workflow, in the order to ask them, see [[user-guide-automation-controller-workflow-custom#choosing-the-designer]].

## Behavior

A task is activated in one of the following ways:

- **Event-Driven Triggering** - an event handler task activates automatically when its configured trigger fires. Triggers include driver events, scheduled time intervals, and external API calls.
- **Explicit Activation via Input Parameter** - in Data Flow workflows, a non-event-driven task activates when its `Activate` input is triggered with a true value.
- **Sequential Control Flow Action** - in Control Flow workflows, a non-event-driven task activates when the preceding statement completes successfully.

Some tasks may deviate from these activation methods. Refer to the documentation of the task for its trigger and input parameter details.

The behavior of a task can vary depending on its nature, settings, and input values. Typically, upon successful execution, the Success output emits a true value. In Data Flow, if the task fails, the Error output emits an error object, which is a data structure that describes the error.

On the task settings page, you can set the name and description of the task, the color used to draw it, and settings specific to that task. See [Name, Description, and Caption](#name-description-and-caption) for how the name, the description, and the Control Flow caption are used.

!!! hint "Use task colors"
    Use task colors as a visual aid. For example, color tasks that result in errors or failures red, and tasks that indicate success green. Driver tasks have a predefined color that you can override.

## Name, Description, and Caption

Every task instance has a name and a description, set on the *General* tab of its settings page. In Control Flow, the block also has a caption. These fields do not change how the task executes, with one exception: in Control Flow, the name is the identifier that other blocks use to read the outputs of the task.

### Task Name

The name is a label for this instance of the task.

- **Data Flow** - the name is the header of the block on the canvas. It also identifies the task in the title of the settings dialog, in the debugger, and in the list of outdated tasks of the **Update Controller Versions** wizard. It defaults to the task type name, for example, `Code` and it is descriptive only.
- **Control Flow** - the name is the identifier used to reference the outputs of the block in the expressions of later blocks, as `{{ $<name>.<output> }}`. The designer generates a unique default, such as `code_7c08`, and the expression editor lists the outputs of the preceding blocks under `$<name>`. Give the block a meaningful name when a later block needs its output, for example, name it `readIdentification` so that the next block can use `{{ $readIdentification.reply }}`.

!!! warning
    In Control Flow, use names without spaces and set the name before writing the expressions that reference it. After renaming a block, review the expressions of the later blocks that used the previous name.

### Task Description

The description is free text that documents what this instance does in the workflow. It is not used at runtime.

- **Data Flow** - the description is shown under the name of the block. The **Connect Entity** wizard fills it automatically with the name of the equipment event on the first task and the name of the equipment command on the last task of the workflows it generates, which is its intended use: stating which event or command the block handles.
- **Control Flow** - the description is kept with the block and edited in the settings wizard, but it is not shown on the block. Use it for review notes or to record the reason behind a setting that is not obvious.

### Task Caption

The caption exists only in Control Flow. It is the sentence the block displays in the sequence. Each task ships a default caption template, for example, `Send {{command}} message to driver connection` for the **Driver Command** task, where each `{{<setting>}}` token is rendered as an input you can edit in place. A task without a template is captioned with its display name.

Edit the caption so that the sequence reads as a description of what the workflow does, for example, `Connect to the equipment` or `Log {{message}} when the file arrives`, and keep the tokens for the values you still want to edit on the block. The [[user-guide-automation-controller-workflow-custom-controlflow]] guide shows this edit step by step.

## Inputs and Outputs

Some tasks allow defining custom inputs or outputs. The custom entries are filled in specific tabs of the settings pages for each task. You can find a list of configured entries on the left side of each task, where you can also add new entries or remove existing ones. On the right side you will find the list of properties defined for the custom entry. Depending on the task, different properties may be required.

![Task (Code task) Inputs Configuration Example](./images/code-task-input-params.png)

!!! warning
    Due to current implementation limitations, input and output names must be unique within a task.

### Ports You Add

Some tasks cannot declare in advance the values they carry, so you add their ports: link an output to the `Link here to add new` input of the task, or add an entry on its inputs or outputs tab. The designer shows the new port under the name of the entry, but each task stores the port under a name of its own:

- Most tasks store the port under the name of the entry, for example **On Equipment Event**, **Execute Equipment Command**, **Get Equipment Properties**, **Set Equipment Properties**, **Store Data**, **Retrieve Data**, **Execute Service Call**, and the expression evaluators.
- The tasks in the following table add `In` to the name of an input and `Out` to the name of an output.

| Task | Stored input name | Stored output name | Designers |
|---|---|---|---|
| [[user-guide-automation-task-core-code]] | `<name>In` | `<name>Out` | Data Flow and Control Flow |
| [[user-guide-automation-task-core-getconfigurations]] | `<name>In` | `<name>Out` | Data Flow and Control Flow |
| [[user-guide-automation-task-core-resolvetable]] | `<name>In` | `<name>Out` | Data Flow and Control Flow |
| [[user-guide-automation-task-core-workflow]] | `<name>In` | `<name>Out` | Data Flow and Control Flow |
| [[user-guide-automation-task-core-logmessage]], `MultipleInputs` mode | `<name>In`. In Control Flow, the task also reads a row named `<name>` | - | Data Flow and Control Flow |
| [[user-guide-automation-task-core-workflowstart]] | - | `<name>Out` | Data Flow |
| [[user-guide-automation-task-core-synchronize]] | `<name>In` | `<name>Out` | Data Flow |
| [[user-guide-automation-task-core-mergeobject]], [[user-guide-automation-task-core-mergearray]] | `<name>In` | - | Data Flow |

Table: Tasks that add a suffix to the ports you add

Use the stored name wherever you write a port name:

- In Data Flow, a link targets the stored name, and the designer writes it for you.
- In Control Flow, name an input row with the stored input name, and read an added output with `{{ $<task name>.<stored output name> }}`, for example `{{ $classify.statusOut }}` for the output `status` of a **Code** task named `classify`.
- Inside a **Code** task, the code uses the declared names, without the suffix: `inputs.size` for an input `size`, and `return { status: value }` for an output `status`.
- When you move a workflow to the other designer, check the stored name of every added port in the target designer.

A row or an expression that uses a name the task does not read raises no error: the value does not arrive, and the task runs on a default value or logs `<null>`.

## Experimental and Deprecated Tasks

A task is marked as experimental when its availability is not certain. This happens when the task depends on general acceptance and use, or when a new and improved solution may replace it.

A task is marked as deprecated when it is going to be discontinued in the next major version.

These different states are visually signaled and color-coded within the Workflow Designer, as shown in the examples below:

| State | Selection Tile | Workflow Designer |
|:-----:|:-------------:|:-----------------:|
|Experimental|![Experimental Task](./images/task_experimental_selection.png)|![Experimental Task - Workflow Designer](./images/task_experimental_designer.png)|
|Deprecated|![Deprecated Task](./images/task_deprecated_selection.png)|![Deprecated Task - Workflow Designer](./images/task_deprecated_designer.png)|

Table: Deprecated and Experimental Tasks