Creating & Running Worfklows

Within Itential Platform is Automation Builder for defining and building the automations that may be used by applications in the system. Automation Builder provides a clean, modern interface for arranging and connecting tasks and transitions on a canvas to create a flow-based workflow.

Figure 1: Automation Builder Canvas

Terminology

Helpful terminology applicable to Automation Builder and workflow design in Itential Platform is referenced in the table below. It is a living document subject to changes and updates.

Workflows in Studio

To get started with building an automation, select Studio (formerly Automation Studio) from the Itential Platform homepage. From the landing page of Studio, you can search for an existing automation (workflow), or you can create a new one.

Searching Workflows

To find an existing workflow, click the search icon (magnifying glass) in the top toolbar of the Studio page. From the Workflows tab of the Collection dialog, you can browse the workflows or use the search bar or browse to select an existing workflow to open and display its workflow canvas.

Figure 2: Workflows Collection

Creating Workflows

To create a new workflow:

1. Click the plus (+) icon on the Studio homepage. The Create dialog opens.
2. Select Automation in the type dropdown.
3. Enter a name for the new automation.
4. Click Create and the workflow opens in the Canvas.

After creating your new workflow, build it out on the canvas:

1. The New Canvas will open with Start and End displayed. Additional tasks can be added to the workflow, as needed, from the Task Palette via drag and drop.
2. The Task Palette is aligned to the left next to the sidenav menus when a new workflow is created. The Task Palette can be moved or closed if more space is needed to view the canvas. Click the Show Task Palette button in the task toolbar to reopen the Task Palette.
3. Search for a task in the Task Palette by typing in the "Filter Tasks" search field.
4. From the search results that return, drag and drop the desired task onto the New Canvas.
5. To add a transition from one task to another, use the mouse to highlight the border around a task. Press and hold the mouse button and move away from the task to create a transition arrow, and then drag the transition arrow to the next task and release the mouse press.

Below is a sample workflow, along with a reference table that highlights the various menus, toolbars and controls.

Figure 3: Workflow Canvas

{height="" width=""}

Canvas Task Types

An automation (job) in the Automation Builder Canvas will consist of:

• An automatic task denoted by green.
• A manual task denoted by grey.
• The start/end terminators denoted by grey and black.
• An operational task denoted by purple.

The arrows in the automation represent transitions and show the direction of the workflow. Automation Builder also provides optional role-based access control (RBAC) by restricting task ownership to authorized groups. Users are assigned to groups, and automation tasks can be restricted to specific groups. Only group members are authorized to work tasks. Groups will play a part in task assignment and work queues.

Figure 4: Canvas Tasks

The following shows an end-to-end automation (workflow) in the canvas designed to perform automated and manual tasks using success and failure transitions with revert capabilities. Transitions are identified by two properties:

• The exit status of the leading task.
• The direction of the transition (standard or revert).

Different transitions allow automations to correct anomalies, repeat parts of an automation, skip tasks, manually intervene, or follow the planned execution path.

Figure 5: Transitions in a Workflow

Automation Lifecycle

The Automation Builder lifecycle refers to the various states associated with running an automation. Each state (i.e., status) corresponds to a running job or task in a workflow.

Job Status

Upon start, a job is set to running status. Running jobs can move into cancelled, completed, or error states.

Figure 6: Job Lifecycle

Task Status

When a job is started, its tasks are set to an incomplete status. From incomplete, tasks move into running or scheduled states. A running task can move to completed, canceled, or error states.

Figure 7: Task Lifecycle

Variable Types

In Automation Builder, variables are used to hold one or more values that can be referenced by various devices and applications There are three variable types (static, job, and task) that can be used in a Reference task on the Automation Builder canvas.

Static Variables

Static variables are hard-coded and maintain the same value between function calls. They cannot be modified or changed programmatically in the lifecycle of an automation run. A static variable remains in memory while the automation is running. They are often used to maintain settings whose values should not change once a workflow (automation) has started.

Job Variables

Job variables allow you to use changeable values in the configuration and execution of a job. You create a variable, give it a name and a value. You can then insert the variable (by referencing its name) in various places in a workflow. When Itential Platform runs a job, it replaces the reference variable with the job variable's value. Job variables are useful in two ways. First, they allow you to pass values as inputs to a workflow each time you execute it. Secondly, anywhere in the workflow, a task can set/update the value of a job variable. As a best practice, use task variables instead of job variables whenever possible, but if task variables will not work, then use job variables.

