Itential Cloud

Itential Cloud

How to Configure and Edit Tasks on the Canvas

18 Oct 2024

Dark

Light
PDF

How to Configure and Edit Tasks on the Canvas

Updated on 18 Oct 2024

Dark

Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Task Panel

To edit a task on the new canvas, double-click a task on the Canvas to display information on that task in a panel on the right. Each Task panel will contain a Data, Advanced, and Details tab.

The Data tab contains input and output variables.
The Advanced tab contains the Access Control, Run Window, and Retry Task configurations.
The Details tab contains a description of the task that can be edited as well as a link to the API Documents page.

Tasks from the Canvas make calls to actions that perform specific and discreet activities to implement business logic. They take input arguments and return output variables. The inputs and outputs for the task are visible in the Edit dialog under the Incoming and Outgoing tabs (Figure 1) of the dialog. In the event an error occurs, the task may return an error variable, which is visible under Error.

Figure 1: Task Configuration Panel
01_Task Properties_2023.1

Configuring Task Properties

Use the information presented in the following sections to configure a task.

Incoming Parameters

Task information is split between three tabs.

Data: Input variables for the task.
Advanced: Configurable options not directly related to input.
Details: The task description.

Figure 2: Task Parameters
02_Task Parameters_2023_1

Label	UI Element	Description
1	Incoming (Tab )	Required (mandatory) parameters are marked with an asterisk. - Variable: The argument name. - Type: Data type (boolean, string, number, array, object). - Reference task: Defines the data source. Options include: job, static, a prior task. - Reference variable: Value is assigned from the defined Reference task.
2	Actor (for Automatic Tasks only)	Execute automatic tasks by the system or a user by setting the Actor field. -Itential (Pronghorn): The system executes the automatic task. -job: Execute the automatic task as the user that started the job. - Any previous manual task: Execute the automatic task as the user that worked a previous manual task.
3	Run Window	Restrict when an automated task will run by specifying a schedule.
4	Description	Enter a brief task description in the optional Description field.

Note:

Avoid changing to another task's input variable, which could create variable type mismatch and other errors.

Reference Task Options

Option	Description
job	A global variable. Job variables are set at the time a job is started or when a task's outgoing data is copied to a job variable. Job variables are visible to all tasks defined in the automation. Job variables are mutable. Some job variables are always present; others are defined by the collection of input job variables between all tasks in the automation.
static	A constant; a value defined within the task properties.
any prior task	Present in the current automation (listed by name in the dropdown).

Reference Variables

Reference Task	Reference Variable
job	Defaults to same name as the task's parameter. Dropdown shows all job variables, including input arguments for every task whose reference task is the job. To set a custom job variable name, click EDIT and type the new name in the Reference variable field. Job Variable names must adhere to the IAP Naming Conventions provided in the developer guide.
static	Static value entered in Reference variable field.
a prior task	Name of an output variable or error from selected prior task.

Manual Tasks & Access Control

For Manual tasks only, use Groups, located under the Advanced tab and in the Access Control drop down, to restrict who is authorized to work the task by assigning one or more groups.

Type "Administrators" in the Groups field. Matching group names will appear in a list after you begin typing.
Click the correct group name to add that group to the task's groups. The group will not be added unless it is selected from the list.
Add as many groups as desired.

Figure 3: Manual Task (Groups)
03_Groups_2023_1

Outgoing Parameters

Configurable options in the task output are referenced below (Figure 4).

Figure 4: Outgoing Tab
04_outgoing_2023_1

Label	Ougoing Parameter	Description
1	Variable	The task's return variable; the variable which is made available to any subsequent task in the workflow. Outgoing variables are immutable.
2	Job Variables	To promote the task's return variable to a job variable, check the Store Output as Job Variables box. This copies the outgoing variable's value to a job variable. Job variables are similar to global variables; they are available to every task in the job.
3	Job Variable Names	Defaults to the same name as the task's return variable. To set a custom name for the return variable, type the new name in the Job Variable Name field. Job Variable names must adhere to IAP Naming Conventions.

Error Parameters

Task error variables are referenced below (Figure 5).

Figure 5: Error Tab
05_outgoing_Error_2023_1

Label	Error Parameter	Description
1	Variable	The task's error variable, which is returned in the event of an error.
2	Job Variables	To promote the task's error variable to a job variable, check the Store Output as Job Variable box. This copies the error value to a job variable. Job variables are similar to global variables; they are available to every task in the job.
3	Job Variable Names	To set a custom name for the error variable, type the new name in the Job Variable Name field. Job Variable names must adhere to IAP Naming Conventions.

Masking Variables

Users can mask certain variables; masking will hide the result in Operations (Job) Manager when the workflow is run. If a variable is a reference variable, or a job variable, the factor that determines whether that variable is masked is by where the variable originated.

To enable masking, open the Task dialogue and toggle Mask to on.

Figure 6: Masked Checkbox
06_Mask_2023_1

Masking JST Tasks

