Automation Builder

On this page:

Transitions

Transitions connect tasks and control the order of task execution. Before adding a transition, a user must select a transition binding value (a loop or a leading task's finish state: success, error, or failure) and a transition direction (standard, revert).

Transition Binding Values

Transition states are based on the finish state of the task, or on a loop.

State Description
Finish This indicates if an automatic task encountered a problem. Also indicates if an evaluation task matches an evaluation expression. Finish state values are listed below.
Loop The forEach loop starts a sequence of tasks to be executed one or more times.

Finish State Values

The finish states for a leading task are success, error, or failure.

Value Description
Success - Indicates an automatic task did not encounter a problem.
- Can be a manual task associated with a success finish state, as specified by the developer.
- Also used to indicate if an evaluation task matches an evaluation expression.
Error - Indicates an automatic task has encountered a problem.
- Can be a manual task associated with an error finish state, as specified by the developer.
Failure - Indicates an evaluation fails to match an evaluation expression.
- Can be a manual task associated with a failure finish state, as specified by the developer.

Transition Direction

Transition direction refers to the direction of the transition.

Direction Description
Standard Transition moves job execution forward from Start to End.
Revert Transition moves job execution backwards toward Start. All previously completed tasks and their data from the revert point forward are reset (and will be re-executed), including the destination task of the revert transition. Note the following:
- Data is saved, not destroyed, but it is not used.
- Only one revert per transition binding is allowed from a single task.
- The job will resume executing at the destination task of the revert transition as if no subsequent tasks had executed.
- Care must be taken when using revert. When used with parallel branching, some tasks could potentially be executed multiple times which might yield undesirable results.

Transition Colors

Like tasks, transitions are color-coded.

  • Green transitions are bound to the success finish of the prior task state.
  • Red transitions are bound to the prior task error or failure finish states. (Place the cursor over the transition, and a tool tip reveals error or failure.)
  • Blue transitions are bound to a forEach operation task.
  • Solid lines represent standard transitions.
  • Dashed lines represent revert transitions.

Add a Transition to an Automation

On the Automation Builder canvas page, select a transition binding (example: success) from the Transition Binding dropdown.

  1. Select a transition direction (example: standard) from the Transition Direction dropdown.

  2. To add the new transition, click the Add transition button or press the "t" key to enter transition mode.

    Figure: Add Button

    Add Button

  3. To exit this mode, you must draw a transition or press the "y" key.

  4. Click the START terminator, drag cursor to your task, and release.

  5. Automation Builder will draw an arrow to connect the two (see figure below). After the transition is drawn, the Transition mode closes. You must repeat steps 3-4 to draw another transition.

    Figure: Transition Arrow

    Add Transition

Delete a Transition

To delete a transition:

  1. On the Automation Builder canvas, select the transition you want to delete.

  2. Click the Delete button (top right) or press the "d" key.

    Figure: Delete Button

    Delete Button

  3. Click SAVE (located at the bottom).

Parallel Branching

When using parallel branching, the control of a workflow becomes much more complicated. It is recommended to avoid parallel branching whenever possible.

In the workflow example below, there are two inputs to the Evaluation (Eval) task. It is impossible to know which of these two tasks will complete first, which is an inherent problem in parallel branching. Furthermore, the notion of having a path is relevant here. A path is defined as a series of tasks that occur sequentially beginning at the Start and culminating with the End. It is important to recognize that one task might be part of many paths, especially when parallel branching is utilized. Finally, determining the order of execution in the path becomes slightly more complex when a workflow contains both a revert transition and parallel branching. In these cases, when designing a workflow, you must separate how the workflow will look visually so as not to confuse how the workflow will run (flow) through its paths. When a revert transition occurs, all the tasks on the path from the revert's destination task to the "End" task will be reset and executed again. The information below will give further detail as to how task execution flows through a workflow with parallel branching.

Figure: Parallel Branching

Parallel Branching

Possible Outcomes for Multiple Inputs to a Task

When there are multiple incoming transitions to a task there are three possible outcomes: all inputs are received, one input is received, or none of the task inputs are received.

All Inputs Received

It is important to know that there is no "waiting" for the specific transition binding value to occur before a task executes; rather, a task will execute if all of its precursor tasks have executed and, in turn, have "chosen a path". Even if the chosen path is different from the one visually drawn on the canvas, as long as the previous task has executed or declared itself to never execute (see the Tasks that Never Run section below), then the workflow can proceed. Moreover, if all incoming transitions run, then the subsequent task will run (which in the example below means the incoming tasks succeeded).

Figure: Parallel Branching - All Transitions Successful

All Successful

One Input Received

When at least one of the incoming transitions occur, and even if all the other transitions are no longer possible, the subsequent task will still run. Keep in mind, that any task references that do not exist will evaluate as null. In the example below, this causes the Evaluation task to take the failure (red) transition path instead of the success (green) transition path.

Note: It is very important to recognize the potential for confusion here when designing workflows. At design time (above image), when the transition in the lower path between Stub and Eval shows success (green), the designer might assume that the only way the workflow advances is if that particular condition occurs. That is not the correct interpretation of how a workflow runs.

As shown below, the Stub task chose a path at runtime which is grey. This means the task run was completed, but since the result was not green (success), it has done as much as it can do. The upper path that was chosen (i.e. the "green" path) and the Evaluation task is now free to execute. In this case, the Evaluation task is conditional and will evaluate any references to the lower path's Stub variables as null.

Figure: Parallel Branching - One Transition Successful

One Successful

No Input Received

When neither of the incoming task succeeds, the subsequent task will never run. Furthermore, if this is the only task that goes to the "End", the job will fail.

Figure: Parallel Branching - No Transitions Successful

Zero Successful

Tasks that Never Run

The scenario above introduces the topic of a "task that never runs", and this section provides additional info to help explain this key concept.

If a task never runs, it will still notify the subsequent tasks to determine if they should run in the future, based on the logic for parallel branching. For example, if the workflow below were to run and the Stub task errors, it notifies all of its connected tasks from a different transition type (e.g. "success"), that these transitions will never be taken. If the next task will never run (i.e. the first Query along the bottom parallel path), it notifies its subsequent task that it will never run (e.g. the second Query along the bottom parallel path). Then that task notifies its subsequent task that it will also never run (i.e. the Evaluation task). This continues until the End is reached or a task that has multiple inputs. Due to this mode of operation, it becomes critically necessary that you give careful attention to any and all parallel paths to prevent a job from never completing (as illustrated here in this section).

Figure: Parallel Branching with Unused Transitions

Parallel Branching with Unused Transitions

Furthermore, if there is a case in parallel branching where it is one of two incoming tasks for a subsequent task and the other task succeeds, it will then run the subsequent task, even if it may not have all the necessary data to run successfully. The workflow below is an example of this. If the Stub task fails, it notifies the subsequent task (Query) that its transition will never run and that Query task in turn notifies the second Query task that its transition will never run. The Evaluation task will be notified that the bottom path will never run and, therefore, free to look to its other inputs to see if it can run. At this point, the Evaluation task just needs for the top path to run and once it does, it sets the references for the unexecuted Query task on the bottom path to null and performs the evaluation.

Figure: Parallel Branching with Unused Transitions in Runtime

Runtime Parallel Branching

Revert Transitions in Parallel Branching

It is also important to keep in mind how revert transitions behave when using parallel branching. In short, once a revert is triggered, all subsequent tasks on the path from the revert's destination task to the "End" will be executed from that point onward (even if they had already executed due to traversal of a different parallel path).

Warning: Use of a revert within a parallel branch can cause all subsequent workflow tasks to run multiple times (1 + the number of reverts). This is expected behavior, so please plan your workflows accordingly.

The following scenarios illustrate how reverts and parallel paths operate.

Example 1

In the workflow below, a task has two paths that lead to an Evaluation task (i.e., a "shared" Evaluation task). The top path contains its own Evaluation task, which in this scenario will fail the first time, then the job variable will be set to a value that is meant to cause the second run of the Evaluation task to succeed. However, the transition from that variable is a revert back to the "Evaluation", so it is only after the revert transition will the second execution of that "Eval" task yield a success.

Figure: Parallel Branching with Revert Transitions

Parallel Branches Revert

Due to the first execution of the Evaluation task, the top path fails and then goes to a task which has a revert transition. The first Evaluation task will notify the "shared" Evaluation task that the path between them will never run.

Example 2

While this is occurring, the bottom path executes and reaches the "shared" Evaluation task (the one where both the top and bottom paths meet) and will run for the first time. Since both of the previous tasks to the shared Evaluation task have chosen a path, the task will run but in this case fail because it does not have the correct data (the "shared" Evaluation task is expecting data from both paths). Consequently, a "failure" path to the Query task is executed, as illustrated below.

Figure: Parallel Branching with Revert Transitions in Runtime Before a Revert Transition

Job before Revert

Example 3

Lastly, when the top path hits the revert transition, it will reset all tasks subsequent to the first Evaluation task along its path and start executing again. This means the second Evaluation task will run a second time. In order to avoid scenarios like this, it is best to find an alternative to using revert within parallel branching, such as converting the workflow to run sequentially or using a child job to handle the revert logic.

Figure: Parallel Branching with Revert Transitions in Runtime After a Revert Transition

Job after Revert