Task Variables

Task variables are values provided as a result of executing another task earlier in the workflow of an automation. Essentially, they provide reference information for another task. This means you are choosing some previously executed task, taking its output, and using that as the selected task’s input.

Actors in Workflow Management

In the context of workflow management, actors play a crucial role in executing tasks within a workflow. Here are some insights:

• Authorization Layer: In workflow management, individual tasks are performed by actors. It's important to ensure that tasks are not executed by unauthorized individuals. This involves setting up an authorization layer to manage who can perform specific tasks. This approach also ensures that tasks are carried out with the appropriate user context.

• Task Configuration: When designing workflows, it's possible to set the actor for each task. Initially, this could be the user designing the workflow, but it can be changed to another user or a system user. This flexibility allows for better management of task execution.

Assigning Actors

When editing an automatic task in Itential Platform, you have the option to select the actor. An actor refers to the user that executes an automatic task in a job. By default, the actor that executes an automatic task is the Itential user, but any user in the Platform can be an actor. When building an automation, you can specify for each automatic task which user should be designated as the actor, which can be one of the following:

• Itential (Pronghorn) - The default user.
• Job Initiator - The user that started the job.
• Any Prior Manual Task - The user of a manual task that occurs prior to the currently configured automatic task within an automation.

When an automatic task runs, it calls the method, writes to an audit trail, and is authorized in the same manner as if that user had called the method associated with the task via Northbound API. If the task invokes an external system API, Itential Platform uses the actor's credentials in the external system API call, which leverages defined access control mechanisms that might be defined on the external system. If an actor is selected from a manual task that is on a branch that does not run, then the Automation Engine will fallback to the Itential user.

Figure 8: Actor

Transitions & Task States in Workflows

In a workflow, transitions connect tasks to each other and control the order of task execution. A transition has two properties that affect its behavior:

• A binding value, which corresponds to a possible finish state of its leading task.
• A direction, which determines whether workflow execution should be moved forward or backward.

By using these two properties, transitions can define multiple conditional execution paths for a workflow.

Task Finish States

When a task is finished executing, it is assigned one of the following finish states.

Transition Binding Values

The binding value of a transition corresponds to one of the finish states. As such, transitions are often referred to as success, error, or failure transitions. You can determine the binding value of a transition by its color:

• Success transitions are green.
• Error transitions are red.
• Failure transitions are purple.

After a task has been assigned a finish state, the workflow will proceed by following any transitions from that task that have a matching binding value.

Example: Determining Which Transition Is Used

The workflow displayed in Figure 1 uses the stringConcat task to combine two strings together. If the stringConcat task does not encounter any errors in its execution, the workflow proceeds to the evaluation task. If the combined strings match the expressions defined in the evaluation task, the workflow proceeds to the End task using the success transition. Otherwise, the workflow proceeds to the runShellCommand task using the failure transition.

Figure 9: Transition Paths

Transition Direction

The second defining property of a transition is its direction. A transition may have one of the following directions as defined in the table below.

The direction of a transition is determined by the type of line it is drawn with:

• Standard transitions are drawn with a solid line.
• Revert transitions are drawn with a dashed line.

Example: Behavior of Standard and Revert Transitions

The workflow displayed in Figure 2 uses the getTime task to get the current time. If the getTime task does not encounter any errors in its execution, the workflow is advanced forward to the ViewData task using a standard success transition. Because the ViewData task is an actionable task, the user will view the results of the getTime task. If needed, the user can re-execute the workflow by following the revert failure transition of the ViewData task. The getTime task will be re-run, and the workflow will proceed as normal.

Figure 10: Transition Directions

Adding Transitions to an Automation

To create a transition between two tasks:

1. Click the task you want to transition from. The task is highlighted with a dashed border.

   Figure 11: Highlighted Task
   

2. Click within the dashed border and begin dragging toward the destination task. Transition direction is determined automatically; a transition is standard unless you are dragging to a previous point in the workflow.

3. While dragging, assign a binding value to the transition by pressing one of the following:

   • S for success
   • E for error
   • F for failure

4. When the transition snaps to the destination task, release the mouse button.

   Figure 12: Adding a Transition
   

Changing a Binding Value

To change the binding value of an existing transition:

