User-Defined Variables
Overview
User-defined Universal Controller variables are available for use in triggers, tasks, and Workflows.
You can define variables to be either:
- Available to a single trigger, task, or workflow; that is, Local.
- Available to all triggers, tasks, and workflows; that is, Global.
You define Local variables (variables specific to a single trigger, task, or workflow) on the Variables tab in the Details of that trigger, task, or workflow. These variables are stored in the ops_local_variable table.
You define Global variables either by:
- Selecting Other > Variables from the Automation Center navigation pane.
- Using the Set Variable action for a task or workflow.
Global variables are stored in the ops_variable table.
Variable Naming Conventions
- Variable names must begin with a letter.
- Allowable characters are alphanumerics (upper or lower case), and underscore (_).
- White spaces are not permitted
- Variable names are not case-sensitive.
Warning
Do not define Controller variables with the prefix ops_. That prefix is reserved for built-in variables.
Resolving User-Defined Variables
When the Controller creates a task instance from a task, it also resolves all variables specified in its free text fields. Because you can define variables at four different levels (trigger, task, workflow, and global), the Controller follows a prescribed formula to determine which variable takes precedence if duplicate variables have been defined. The general order of precedence, each of which may or may not exist in any given situation, is as follows:
- Task trigger (highest precedence)
- Task
- Workflow trigger
- Workflow
- Global (lowest precedence)
Note
You also can use the Set Variable Action of any task or workflow to define a variable. The Set Variable action explicitly states what scope you are setting the variable at, and under what circumstances.
The following scenarios provide more detailed information about how Controller variables are resolved.
For Tasks Launched by a Trigger
- If the trigger defines the variable in the variables tab, that value is used to resolve the variable.
- If the trigger does not define the variable, the value from the variable tab in the task Details is used.
- If neither the trigger nor the task define the variable, the variable definition in the global variables table is used.
- If the global variables table does not define the variable, the variable remains unresolved.
For Tasks Launched by a Workflow
- If the task defines the variable in the variables tab, that value is used to resolve the variable.
- If the task does not define the variable, and the workflow was launched by a trigger, the value defined in the trigger is used.
- If the workflow's trigger does not define the variable or the workflow was not launched by a trigger, the value defined in the workflow is used.
- If the workflow does not define the variable, and there is a parent workflow, the value defined in the parent workflow's trigger is used.
- If the parent workflow's trigger does not define the variable or if there is no trigger, the value defined in the parent workflow is used.
- If the parent workflow does not define the variable, the Controller checks up a level for the trigger on the next parent workflow.
- If that trigger does not define the variable, it checks for variables associated with the workflow. (This continues until the top level workflow is reached.)
- If the top-level workflow does not define the variable, the variable definition in the global variables table is used.
- If the global variables table does not define the variable, the variable remains unresolved.
For Tasks Launched Manually
- If the task defines the variable in the variables tab, that value is used to resolve the variable.
- If the task does not define the variable, the variable definition in the global variables table is used.
- If the global variables table does not define the variable, the variable remains unresolved.
Format for Using Variables
When you enter a variable into a text field, precede the variable with the dollar sign ( $ ) and enclose the variable in curly braces ( { } ). You can enter a series of variables or nested variables.
Examples:
Creating a Variable
You can create variables that are:
- Available on a Global level; that is, available for all triggers, tasks, and Workflows.
- Available only for a specific trigger, task, or Workflow.
Creating a Global Variable
To create a Global variable that is available for all triggers, tasks, and Workflows:
Step 1 | From the Automation Center navigation pane, select Other > Variables. The Variables list displays a list of all Global variables. (You also can define a Global variable by using the Set Variable action for a task or workflow.) |
---|---|
Step 2 | Enter / select Details for a new Variable, using the field descriptions below as a guide.
To display more of the Details fields on the screen, you can either:
|
Step 3 | Click a Save button to save the record in the Controller database. |
Note
To open an existing record on the list, either:
- Click a record in the list to display its record Details below the list. (To clear record Details below the list, click the New button that displays above and below the Details.)
- Clicking the Details icon next to a record name in the list, or right-click a record in the list and then click Open in the Action menu that displays, to display a pop-up version of the record Details.
- Right-click a record in the a list, or open a record and right-click in the record Details, and then click Open In Tab in the Action menu that displays, to display the record Details under a new tab on the record list page (see Record Details as Tabs).
Global Variable Details
The following Variable Details is for an existing Global Variable.
See the field descriptions below for a description of all fields that display in the Global Variable Details.
For information on how to access additional details - such as Metadata and complete database Details - for Variables (or any type of record), see Records.
Global Variable Details Field Descriptions
The following table describes the fields and buttons in the Variables Details.
Field Name | Description |
---|---|
Details | This section contains assorted detailed information about the variable. |
Name |
Name of the variable. Up to 128 alphanumerics. The name must begin with an alphabetic character and can consist of: alphas (a-z, A-Z), numerics 0-9, _ (underscore). White spaces are not permitted; names are not case-sensitive. Important Do not define variables with the prefix ops_. The ops_ prefix is reserved for built-in variables. |
Version | System-supplied. The version number of the current record, which is incremented by the Controller every time a user updates a record. Click the Versions tab to view previous versions. For details, see Record Versioning. |
Description | Optional. Description of this variable. |
Member of Business Services | User-defined; Allows you to select one or more Business Services that this record belongs to. (You also can Check All or Uncheck All Business Services for this record.) You can select up to 62 Business Services for any record type, and enter a maximum of 2048 characters for each Business Service. If the Business Service Visibility Restricted Universal Controller system property is set to true, depending on your assigned (or inherited) Permissions or Roles, Business Services available for selection may be restricted. |
Value | Value of the variable up to a maximum of 25000 characters. |
Self-Service Options | This section contains assorted information about the variable for tasks, workflows, and triggers only - not for Global Variables. |
Value Options | Value options that will presented when editing values from the Trigger Now... and Launch Task with Variables... command dialogs. Only non-empty values are allowed; duplicate values are not allowed. (Maximum = 25000 characters.) |
Allow Empty Option | Indication of whether or not an empty value is a valid value option. If true, an empty option will be added to the drop-down when editing values from the Trigger Now… and Launch Task with Variables… command dialogs. |
Allow Unlisted Option | Indication of whether or not an unlisted value is a valid value option. If true, the drop-down input box should allow users to enter a value that is not present in the set of value options when editing values from the Trigger Now… and Launch Task with Variables… command dialogs. |
Metadata | This section contains Metadata information about this record. |
UUID | Universally Unique Identifier of this record. |
Updated By | Name of the user that last updated this record. |
Updated | Date and time that this record was last updated. |
Created By | Name of the user that created this record. |
Created | Date and time that this record was created. |
Buttons | This section identifies the buttons displayed above and below the Global Variable Details that let you perform various actions. |
Save | Saves a new variable record in the Controller database. |
Save & New | Saves a new record in the Controller database and redisplays empty Details so that you can create another new record. |
Save & View | Saves a new record in the Controller database and continues to display that record. |
New | Displays empty (except for default values) Details for creating a new record. |
Update button |
Saves updates to the record. |
Delete button |
Deletes the current record. |
Refresh | Refreshes any dynamic data displayed in the Details. |
Close | For pop-up view only; closes the pop-up view of this task. |
Creating a Variable Specific to a Trigger, Task, or Workflow
To create a variable that is specific to a single trigger, task, or Workflow:
Step 1 | From the Automation Center navigation pane, select Trigger > <trigger type> or Tasks > <task type>. The records list for that trigger or task type displays. For example: |
---|---|
Step 2 | Open a task on the list and click the Variables tab to display a list of any currently defined variables specific to that record. |
Step 3 | Click the New button to display Variables Details for a new variable. |
Step 4 | Using the field descriptions provided for Global Variable Details as a guide, complete the fields as needed. |
Step 5 | Click the Save button, or right-click in the Details and click Save, to save the record. |
Step 6 | If appropriate, repeat these steps for any additional variables you want to add. |
Automatically Incrementing a Variable
For example: To increment ${counter
}, use a Set Variable action to set ${counter
} with a value of ${_trim(${__add("${counter}", "1")})
}.