Universal Templates Overview

Owned by Stonebranch
Feb 06, 2023
8 min read

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:
    • Assigns matching variables for use in the Universal Template script.
    • Adds matching fields to the Details of any Universal Task that you create based on that Universal Template.

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>
 

ops_

Controller prefix used for all built-in variables and system-assigned variable.

<Variable Prefix>

Value of the user-defined Variable Prefix field in the Universal Template Details, followed by an underscore ( _ ) character.

<Field Name>

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: ops_<Variable Prefix>_<Field Name>) to each Field, using the variable prefix that you specified in Step 1, and will place those Fields in the Details of all Universal Tasks based on this Universal Template.

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.zipThe 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.

ImportTo 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

  • Prohibited.

Update a Template


  • Name
  • Allowed.
  • Variable Prefix
  • Allowed; Requires a corresponding Script change.
  • Agent Type
  • Broadening Allowed (Windows to Any, Linux/Unix to Any)
  • Narrowing Not Allowed (Any to Windows, Any to Linux/Unix, Windows to Linux/Unix, Linux/Unix to Windows)
  • Use Common Script
  • Script
  • Linux/Unix Script
  • Windows Script
  • Windows Script Type
  • Allowed.

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

  • Allowed (with conditions); Requires a corresponding Script change.
  • Prohibited if either Required or Required If Field/Required If Field Value(s) are specified.
  • Default Value applied to all Universal Tasks, but not to Universal Task Instances.

Delete a Field

  • Allowed (with conditions); Requires a corresponding Script change.
    • Update the only Field.
    • Create a new Field prior to deleting the only Field.Prohibited if the Field is the only Field in the Universal Template Details; User can either:

  • This restriction applies regardless of the existence of Universal Task/Task Instances associated with the Universal Template.



  • NULL value is applied to deleted Text, Integer, Choice, and Credential Fields in all Universal Tasks, but not Universal Task Instances.
  • A boolean False value is applied to a deleted Boolean Field for all Universal Tasks, but not Universal Task Instances.

Update a Field


  • Name
  • Prohibited.
  • Required
  • Allowed (with conditions).
  • Unchecking the Required field; Allowed (without conditions).
  • Checking the Required field; Allowed only if all Universal Tasks based on the Template have a value specified for this Template Field (does not apply to Universal Task Instances).
  • Require If Field
  • Require If Field Value(s)
  • Allowed (with conditions).
  • Removing a Require If Field specification; Allowed (without conditions).
  • Adding a Require If Field specification; Allowed only if all Universal Tasks based on this Template have a value specified for this Template Field (condition does not apply to Universal Task Instances).
  • Type
  • Prohibited.
  • Mapping
  • Prohibited.
  • Default Value
  • Allowed.
  • No Universal Task data will be updated; multi-update can be performed to apply any required changes to pre-existing Universal Task data.
  • Length
  • Allowed.
  • No Universal Task data will be updated, as it may not comply with updated Length constraint.
  • Minimum
  • Maximum
  • Allowed.
  • No Universal Task data will be updated, as it may not comply with updated Minimum/Maximum constraint.
  • Boolean Value Type
  • Boolean Yes Value
  • Boolean No Value
  • Allowed.
  • Field Display:
    • Label
    • Hint
    • Sequence
    • Form Column Span
    • Form Start Row
    • Form End Row
    • Add To Default List View
  • Allowed.

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

  • Allowed.

Delete a Choice

  • Allowed (with conditions).

  • Prohibited if the Template Field Choice is the only Choice; user can either:

    • Update the Choice Value.
    • Create a new Choice prior to removing the Choice.

    Note

    This restriction applies regardless of the existence of Universal Task/Task Instances associated with the Universal Template.

  • Any Universal Tasks using the Choice will still display the value, and substitute the old value into the Script; however, the drop-down will no longer display that Choice as an option.

Update a Choice


  • Value
  • Allowed
  • Any Universal Task using the previous value will be updated with the new value, but not Universal Task Instances.
  • Use Value For Label
  • Allowed.
  • Label
  • Allowed.
  • Sequence
  • Allowed.