For JST tasks, you must mask all outgoing variables, or none of them (Figure 7).

Figure 7: Masking JST Tasks
07_Transformation_Masking_2023_1

JSON Schema for Schedule Value in Run Window

{
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "window": {
        "type": "object",
        "properties": {
            "sun": {
            "$id": "/properties/window/properties/sun",
            "type": "object",
            "description": "Schedule details for day of the week Sunday.",
            "properties": {
                "enable": {
                "type": "boolean",
                "description": "Will task run this day of the week?",
                "default": false,
                "examples": [
                    false
                ]
                },
                "time": {
                "type": "object",
                "description": "When can task run this day of week.",
                "properties": {
                    "from": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's beginning inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        200
                    ]
                    },
                    "to": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's ending inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        229
                    ]
                    }
                }
                }
            }
            },
            "mon": {
            "$id": "/properties/window/properties/mon",
            "type": "object",
            "description": "Schedule details for day of the week Monday.",
            "properties": {
                "enable": {
                "type": "boolean",
                "description": "Will task run this day of the week?",
                "default": false,
                "examples": [
                    false
                ]
                },
                "time": {
                "type": "object",
                "description": "When can task run this day of week.",
                "properties": {
                    "from": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's beginning inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        200
                    ]
                    },
                    "to": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's ending inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        229
                    ]
                    }
                }
                }
            }
            },
            "tues": {
            "$id": "/properties/window/properties/tues",
            "type": "object",
            "description": "Schedule details for day of the week Tuesday.",
            "properties": {
                "enable": {
                "type": "boolean",
                "description": "Will task run this day of the week?",
                "default": false,
                "examples": [
                    false
                ]
                },
                "time": {
                "type": "object",
                "description": "When can task run this day of week.",
                "properties": {
                    "from": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's beginning inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        200
                    ]
                    },
                    "to": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's ending inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        229
                    ]
                    }
                }
                }
            }
            },
            "wed": {
            "$id": "/properties/window/properties/wed",
            "type": "object",
            "description": "Schedule details for day of the week Wednesday.",
            "properties": {
                "enable": {
                "type": "boolean",
                "description": "Will task run this day of the week?",
                "default": false,
                "examples": [
                    true
                ]
                },
                "time": {
                "type": "object",
                "description": "When can task run this day of week.",
                "properties": {
                    "from": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's beginning inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        200
                    ]
                    },
                    "to": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's ending inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        229
                    ]
                    }
                }
                }
            }
            },
            "thur": {
            "$id": "/properties/window/properties/thur",
            "type": "object",
            "description": "Schedule details for day of the week Thursday.",
            "properties": {
                "enable": {
                "type": "boolean",
                "description": "Will task run this day of the week?",
                "default": false,
                "examples": [
                    true
                ]
                },
                "time": {
                "type": "object",
                "description": "When can task run this day of week.",
                "properties": {
                    "from": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's beginning inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        200
                    ]
                    },
                    "to": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's ending inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        229
                    ]
                    }
                }
                }
            }
            },
            "fri": {
            "$id": "/properties/window/properties/fri",
            "type": "object",
            "description": "Schedule details for day of the week Friday.",
            "properties": {
                "enable": {
                "type": "boolean",
                "description": "Will task run this day of the week?",
                "default": false,
                "examples": [
                    false
                ]
                },
                "time": {
                "type": "object",
                "description": "When can task run this day of week.",
                "properties": {
                    "from": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's beginning inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        200
                    ]
                    },
                    "to": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's ending inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        229
                    ]
                    }
                }
                }
            }
            },
            "sat": {
            "$id": "/properties/window/properties/sat",
            "type": "object",
            "description": "Schedule details for day of the week Saturday.",
            "properties": {
                "enable": {
                "type": "boolean",
                "description": "Will task run this day of the week?",
                "default": false,
                "examples": [
                    false
                ]
                },
                "time": {
                "type": "object",
                "description": "When can task run this day of week.",
                "properties": {
                    "from": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's beginning inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        200
                    ]
                    },
                    "to": {
                    "type": "integer",
                    "description": "Time in 24-hour format (HHMM) and in the Itential server's time zone that identifies the time window's ending inside which the scheduled task is allowed to run.",
                    "default": 0,
                    "pattern": "[0-9]{1,4}",
                    "examples": [
                        229
                    ]
                    }
                }
                }
            }
            }
        }
        }
    }
    }

How to Edit a Task

To edit a task:

Double-click any task in the workflow canvas to open the Edit task dialog.
Update the appropriate task properties.
Click the SAVE button to retain your changes.

How to Copy a Task

To copy a task within an automation:

Right-click the task to view the pop up menu.
Click Copy.
Rigth-click anywhere on the Canvas and click Paste here from the pop up menu. A copy of the task is pasted onto the canvas.

Keyboard Shortcuts:

Command + C and Command + V can be used to copy and paste, respectively.
Holding the Option key and dragging to duplicate can be used as well.

How to Delete a Task

To delete a task:

