- 05 Dec 2024
-
DarkLight
-
PDF
How to Configure and Edit Tasks in Gen 1
- Updated on 05 Dec 2024
-
DarkLight
-
PDF
Tasks in Gen 1 Automation Builder 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 the Error tab.
Figure 1: Task Configuration Dialog
Configuring Task Properties
Use the information presented in the following sections to configure a task.
Incoming Parameters
Figure 2: Automation Task Parameters
Label | Parameter | Description |
---|---|---|
1 | Summary | Enter a brief summary in the optional Summary field. This text displays on the task block. Tasks reference other tasks by their summary. |
2 | Description | Enter a brief task description in the optional Description field. |
3 | 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. |
4 | Run Window | Restrict when an automated task will run by specifying a schedule. |
5 | 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 the Reference task. |
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 variable
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 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. |
For Manual Tasks
For Manual tasks only, use Groups to restrict who is authorized to work the task by assigning one or more groups.
- Type "Operations" 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)
Outgoing Parameters
Figure 4: Outgoing Tab
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 Job Variables box. This copies the outgoing variable's value to a job variable. Job variables are similar to global variables in that 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 Names field. Job Variable names must adhere to the IAP Naming Conventions. |
Error Parameters
Figure 5: Error Tab
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 Job Variable box. This copies the error value to a job variable. Job variables are similar to global variables in that 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 Names field. Job Variable names must adhere to the IAP Naming Conventions. |
Masking Variables
Users can mask certain variables; masking will hide the result in 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, double-click the Start task on the canvas to open the Input Schema dialog. Job variables can be masked from here.
Figure 6: Masking Job Variables
Figure 7: Masked Checkbox
Figure 8: Masking JST Tasks
For JST tasks, you must mask all outgoing variables, or none of them.
Figure 9: Masking Result
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:
- Select the task to be copied. The labels should become bold.
- Click the Copy task button in the upper right corner of the Automation Builder canvas.
- A copy of the selected task will appear on the canvas.
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 press the "d" key.
- Click the SAVE button in the title bar.
How to Resize Task Boxes
For better visibility, task boxes and their labels can be enlarged or reduced. To increase or decrease the size of a task box:
- Click the Zoom In or Zoom Out buttons in the upper right corner of the Automation Builder canvas.
- Click the SAVE button in the title bar to save the resized task boxes.
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 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 Automation Builder Gen 1 canvas:
-
Open the Task Details dialog.
-
Switch the Retry Task toggle on.
-
Click the Edit button. The Retry Settings modal will open.
-
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. Retry Attempts The number of times to retry a task before the workflow must continue running. Retry Delay The number of seconds between retry attempts a task waits to retry again. Figure 10: Retry Settings Dialog
-
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 beneath the workflow, 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 11: Retry Task Button
Figure 12: Change Task Data on Retry
How to Schedule an Automated Task
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.
Setting a run window means the task will not run (once it is time to run) if the current time falls outside the run window.
Figure 13: Run Window Dialog
To schedule an automated task:
- In an open automation, double-click an automated task to open the Edit task dialog.
- Click the Run Window slider to set Scheduled to true.
- Click the EDIT button to open a side panel with the run window settings.
- Select an option from the Select Mode dropdown list.
- Select Static to statically define the task's run window.
- Select Variable to pass the schedule at run time through a variable and then configure the properties. The Reference task defines the data source. Options include: job, static, or any prior task in the current automation (listed by name in the dropdown). The Reference variable can be a job variable name, a static value, or an earlier task's outgoing variable name or error.
- Select the days on which the task should run. The selected buttons will turn from white to blue.
- Enter the Start Time and End Time in 24 HR format (HHMM) relative to the server's configured timezone.
- Click SAVE in the task dialog to save the run window schedule.
- Save your changes to the Automation by clicking SAVE in the bottom footer. A confirmation message will appear to confirm the changes were saved.
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
]
}
}
}
}
}
}
}
}
}