1. Click the transition. The transition becomes bold.
2. Assign a new binding value to the transition by pressing one of the following:
   • S for success
   • E for error
   • F for failure

Alternatively, right-click the transition and select a binding value from the context menu that appears.

Task Status Symbols (Ops Manager)

Task status symbols on the workflow canvas are used by Operations Manager to track task status in a job instance. This table lists all the icons used in the canvas interface to indicate the status of a task.

Task Status Symbol	Icon	Meaning
Green Check Mark		Task completed successfully.
Red Exclamation Mark		Task has errored.
Blue Circular Arrows		Task is currently running (manual task).

Using the Canvas Search

Automation Builder supports searching the content of your automation through the Canvas Search function. The search icon (magnifying glass) for Canvas Search is located at the top-left of the main canvas.

Figure 13: Search Icon

Additionally, the Canvas Search function can be accessed by right-clicking the canvas and selecting Show Canvas Search on the palette menu or by using the keyboard shortcut “Q” .

Figure 14: Short Cuts

When you click the magnifying glass icon this will reveal the Search Palette, a panel similar to the Task Palette. The search field at the top will be followed by a list of tasks that are currently on the canvas.

Figure 15: Search Palette

Enter a search term in the "Search your canvas" field. The search function will query the task summary and task description to look for 3 words before and 3 words after the search term. Search terms will be highlighted at the bottom of each task they pertain to. Search Options can include: app, description, id, job variable, name, and summary.

To clear a search, delete the search term.

Searching for a task located in multiple places on the workflow will return as a list as well as bring each task into focus on the canvas, making it easier to find them in complex workflows.

Figure 16: Multiple Tasks

Clicking a task in the search list will select that specific task and center it on the canvas.

Figure 17: Selecting a Task

Double-clicking a task in the search list will select the task, center it, and open the task.

Figure 18: Double Clicking a Task

If there is more than one result from the search criteria that matches a task, an icon displaying the number of Other Results Not Shown will appear. There can be up to "+4" other results that are not shown.

Below, a search on the term "stub" has matched the Task Summary first, with the number of other results displayed in the lower-right of the "Stub" task, and has also matched the Description. Only one vertically expanding result is displayed at a time. In this case, the Summary is displayed, and the Description is being hidden with the "+1" icon. Additional details are displayed by hovering the mouse over the icon.

Figure 19: Additional Results

Using the Reference View

Reference View is a powerful interface tool that allows the user to see the flow of data, via tasks, through a workflow. Before making changes to a workflow, a user can see how the flow of data from the current tasks will be impacted.

Reference View Mode

To enter Reference View mode, click on a task and then use the keyboard shortcut "R". Alternatively, perform a context click on the task (right-click on; mouse/two finger click-on; mouse pad/hold down Ctrl key and click on the task) and then select the View References option in the context menu.

Figure 20: Enable Reference View from the Stub Task

When Reference View is enabled, all the tasks the selected origin task uses for variable inputs (referred to as 'prior' tasks) and all tasks using variables of the selected task (referred to as 'subsequent' tasks) are displayed in a custom node template. All other tasks and transitions are lowered in opacity.

While in Reference View mode, the user can interact with the canvas as normal, except for any actions that could potentially change a task's references, which would trigger a notification suggesting the user exits the reference view to complete their attempted action. Reference View allows for a convenient visualization of all tasks that any particular task uses or is used by.

Reference View Visualizations

Listed below are the visualizations and features used in the application to distinguish the Reference View:

• Origin Tasks are focused by four gray floating corner accents/highlights surrounding on the task.
• Prior Tasks are highlighted in orange to indicate where data is coming into the origin task.
• Subsequent Tasks that receive data from the origin task are highlighted in blue and show where data is going.

Examples

Below, the Stub task is the Reference View Origin Task and is highlighted with the four corner accents. It is pulling in data from both of the Prior tasks (the New Variable and Modify tasks) displayed in orange. It is passing data through both of the Subsequent tasks (the Evaluation task and another Stub task) displayed in blue.

Figure 21: Data Flow for Reference View

Below is an example of a warning a user will see when attempting an action that would potentially change references. In this example, there is an attempt to delete the Reference View Origin Task. The delete options in the context menu are disabled and when the keyboard shortcut is used, the warning notification appears in the upper-right corner of the canvas.

Figure 22: Reference View Warning