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.

As a system administrator, you maintain Client and system variables and VARA objects.

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

For more information, see:

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
  • Virtual Agent VARA Objects

As an administrator, you define system settings that determine what should happen when VARA objects cannot be resolved. For more information, see VARA_ERROR_ON_REPLACEMENT in UC_CLIENT_SETTINGS - Various Client Settings.

Predefined VARA Objects for System and Client Values

Your system contains predefined VARA objects in Client 0 that store system and Client values. These objects control the behavior of the system and of the Clients. The access to this type of VARA objects is typically restricted to administrators.

VARA objects that contain system-wide parameters must remain in Client 0.

VARA objects that govern the behavior of Clients and their processes can be stored in the respective Clients.

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

Note: You cannot use predefined VARA objects in Job Forms.

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 define VARA objects, see User-Defined VARA Objects.

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

Virtual Agent VARA Objects

Agent variables store Agent information and settings. They are available either in Client 0 or in the database. For a list of all available Agent variables, see List of Agent Variables.

Note: You cannot set values in Agent variables by script.

As an administrator, specify all Agent variables in the [VARIABLES] section of the Agent INI file. By doing so, you ensure that the variable values are set in accordance with your environment.

Example

[VARIABLES]

UC_HOST_CODE=UC_CODE

UC_HOST_JCL_VAR=NSK

UC_EX_PATH_BIN=$data01.uc4

UC_EX_PATH_CACHE=c:\AE11\agents\windows\CACHE\0100\
UC_EX_PATH_JOBREPORT=$data01.
UC_EX_JOB_MD=$data01.uc4.ucxjns1r

Use script elements such as GET_VAR to retrieve values from Agent variable.

Syntax

GET_VAR (Agent variable,Agent name)

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.

Predefined Variables

Predefined system variables have always the same value across the whole Client or Automation Engine system. They can be accessed by all tasks. The following types of predefined variables are available:

  • Predefined variables for system values

    These variables retrieve values from the Automation Engine or from the Client.

  • Predefined variables for object values

    Predefined object variables depend on the executable object that used them and on the status of the object.

You can use these predefined variables in scripts and in object definitions. In scripts, variables are resolved and replaced by values when the script is processed. In object definitions, the values of these variables are replaced after the script has been processed. You can use predefined variables to modify object attributes.

Predefined variables are displayed in blue in the script editor.

Notes:

  • Do not use a system or object variable in its own object attribute. If variables are used in their own attribute, they are not replaced when the script is processed.
  • Do not define attributes that refer to each other through variables. Attributes that refer to each other through variables are not replaced when the script is processed.

For more information, see Variables for System and Object Values.

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#

For more information, see:

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.

For more information, see:

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.

For more information, see:

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

  • Schedules

    • If the runtime of a task differs from the value that is defined in the Runtime task properties
    • If the status of a task differs from the status that is specified in the Result settings

  • ALARM and STANDARD Notifications

    If the object escalates by executing a different CALL object

For more information, see:

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/bytes

    Notes:

    • Variable names can use a paragraph character (§) in their names where the '§' represents part of the extended ASCII character set (such as "ö" or "â") and takes up two bytes in UTF-8. Using this character as part of your variable name reduces the available bytes by two instead of one. We recommend that you verify if you use variable names containing '§'. If they exceed the maximum length of variable names, ensure that the used variable names are not cut, which may lead to errors.
    • 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:

    • System Properties

      System and Client variables.

    • 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

For a complete list of system and object variables, see Variables for System and Object Values

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.

For more information, see:

See also: