Variables and VARA Objects

Variables and VARA objects are placeholders for values that you use in executable objects. When an object is generated, the system resolves the variables and references to VARA object to retrieve values from various sources. The values of variables and VARA objects are resolved at activation time or at runtime, depending on what is defined on the Attributes page of the object definition.

As a developer and object designer, you create variables and VARA objects and use them in executable objects.

This topic outlines the differences between the various types of variables and VARA objects.

This page includes the following:

VARA Objects

VARA objects are entities with their own attributes like any other object in your system. The following types of VARA objects are available:

  • Predefined VARA objects for system and Client values
  • User-defined VARA objects

Predefined VARA Objects for Client Values

Your system contains predefined VARA objects that store Client values. These objects govern the behavior of the Client and its processes. The access to this type of VARA objects is typically restricted to administrators.

For more information, see List of VARA Objects for Client Values.

User-Defined VARA Objects

As a developer and object designer, you create VARA objects to store and use values. Your VARA objects can retrieve values dynamically from various sources (databases, directories, and so forth). You can also assign them static values. User-defined VARA objects are not provided with the installation. However, your system contains templates for various types of user-defined VARA objects.

Use VARA objects to separate object configuration from automation logic in Workflows, Actions and Action packs. Usually, Workflows need input parameters for processing. These parameters are configuration values such as Agents, Login objects, and so on. These values can change over time, and they might also be different depending on which system your Workflows run in (for example, development, test or production).

Instead of manually changing the configuration values in all your Workflows and systems, you can store those values in variable (VARA objects). Then, you reference the VARA objects in your Workflows. There are various ways of referencing VARAs in Workflows.

For more information about how to configure Workflows efficiently by using VARA objects, watch this video: Video: Efficient Configuration Using VARA Objects.

VARA Objects and Scripts

The Automation Engine scripting language provides script elements that let you perform many operations with VARA objects. This list provides links to some of the most common ones:

  • GET_VAR

    Use this script function to populate the attributes of objects with VARA objects

  • PREP_PROCESS_VAR and PREP_PROCESS_VAR_XML

    Use this script function to access all or some of the entries of a VARA object and to prepare the processing of a data sequence

  • CREATE_OBJECT

    Use this script function to create a STATIC VARA object

  • MODIFY_OBJECT

    Use this script function to modify a STATIC VARA object

  • REMOVE_OBJECT

    Use this script function to delete a VARA object

For more information, see:

Variables

There are various types of variables to store and pass values. Some variables are predefined and cannot be set by users, while you can freely create others. Variables are resolved when the task is generated. Unlike VARA objects, variables are stored in scripts and are not objects in their own right.

Script Variables

Script variables play a fundamental role when you write scripts. Create them to store and pass values in the scripts that you define on the Process pages of executable objects. You can also define some object properties with script variables.

Script variables can contain only text. Their values cannot contain multiple lines. Variables declared as arrays can contain multiple values.

You use script statements such as :SET, :PSET, or :RSET to set and declare script variables, and assign values to a script variable. You use :DEFINE to define the variable as an array. With :GET_SCRIPT_VAR and :SET_SCRIPT_VAR you set and read the values of script variables by indirect reference.

Script variables are displayed in purple in the script editor.

Examples

A numerical value is assigned to a script variable:

:SET&NUMBER# = 1

The value of one script variable is assigned to another variable:

:SET&NR# = &NUMBER#

Object Variables

Object variables retrieve values from object properties (values in its input fields), or from the runtime instance of the object (the task). You define object variables on the Variables page of executable objects. Alternatively, use a :PSET script statement on the Process pages. These object variables are stored in the object definition. Child tasks can inherit object variables from parent objects.

Object variables can contain multi-line text. They are displayed in purple in the script editor.

PromptSet Variables

If you have defined values in a PromptSet, these values are stored as PromptSet variables. When the PromptSet is assigned to an object, these values are used during its execution. However, they can be overridden in one of the following ways:

  • Manually upon object execution
  • You can specify different values when the PromptSet is called
  • By defining different values on the object PromptSet page
  • When the object is executed from within a Workflow or a Schedule

The type of data that PromptSet variables can contain depends on the element type in the PromptSet where they have been defined. Once a PromptSet variable has been defined, its value is read-only and cannot be changed.

PromptSet variables can also be defined using :READ statements in scripts. They are displayed in purple in the script editor.

Storing Variables in the Read Buffer

The read buffer temporarily stores values so that other tasks can use them. These values are deleted after they have been consumed. If a process contains several tasks, the read buffer variables store their values in chronological order. Those values are also consumed in chronological order. For example, in a process with three tasks, the first time that the ACTIVATE_UC_OBJECT function is used, the values that are stored by the first task are used.

