XML Variables

XML variable objects store one value for one or more named keys. Their data must have a well-formed XML structure.

This topic provides information on the following:

Overview

XML Variable objects are a special type of the static Variable object. Although a static object by definition, they contains one value column instead of five. In addition, their data type must be XML, and it must have a well-formed XML structure. They may be used to temporarily store complex data as XML structure in the Automic Workload Automation system. This data then my be referenced and used in PromptSet objects, in Script objects, and other script contexts system-wide.

If you try to use other data types than XML or incomplete XML structures with this object, an error message will be displayed.

The use of XPath expressions with the Variable object XML is possible, as described also in the individual sections of the relevant script functions. Depending on the database the Automic Workload Automation system is being used with, individual XPath expressions may work differently. In such cases please check with the database's vendor.

If you use the Automic Workload Automation with an Oracle database, the attribute values of XML data used in this Variable object should not contain more than 4000 characters.

XML data can use only character encoding which is compatible with the character encoding in the database connection.

PromptSet variables are supported in select fields for BACKEND, EXEC, FILELIST, SEC_SQLI, SEC_SQL, SQLI, SQL, and XML variable types. Using PromptSet variables are necessary when using the Dynamic Reload feature.

Field/Element

Description
Key

The key for the XML data structure entered in the "Value" field. You may set an individual key.

You can include PromptSet variables here when using the Dynamic Reload feature for Combobox prompts. When PromptSet variables are used in dynamic Variable objects, and you click Preview, you will get an error. This is because the PromptSet variables do not exist in the dynamic Variable object. However, the PromptSet variables will be resolved when objects including the PromptSet are executed.

Value

The data to be stored and used in XML format.

You can include PromptSet variables here when using the Dynamic Reload feature for Combobox prompts. When PromptSet variables are used in dynamic Variable objects, and you click Preview, you will get an error. This is because the PromptSet variables do not exist in the dynamic Variable object. However, the PromptSet variables will be resolved when objects including the PromptSet are executed.

In order to edit the XML data, you may use the cell editor, which may be opened by clicking the pencil symbol, when the "Value" cell is activated by a mouse-click, as shown below. For details on the cell editor and its use see the "Static" category above.

Retrieving a List of Variable Object Values with the PREP_PROCESS_VAR_XML Script Function

Use the script function PREP_PROCESS_VAR_XML to access all or several particular entries of a variable. This prepares the processing of a data sequence.

Attributes Page

