Universal Templates Overview
Introduction
Universal Templates allows you to create the templates on which Integrations are based.
Within each Universal Template, you:
- Enter either:
- A script that will be executed by any Universal Task based on that Universal Template.
- An Extension that will be executed by any Universal Task based on that Universal Template through the Universal Extension framework.
- Create Fields that the Universal Controller:
When you create a Universal Template, the Controller creates a Universal Task type, under the Universal Tasks folder in the Automation Center navigation pane, based on that Universal Template.
When you create a Universal Task for that Universal Task type, its Details display - among other fields - the fields that you created in the Universal Template.
When you run the Universal Task, it executes the script in the Universal Template, and the variables in the script are resolved to the user-defined values of their matching fields in the Universal Task instance.
Note
Administration of Universal Templates requires the ops_universal_template_admin or ops_admin role.
Universal Template Scripts
A Universal Template can contain any user-defined script. Any script variables to be resolved to Universal Task field values when the task executes the script must be in a specific format.
If you change the script in a Universal Template, the Universal Tasks based on that template execute that changed script when they are run. With Universal Task / Universal Template, you do not have to change the scripts in multiple tasks, just in the template.
Universal Template Fields
For each Field that you create for a Universal Template, the Controller:
- Assigns it a matching variable for use in the Universal Template script.
- Adds a matching field to the Details of all Integrations based on that template.
When a Universal Task is run, it executes the script, and the system-assigned script variables are resolved to the user-defined values of their matching fields in the Universal Task instance.
You can enter seven types of Fields in a Universal Template:
- Text
- Integer
- Boolean
- Choice
- Credential
- Script
- Array
For each Field, you specify information regarding its appearance in the task Details for any Universal Task based on that template, including:
- Value
- Location
- Required or optional
Note
You must refresh the list of Universal Tasks that are based on a Universal Template in order for any changes to the Universal Template Fields to be applied to the Universal Task Details.
For detailed information about these Fields, see Creating Universal Template Fields.
Universal Template Variables
For each Field that you create for a Universal Template, the Controller assigns it a variable and adds the Field to the Details of all Universal Tasks based on that template.
These system-assigned variables are provided for use in the Universal Template script. When a Universal Task based on the template is run, it executes the script in the template, and all system-assigned variables in the script are resolved to the values of their matching fields in the Universal Task.
The system-assigned variables that are available for use in a Universal Template script must be in this format: ops_<Variable Prefix>_<Field Name>
| Controller prefix used for all built-in variables and system-assigned variable. |
| Value of the user-defined Variable Prefix field in the Universal Template Details, followed by an underscore ( _ ) character. |
| Name (not Label) of the user-defined Universal Template field to which the Controller assigns this variable. |
Note
If a Universal Template Field is required (either directly via the Required field in the Universal Template Field Details or indirectly via the Required If Field field), and its matching field in the Details of a Universal Task Instance is undefined after variable resolution, the Universal Task Instance will transition into the Start Failure status.
If a Universal Template Field is not Required, and its matching field in Details of a Universal Task Instance is undefined after variable resolution, the system-assigned variable for that Field will resolve to blank.
If a Universal Template Field with Type = Choice has a Choice with a NULL (or blank) Value at run time, a Universal Task Instance will transition into the Start Failure status.
Setting Up Universal Templates and Tasks
Step 1 | Create a Universal Template, which includes selecting the type of Agent(s) on which Universal Tasks based on this Universal Template can be run, and a variable prefix used for script variables that you want resolved when a Universal Task executes the script in this Universal Template. |
---|---|
Step 2 | Enter a script in the Universal Template that all Universal Tasks based on this Universal Template will execute when they are run. |
Step 3 | After you have entered/selected any other desired values in the Universal Template Details, save the Universal Template. |
Step 4 | For each parameter in the script that you want to replace with a variable, create a Universal Template Field of an appropriate Field type. The Controller automatically assigns a variable (format: |
Step 5 | Replace the appropriate parameters in the script with the system-assigned variables. |
Step 6 | Update the Universal Template. Now that the Universal Template has one or more defined Fields, the Controller creates a Universal Task type for it and adds the Universal Task type to the Automation Center navigation pane. (You must refresh the Automation Center navigation pane in order to see the new Universal Task type. |
Step 7 | Create a Universal Task for that Universal Task type. The Universal Task Details will contain the fields that you created in the Universal Template for that Universal Task type. |
Step 8 | Enter/change values in the Universal Task fields that match the Universal Template fields, based on how you want their matching variables in the script to be resolved. |
Step 9 | Run the task, which executes the script. The variables in the script are resolved to the values of their matching fields in the Universal Task. |
Importing / Exporting Universal Templates
The Import/Export Universal Template feature supports importing/exporting a Universal Template as a zip file.
A Universal Template zip file includes the following entries:
File Name | Description | Optional |
---|---|---|
template.json | The Universal Template definition in JSON format. | No |
template_icon.png | The Universal Template Icon in PNG format. Note Icon metadata will be set as attributes in the Universal Template JSON. | Yes |
extension_archive.zip | The Universal Template Extension Archive in ZIP format. | Yes |
Export | To export an existing Universal Template as a zip file, click the Export Template button in the Universal Template Details. (You can also click Export Template in the Action menu that displays for that Universal Template record.) The exported Universal Template has the following filename format: unv_tmplt_UniversalTemplateName-extensionVersion.zip Any character in the UniversalTemplateName that is not an alphanumeric or underscore, will be replaced with an underscore. |
Import | To import a Universal Template zip file, click the Import Template… button on the Universal Templates list. |
Release Levels
Export Template sets the following release level attributes in the Universal Template JSON:
Attribute | Description |
---|---|
minReleaseLevel | The minimum Universal Controller release level required to import the Universal Template. "minReleaseLevel" : "7.0.0.0" |
exportReleaseLevel | The release level of the Universal Controller that the Universal Template was exported from. "exportReleaseLevel" : "7.0.0.0" |
Import Template validation prevents importing a Universal Template if the Universal Controller does not meet the minimum release level requirement:
Cluster Node release level is 7.0.0.0, which does not meet the minimum release level of 7.0.0.1 for the Template.
List Import/Export
The List Import/Export feature continues to support exporting the Universal Task and Universal Template, as it has in previously releases.
Comparable to the Universal Template Icon, the Extension Archive will be encoded in the XML as base64.
List Import validation prevents an extension name from being associated with more than one Universal Template:
The template 'template-name1' specifies an extension name 'extension-name' that is already associated with template 'template-name2'.
Restrictions on Universal Template Changes
There are restrictions on the changes that you can make on Universal Templates, because some changes (such as adding a new field with a default value), can automatically change existing Universal Task and Universal Task Instances based on that Template.
Some Universal Template changes are restricted, based on the existence of Universal Tasks and Universal Task Instances.
Universal Templates do not have versioning; therefore, reverting a Universal Template change must be done manually, and the restrictions still apply.
Some changes cannot be reverted; for example, you cannot broaden the Agent Type, and then narrow it. Universal Tasks do have versioning, but changes to a Universal Template that automatically change a Universal Task, such as adding a new field with a Default Value, do not generate a new version.
Any promoted Bundle that includes Universal Template changes cannot be restored.
Restriction Conditions
Restrictions on changing Universal Templates (see List of Restrictions, below) depend on the following conditions:
Condition | Restrictions |
---|---|
Both Universal Tasks and Universal Task Instances exist. | All restrictions apply. |
Universal Tasks exist, but no Universal Task Instances exist. | All restrictions apply. |
Universal Task Instances exist, but no Universal Tasks exist. | All restrictions apply if the Universal Task Instances are still active. |
Neither Universal Tasks nor Universal Task Instances exist. | None of the restrictions apply unless otherwise noted. |
List of Restrictions
Action | Restriction |
---|---|
For Universal Templates | The following Delete and Update actions refer to Universal Templates and the fields in Universal Template Details. |
Delete a Template |
|
Update a Template | |
|
|
|
|
|
|
|
|
For Universal Template Fields | The following Add, Delete, and Update actions refer to the user-defined Fields that are added to a Universal Template. |
Add a Field |
|
Delete a Field |
|
Update a Field | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For Universal Template Field Choices | The following Add, Delete, and Update actions refer to the Choices that are defined for a Universal Template Field type of Choice. |
Add a Choice |
|
Delete a Choice |
|
Update a Choice | |
|
|
|
|
|
|
|
|