.png?sv=2022-11-02&spr=https&st=2024-12-23T11%3A26%3A05Z&se=2024-12-23T11%3A36%3A05Z&sr=c&sp=r&sig=tNnnQ%2Bo%2FPrTukXW%2BaSbSM5%2B5QQ8%2FF04HIgIdb7v3XGc%3D){kind=logo}
How to Use Transitions and Task States in Gen 1
- 18 Oct 2024
-
DarkLight
-
PDF
How to Use Transitions and Task States in Gen 1
- Updated on 18 Oct 2024
-
DarkLight
-
PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
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 the finish state of a leading task: 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 in the next section. |
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. - Also used to indicate failure if a task ever returns undefined. |
Task Success, Failure, or Error
All tasks are able to return an Error or Success status. However, Evaluation tasks, Manual tasks, and Query tasks can return as a Failure. The differences between an Error and Failure are discussed in the next sections.
Task Failure
A task Failure is displayed on the Job Details page and will not show any output to identify what the issue was that caused the failure.
- A
Manualtask Failure can be triggered by manually working the task to send the workflow down a Failure transition. - An
Evaluationtask will show a Failure that has a False return. - A
Querytask can return either a Failure or an Error.
Task Error
An Error on the Job Details page will display an output message for what went wrong. This can be helpful for locating where the error occurred in the workflow and what troubleshooting may be needed.
- An issue in a
JSTtask will result in an Error. - An issue in a
Querytask can result in an Error or a Failure.
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.
How to Add Transitions to an Automation
On the Automation Builder canvas page, select a transition binding (example: success) from the Transition Binding dropdown.
- Select a transition direction (example: standard) from the Transition Direction dropdown.
- To add the new transition, click the Add transition button
or press the "t" key to enter transition mode. - To exit this mode, you must draw a transition or press the "y" key.
- Click the START terminator, drag cursor to your task, and release.
- 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 1: Transition Arrows on Workflow Canvas
How to Delete a Transition
To delete a transition:
- On the Automation Builder canvas, select the transition you want to delete.
- Click the Delete button (top right) or press the "d" key.
- Click SAVE (located in the bottom footer).
How to Use 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 2: 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 3: Parallel Branching - All Transitions 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.
Warning!
It is very important to recognize the potential for confusion here when designing workflows. In Figure 3, 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 4: Parallel Branching - One Transition 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 5: Parallel Branching - No Transitions 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 6: 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 7: Parallel Branching with Unused Transitions in Runtime
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 8: Parallel Branching with Revert Transitions
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 9: Parallel Branching with Revert Transitions in Runtime Before a Revert Transition
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 10: Parallel Branching with Revert Transitions in Runtime After a Revert Transition
Revert Transitions in Parallel Branching with Child Jobs
Another scenario involving revert transitions involves child jobs used within parallel branching. When reverting over a workflow which uses parallel paths, this may also revert over a running child job task. This will not stop the previously running child job from executing but instead launch a second child job.
Warning!
Use of a revert within a parallel branch can cause multiple instances of the same child job to run simultaneously. Itential recommends that you avoid this when possible.
The following scenario illustrates how running child jobs behave when reverted over in a parallel path.
Example
In the below workflow, the stub task has parallel branches to both a ViewData manual task and a childJob task. Assuming the manual task is worked before the child job finishes, when the manual task is worked the job will revert to the Stub task, which will succeed and then again execute the Child Job task. However, this will not cancel or replace the initial child job, but instead execute a brand new child job. The first child job will still continue running until it is completed, just like any other automatic task. Otherwise, there is no way for the parent job to understand the state of the first child job when it was reverted over. If these previous child jobs are no longer needed, it should be safe to cancel these child jobs manually.
It should be noted that this behavior also works the same as when manually reverting over a paused child job.
Figure 11: Parallel Branching with Revert Transitions over a Child Job
Was this article helpful?