To Define the Variable Attributes

  1. Specify the Data & Formatting settings:

    Field

    Description
    Data Type

    The data type decides the format of the variable's values in the first value column. The data type "Text" is always used for all other value columns.

    • Text: An alphanumeric string. Blanks at the end are removed, leading blanks are kept. If the Limit Text Length checkbox is not checked, there will be no limit to the length of the character string.

      You can format the string further:

      • Select Limit text length to display the Max. text length input box allowing you to limit the text length.
        Possible values: 1 to 1024
      • Select Force upper case to convert the variable's text to upper case.
    • Number: Singed integer, i.e. a number between 0 and 2147483647.

      You can format the string further:

      • Select from the Output format drop-down list, how the number will be displayed.
      • Select Set Min. value to display the Min. value input box.
        Possible values: max. 16 digits before and 16 digits after the decimal point
      • Select Set max. value to display the Max. value input box.
    • Time: The default time format is hh:mm:ss. You can:
      • Select another format from the drop-down list.
      • Define a minimum and maximum value.
    • Date: The default date format is yyyy-mm-dd. You can:
      • Select another format from the drop-down list.
      • Define a minimum and maximum value. Note that you cannot define a date before 01.01.1980 as the minimum value.
    • Timestamp: The default timestamp format is yyyy-mm-dd hh:mm:ss. You can:
      • Select another format from the drop-down list.
      • Define a minimum and maximum value. Note that you cannot define a date before 01.01.1980 as the minimum value.

    The exact format of the selected data type (with the exception of "String") can be determined in the Output Format field.

    The data type of the values that are available in the first column is checked. The variable's data type must match the data type of the first column returned by the SQL statements when you use the sources "SQL" or "SQL internally". Data can also be processed using specific SQL statements. An error occurs if static variables should be stored or dynamic variables are accessed and the data types do not match.

    Note the following if you change the data type of static Variable objects that already include values:

    • You can easily change "Number", "Timestamp", "Time", and "Date" to "Text". The values are converted without any changes.
    • An output format must be selected if "Text" has been changed to "Number", "Timestamp", "Time", or "Date". When the Variable object is saved, the system verifies that the values match the specified format.
    • You cannot directly modify the data types "Date", "Time", "Number", and "Timestamp". They must be converted to the data type "Text" before you can modify them.

    The data type of variables with the type "Multi", "SQL", or "SQL internally" can be changed at any time.

    The data type of the script variable in question ("float", "signed", "unsigned", or "string") is irrelevant in values that have been retrieved from Variable objects with the data type "Number" when using the script element GET_VAR. The value can always be stored. Algebraic signs and decimal places are removed if they are not supported by the script variable's data type. The values are always passed on to the script as a "string" if a different data type has been specified in the Variable object.
    Output Format

    This setting defines the format that should be used to store values in the Variable object (source: static variables) or to retrieve values from the data source (dynamic variables).

    The contents of this selection menu depend on the data type. Several different formats are available for each data type (except for the String type).

    The output format only refers to the first column. In static variables, this is the column Value 1; in Database and Multi variables, it is the first basic column. Note that Multi variables use the first basic column as their reference column. This means that the source variable's output format can affect the retrieved values.

    The output format of static variables for a particular datatype can be changed at any time. In doing so, the values are converted to the new format. If the values do not match the old format, they cannot be converted to a new format.

    The format that is used to enter value in static variables is irrelevant unless it is an AE-supported format of the data type in question. The values are then converted to the relevant output format.

    The data type "Text" does not show this combo box.

    Data type Available formats Default format

    Timestamp
    • YYYYMMDDHH24MISS
    • YYYY-MM-DD HH:MM:SS

    YYYY-MM-DD HH:MM:SS

    Date
    • DD-MON-YYYY
    • DD-MON-RR
    • MM-DD-YYYY
    • YYYYMMDD
    • MMDDRR
    • DDMMRR
    • MM-DD-RR
    • MM/DD/RR
    • YYMMDD
    • YY.MM.DD
    • YY-MM-DD
    • YYYYMMDD
    • YYYY.MM.DD
    • YYYY-MM-DD
    • DDMMYY
    • DD.MM.YY
    • DD-MM-YY
    • DDMMYYYY
    • DD.MM.YYYY
    • DD-MM-YYYY
    • MMDDYY
    • MMDDYYYY
    • MM/DD/YY
    • MM/DD/YYYY

    YYMMDD
    Time
    • HHMMSS
    • HH:MM:SS
    • HHMM
    • HH:MM
    • MMSS
    • MM:SS

    HHMMSS
    Number
    • 00.00
    • +00.00
    • -0.00
    • 0
    • +0
    • -0
    • 16 digits
    		 16 digits

    Some date formats include RR as a placeholder for the abbreviated year. Having both YY and RR accommodates different century-counting conventions based on the two digits of the abbreviated year value.
    YY - The current century applies for numbers between 00 and 80. The previous century applies for 81 - 99. 
    RR - The current century applies for numbers between 00 and 49. The previous century applies for 50 - 99.

    For example:
    Date format DDMMYY and the resulting complete dates:
    010305 - corresponds to 01 March 2005
    010365 - corresponds to 01 March 2065
    010380 - corresponds to 01 March 2080
    010385 - corresponds to 01 March 1985

    For example:
    Date format DDMMRR and the resulting complete dates:
    010305 - corresponds to 01 March 2005
    010365 - corresponds to 01 March 1965
    010380 - corresponds to 01 March 1980
    010385 - corresponds to 01 March 1985

    The time value for the data type "Time" or "Timestamp" must be a 4 or 6-digit number. Decimal places are removed. 4-digit numbers are converted to hours and minutes.

    Examples:
    Data type: Time
    Output Format: HH:MM:SS
    Value of the user or the data source: 1234, 1234.5, 123400, 12:34, 12:34:00
    Resulting variable value: 12:34:00

    Data type: Timestamp
    Output Format: YYYY-MM-DD HH:MM:SS
    Value of the user or the data source: 20110325 2201, 20110325 2201.5, 20110325 220100
    Resulting variable value: 2011-03-25 22:01:00

    Set min. value

    Min. value

    Enforces a minimum value.

    The data type "Text" does not show these fields.

    Set max. value

    Max value

    Enforces a maximum value.

    The data type "Text" does not show these fields.

    Limit text length

    Max. Text Length

    Enforces a maximum character length.

    Allowed values: 1 to 1024

    If this option is deactivated, there is no limit.

    The Key column of VARA objects has a maximum limit of 200 characters. This limit always exists and cannot be increased or deactivated.

    The result column of dynamic variables has no limit. The length depends on the value columns.

    In static and dynamic variables, this limit refers to the first value column. The Key or result column is not checked.

    Values that exceed the maximum length are excluded.

    Only the data type "Text" shows these fields.
    Force upper case

    Lower case letters that are used in variable values are automatically converted to upper case. This only affects the first value column.

    Only the data type "Text" shows this field.
    Sort by column

    Specifies the column whose values are used to sort the entries.

    Possible options: Key, 1, 2, 3, 4, or 5
    Sort order

    Type of sorting.

    Possible options: Descending or ascending

    The underlying type of sorting such as binary or alphabetic, depends on what is defined in your database.

  2. Specify the Variable Settings:

    Field

    Description
    Type This read-only field shows STATIC as the variable type. You determine the variable type when you create the object. It cannot be changed once the variable is defined.

    Scope

    This setting can be used to simplify the script that writes values to variables or reads them. Usually, the key must be specified as a parameter in the script element :PUT_VAR or GET_VAR. However, this makes it difficult to ensure that values are stored with unique keys. By specifying a particular scope, you can simplify design of scripts that write to or read from the variable. For all values of scope except Freely selected, the key is optional, and the default key used to access the variable if no key is specified depends on the characteristics of the task that is accessing the variable.

    For: Specifying a key is: The key used to access the variable, when none is specified is:
    No scope Optional *
    Freely selected Required

    N/A

    Since a key is required, Runtime error U00003712 occurs if a key is not specified.
    Host - each host name Optional The name of the agent where the task is running
    Task - each task name Optional The name of the running executable object
    Workflow name - each workflow name Optional The name of the parent workflow of the task
    Workflow session - each workflow session Optional The run ID of the parent workflow in which the task is running
    User - each user name Optional The name of the executing user
    User session - each user session Optional The run ID of the user session

    The entry (row) corresponding to the user session will be deleted when the user session ends.

    If the VARA object has the scope Freely selected, you must specify the key when writing to or reading from the VARA object.

    :SET &VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERNAME"

    :PUT_VAR &VARA_NAME#, &$USER#, "Mercury", "Venus", "Earth", "Mars", "Jupiter"

    :SET &VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

    :PRINT "Value: &Value#"

    If the VARA object has the scope User - each user name, you can omit the key when accessing the VARA object.

    :SET &VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERNAME"

    :PUT_VAR &VARA_NAME#, , "Mercury", "Venus", "Earth", "Mars", "Jupiter"

    :SET &VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

    :PRINT "Value: &Value#"

    The two scopes that are more useful are User session - each user session and Workflow session - each workflow session. With these two scopes, the default key that is used if none is specified is user session ID or the workflow run ID, respectively. And importantly, with these two scopes, the rows are deleted when the corresponding run ID is deactivated.

    For example, let’s say you want to store some information in a VARA object as long as a user is logged in, but remove the information when the user logs out. You can set the scope of the VARA object to User session - each user session, and put values into the VARA object without specifying a key as shown below.

    :SET &VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERSESSION"

    :PUT_VAR &VARA_NAME#, , "Mercury", "Venus", "Earth", "Mars", "Jupiter"

    :SET &VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

    :PRINT "Value: &Value#"

    The key used to write the values will be the session ID of the user who runs the script. In this example, running the script caused the following row to be added to the VARA object:

    Key Value 1 Value 2 Value 3 Value 4 Value 5
    1168010 Mercury Venus Earth Mars Jupiter

    1168010 is the user's session ID. Users' session IDs are visible under Users in the Administration perspective. As soon as the user logs out, this row is removed from the VARA object.

    The scope Workflow session - each workflow session works in a similar way. Any row written to such a VARA object (without a key specified) will be automatically removed as soon as the executing workflow is deactivated.

  3. Specify the Script Access settings:

    You can specify what happens if a key is not found with the If key not found radio buttons.

    To:

    Choose:
    Have an error message displayed if an object attempts to access an item that is not available at runtime via script Return error
    Not use the result of output format of when it is " " Return initial values

  4. In client 0 only: Specify how the VARA object will behave in clients other than 0.

    When you define Variable objects in system Client 0, they can be used in other clients, either because they refer to the values set in the Variable in Client 0 or because you copy the original object from Client 0 to other clients and, if necessary, edit its values in the target clients.

    With the Share object with other clients and options you define the behavior of this Variable object in clients other than 0:

    Option

    Description
    Don't share but allow duplicates

    If you select this option, this VARA object is available in clients other than 0 and you can use it there. You can modify all of its parameters in the non-0 clients, which can then be different per client.

    The name of the variable can be kept in non-0 clients. This means that if there is already a VARA object in the non-0 client with this name, two independent VARA objects with the same name will be available.

    You can modify all the parameters of both variables independently per client.
    Share and allow read-only access

    If you select this option, this VARA object is available in clients other than 0 and you can use it there but you cannot modify any of its parameters.

    Additionally, the name of this VARA object must be unique system-wide.
    Share but keep attribute settings from system client

    If you select this option, this VARA object can be copied to non-0 clients. If you do so, it keeps all the definitions made on the Attributes page but you can edit the Key and Value settings in the non-0 clients. Each client can have its own Key/Value definitions.

    Only available for STATIC variables.