Use script statements to store values of script variables or PromptSet variables in the read buffer when you activate an object through a script with ACTIVATE_UC_OBJECT.

Your system includes predefined variables (UC_CAUSE* variables) that retrieve details of a task and temporarily store the values in the read buffer. Values are stored in the read buffer when you specify follow up or alternative actions (the execution of another object) if a condition or status is not met.

  • Executable objects

    • If the status of a task is not in the range that has been specified in the Return Code Handling section on the Runtime page of the object definition
    • If the status of a task is not the one that has been specified in the Task Result Evaluation section on the Attributes page

  • Workflows

    • If a task cannot be executed at the time that is specified by the checkpoint as defined in the task Time & Dependencies tab
    • If the conditions defined for a task in the Dependencies section (Time & Dependencies tab) are not met
    • If the runtime of a task differs from the expected value as defined in the task Runtime tab

  • ALARM and STANDARD Notifications

    If the object escalates by executing a different CALL object

Variable Names

Variables names have the following syntax:

  • Leading ampersand character (&)

  • The second character after the leading ampersand cannot be a number or a dollar sign ($). The reason is that the dollar sign is reserved for predefined system and object variables.

    Examples:

    &$NAME#, &$STATUS#, &$RUNID# are predefined object variables

    &$SYSTEM#, &$CLIENT#, &$USER# are predefined system variables

    &DATETIME1#, &string# are script variables

  • Maximum length: 32 characters

    The leading ampersand does not count. The length of the returned value is not limited.

  • Allowed values: A-Z, a-z, 0-9, , _, @, ยง and #

  • Do not use accented characters

  • Variable names are not case sensitive

  • Variable name termination

    In this documentation, variable names end with the # character. It is not mandatory to end variable names with it, but it is a recommended convention. The reason for this is that variable names may not be sub strings of other variable names. For example, if you have a variable called &UNR you cannot define a variable called &UNR_SC because the former is a sub string of the latter. The last # symbol in the variable name helps you get around this limitation. It is not mandatory but it is good practice to use it, because it ensures that names do not overlap. Using the previous example, &UNR# is not a sub string of &UNR_SC#.

    You can use any character that is allowed in a variable name as ending character.

    Important!

    • Use the ending character consistently
    • Do no use the ending character in the middle of variable names

Examples:

  • Variables for system and object values: &$CLIENT#, &$DATE_format#, &$DATABASE_NAME#
  • Variables: &HEADER#, &ROW#, &parentname#

Retrieving Values

In executable objects, retrieve values from variables and VARA objects in the following ways:

  • In input fields and combo boxes (where supported), type the variable name

  • Click the variable icon where available to open the Select Variable dialog, where VARA objects and variables are grouped as follows:

    • Object Properties

      Object variables that retrieve values that are either specified in the object properties or that are derived from its runtime instance (the task)

    • Automation Variables

      List of system and Client VARA objects

    • Variable Objects

      List of user-defined VARA objects available in the current Client

Defining Object Attributes using Values from VARA Objects

In the input field where you want to use the VARA object, enter its name in curly brackets. Optionally, specify key and column parameters to select a specific value in the VARA object.

Syntax

{ Variable object [, Key [,Column number]] }.

Example

The following expression is replaced by a value from a VARA object when the task is generated:

{MONITOR_SP1, 2, 3}

where

  • MONITOR_SP1 is the name of the VARA object
  • 2 is the key
  • 3 is the column

The Key and Column parameters are optional. If you do not specify the parameters, the system selects the value as follows, depending on the type of VARA object.

  • Static VARA objects

    The expression is replaced by the value that is defined in the first column in the VARA object

  • Dynamic VARA objects

    The Column number is replaced with the value in the Results column

Retrieving Values from Variables and VARA Objects in Scripts

In scripts, retrieve values from variables and VARA objects in the following ways:

  • Call the following variables directly from your scripts

    • Script variables
    • Read buffer variables
    • PromptSet variables
    • Predefined system and object variables directly in your scripts.

  • To retrieve values that are stored in VARA objects, use script functions such as GET_VAR

    Important! Unlike script variables, you cannot directly call predefined VARA objects in scripts.

    Example: 

    The following script retrieves the path to the directory in which the Agent (WIN01) stores job reports.

    :SET &jobreport# = GET_VAR('UC_EX_PATH_JOBREPORT','WIN01')

  • To retrieve the value of an object attribute, use the GET_ATT script function.

    If the object attribute includes a variable such as an object variable, the system resolves the variable and retrieves the value. This function does not modify or replace the variable itself.

    Example:

    The following script retrieves the value of an object attribute with the GET_ATT script function.

    :SET&MYINTERNALACCT# = GET_ATT(&$INT_ACCOUNT#)

  • To retrieve values that are stored in the read buffer, use :READ script statements.

See also: