Workflow Best Practices

These best practices are provided as suggested approaches to support optimal results within the Itential platform and to establish basic workflow design standards that may be suitable for widespread adoption. There could be instances where these suggested practices require adaptive modification to support what actually happens in a production environment.

Top to Bottom Design

Being able to quickly and accurately read a workflow is critical. To help with this the flow should be top-to-bottom, then right-to-left. This is referred to as Top-to-Bottom design. Even when the logic requires having divergent paths, keep them flowing from top-to-bottom.

When you need to divert the path based on an evaluation, or if you need to revert to a previous task, the flow should be from right-to-left. When handling an error or failure condition, flow should be left-to-right.

Figure 1: Top to Bottom Flow

Error and Failure Paths

Use Error and Failure paths whenever possible. If a workflow encounters a critical error, have all errors exit the same way.

Error pathways should go to the right. Avoid having them run through the center of the workflow whenever possible.

When creating success, failure, and error transitions, try to avoid crossing them whenever possible. This will help to keep your workflows clear and easy to read.

You also want to avoid having task transitions go through other tasks. You can use stub tasks to complete this and keep your workflow clean and easy to read. When creating these transitions, do not forget to set the summary and description to something that is easy to understand like “Exit Gracefully”.

Figure 2: Error and Failure Paths

Error Transitions

Make sure to always have error transitions. Essentially, allow for failures, even when you do not expect something to fail. There are times when the system will crash or reset and it may have nothing to do with your workflow, but that can cause less than graceful failures in workflows that do not allow for failure paths in their design.

Some tasks, such as newVariable, do not need error transitions as they process very quickly. Focus on having an error transition from every automated task (those with a green hexagon) when possible.

Descriptive Summaries

Always use descriptive summaries and descriptions on every task. Think of them like comments in your code. The default description that is preestablished for tasks is not very clear. However, the description “Query data using a dot/bracket notation string and a matching key/value pair” when debugging a workflow is more informative than seeing "Query Workflow Names". When hovering over a task in Automation Studio, the description is displayed.

Figure 3: Summary

Proper task names are important as well. When an operator is viewing the details of a job, the task names are listed. These should be summaries that clearly define what is being done without being overly verbose.

Setting the Job Description

If a job refers to an external system – such as a trouble ticket system – and you can ID the external system, then enhance the job description to include the additional information. This can be done using the updateJobDescription task. This allows operators to more easily search for the job associated with a particular ticket number in Jobs (Operations Manager), thereby helping to reduce the time it takes to find that correlation compared to if they only had the ticket number.

Job descriptions can also be used to mark the status of a job. If the job has an unrecoverable error, for example, you can use the job description to mark exactly what failed, allowing operators to easily search to see how many jobs encountered that error.

Figure 4: Error or Failure Paths

When naming a workflow, do not use special characters and keep the naming in a format that groups related workflows together.

Workflow Nomenclature

When naming workflows, make sure they include a clear description of what project the workflows are associated with. This allows developers to quickly search for all workflows associated with a project. Creating groups to contain closely associated workflows is another way to manage a project.

Figure 5: Workflow Groups

The project name can also be abbreviated so it does not take up the entire search window. In the example below (Figure 6), all that is visible is “DNS Management Infob”. If the developer of this workflow started the name with “DNS Mgmt” then users could see easily which workflow was “DNS Mgmt Infoblox Fixed Address Records Modify” instead of having to click on each workflow to find the right one.

Figure 6: Project Name

The example below (Figure 7) shows proper use of nomenclature. You know what project these workflows are associated with, and you can easily determine which of the five workflows is listed by running a search for the word ‘Email'.

Figure 7: Abbreviating Names

JSON Transformations (JSTs)

Use JSTs when possible. JSON Transformations are incredibly powerful and allow for developers to modify data into new formats. JSON Transformations also provide functionality that is not built into Workflow Builder, such as incrementing a running tally. Utilizing JSTs can also drastically reduce the canvas size of a workflow.

Child Workflow

Utilize child workflows when possible, as this will increase reusability. Think of child workflows as a function that will process data and then return the result. Child workflows can be utilized to run identical steps multiple times, or to lower the footprint of a massive workflow into multiple, more manageable, workflows.

Smaller Workflows

The processing of child workflows has improved significantly in IAP, and child workflows are now encouraged. Instead of a monolithic workflow, multiple smaller workflows allow for easier handling and debugging.

Looping Large Arrays

Avoid using forEach loops when iterating over long running or large arrays. If you must process an array with thousands of elements, utilize a JST or child job looping for this purpose.

Passing Large Objects

Avoid using large objects thousands of lines long. If you pass a large object, consider breaking it down into smaller components that are more manageable.

Dangling Tasks

Avoid dangling tasks when possible. Tasks that do not transition back to the main pathway will fire, but will not return any data back to the main pathway. A better practice would be to return an object showing the status of the tasks (success, failure, warning, etc).

Dangling tasks do not include forEach loops or tasks that revert to previous tasks. Instead, use a child workflow to accomplish the same goal.

Reuse Workflows

When building workflows, try to design them so they can be used again or more than once in multiple workflows. To help facilitate this, keep workflows small and manageable.

Standardize your Outputs

Have your returned values from the workflow be the same across your entire solution. The example below shows the values of "status" and "results" returned from the child workflow as a job variable. This allows for the parent workflow to quickly check the value of "status" to determine the status of the child workflow. If the values are returned, then they can be accessed by querying the value for the "results" key.

Figure 8: Standardized Output

Defining Job Variables

Define job variables at the start of a workflow. This makes it easier to find where a variable needs to be changed. It is significantly easier to change a value here than to find a hard coded value in an eval task.

The start of a workflow is a place to put workflow constants such as Maximum Number of Retries (maxNumberOfRetries), Number of Decimal Places, Verbose or Silent. When defining these variables, multi-thread them so they all fire at once. This will increase the overall speed of the workflow.

Figure 9: Define Variables

Job variables can be set or defined in newJobVar tasks. They can also be set in the output tab of a task. Using newJobVar tasks make a workflow more readable without having to open the tasks. The Output Tab job variable setting is cleaner on the canvas but can be more difficult to track down (users will need to view a workflow JSON export to find everywhere the job variable is used/set).

Variables to Indicate Workflow Status

Use Job Variables as key indicators of workflow success. This helps when looking at the workflow "variables" object to understand where the success or failure occurred.

Variable Mutation

Avoid Job Variable mutation when possible. Keep variables clean and consistent, and declare a new name if possible when updating values. This becomes even more important if incrementing a tally or updating workflow status is not possible.

Misunderstood Features

This sections covers task features often incorrectly interpreted or misunderstood.

Query

Workflow Engine Query Object - Pass on Null

• If PassOnNull is set as TRUE and the query key does not exist, the task will return the entire object that was passed in.

• If PassOnNull is set as FALSE and the query key does not exist, you must use the failure transition to handle the missing key.

Failure Tasks

Failure transitions are only utilized in specific areas. This would include a human decision, such as from a View Data task, or rejecting a command template. Automatic decisions also use failure transitions, such as from an eval task. In other cases, error transitions are used.