On the Automation Builder canvas, select the task you want to delete.
Click the Delete button, or double-click the task and choose Delete from the pop up menu .
Click the SAVE button in the title bar.

How to Spread Tasks on the Canvas

To spread tasks out on the Canvas for better viewing and management:

Click the Fit Window button in the upper-right corner of the Canvas.
An option to Spread Tasks will appear. Moving the slider will allow users to enlarge or shrink the area between tasks that are on the canvas.

Figure 8: Spread Tasks
18_Spread_Tasks_2023_2

How to Use Recent Tasks

The ten (10) most recent tasks moved from the Task Palette to the canvas will now be stored under the Recent Tasks icon for quick access. Click the icon for Recent Tasks and a dropdown will display the 10 most recent tasks added to the canvas.

From the Recent Tasks dropdown, each task can be dragged and dropped onto the canvas to use again as needed. Copying, pasting, or duplicating tasks already on the canvas will not add them to the Recent Tasks dropdown. Any task displayed in the Recent Tasks dropdown can be removed by clicking the "X" to the right of the task.

Figure 9: Recent Tasks
17_recent_2023_2

How to Find Adapter IDs

Adapter IDs can now be found under the Advanced tab in the Task Options dropdown.

Figure 10: Adapter IDs
12_Task_ID_2023_1

How to Retry a Task

From the Automation Builder canvas, a task can be setup to allow an operator of a job to retry it. Two types of task retry are available: Automatic and Manual.

The Automatic Retry is configured on the canvas with options for when to retry, how often, and if there should be a delay between retry attempts.
A Manual Retry is available within Operations (Job) Manager; however, to enable this capability, the automation designer must specifically have 'Retry Task' set to true.

To specify the retry settings on the Canvas:

Open the Task Details dialog and click the Advanced tab.
Expand the Retry Task dropdown.
Toggle Enable Retry Task to "on".
Select the Automatically Retry Task checkbox. When checked, the task will automatically retry without user intervention.

Configure the Retry settings using the table below.

Retry Setting	Description
Retry On	Select a value from the dropdown to set what conditions to allow task retry to occur on.
Number of Retry Attempts	The number of times to retry a task before the workflow must continue running. Default value is "10". Note: Itential advises caution when increasing the Number of Retry Attempts. There is no limit to the number of times to retry a task.
Retry Delay	The number of seconds between retry attempts a task waits to retry again.

Figure 11: Retry Settings Dialog
08_retry_2023_1

After running the workflow, you can manually retry a task by accessing the job in Operations Manager (IAP→ Operations Manager → Jobs), and clicking the Retry button in the Job Details panel, located in the vertical dots (⋮) button menu of the job, if available. You will be presented with a Retry Task modal that contains a previous iteration of retry values. From this modal, you can provide new inputs on the retry. The modal is also resizable. After entering the new inputs, click Continue Job.

Figure 12: Retry Task Button

How to Restrict an Automated Task from Running

You can restrict when an automated task will run by specifying a schedule. This is also defined as setting the Run Window for a task, which means the task will not run (once it is time to run) if the current time falls outside the run window.

To schedule an automated task:

In an open automation, double-click an automated task to open the Edit task dialog.
Click the Advanced tab and then expand the Run Window dropdown.
Toggle the Enable Run Window switch to open the schedule options..
Select an option from the Run Window Mode.
1. Select Static to statically define the task's run window.
2. Select Job to pass the schedule at run time through a job variable and then configure the properties. The job variable can be a job variable name, a static value, or an earlier task's outgoing variable name or error.
3. Select Task to define the data source. Options include: job, static, or any prior task in the current automation (listed by name in the dropdown).
Enter the **Window Start ** and Window End time in 24 HR format (HHMM) relative to the server's configured timezone.
Select the days on which the task should run. The selected buttons will turn from white to blue.
The selections are automatically SAVED in the task.

Figure 13: Run Window Dialog
11_Schedule_2023_1

How to Swap a Task on the Canvas

Tasks on the canvas can now be swapped without having to delete another task or the transition that connects to the task that is swapped.

To use this feature:

Double-click the task on the canvas to display the task panel.
In the upper-left corner of the task panel overlay, click the Swap Task icon (  ) to open a simplified version of the task palette that is used to add tasks to the canvas.

Figure 14: Swap Task
Locate the replacement task via the task filter, or scroll through the list of tasks.
Click on the replacement task to put it in focus and enable (highlight) the “Confirm Swap” button at the bottom of the panel.
Click Confirm Swap. The replacement task will now show in place of the original task on the canvas.
Click Cancel Swap to revert back to the original task displayed on the canvas.

Figure 15: Confirm Swap and Cancel Swap Buttons
Any data under the Advanced Tab of the original task will be retained in the swapped task.

Figure 16: Advanced Variables
If the swapped task contains similar variables to the original task, select the Retain Task Data checkbox to carry over any relevant data that is applicable. If the swapped task is a completely different type of task, the variables will not be carried over.