Static VARA scope (validity area)

[Michael A. Lowry]

The documentation of the scope setting of static VARA objects is a bit misleading, so I wrote up a clearer description.

 

Scope

Defines the how the variable will behave if no key is specified when a VARA object  is accessed.

 

This setting can be used to simplify the script that writes values to VARAs 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 VARA object. For all values of scope except Freely selected, the key is optional, and the default key used to access the VARA if no key is specified depends on the characteristics of the task that is accessing the VARA.

Scope	Key optional	Key used to access variable if none is specified
No scope	✔	*
Freely selected	✘	Runtime error U00003712 will result if no key is specified.
Host	✔	The name of the agent on which the task is running
Task	✔	The name of the running executable object
Workflow name	✔	The name of the parent workflow of the task
Workflow session	✔	The run ID of the parent workflow in which the task is running (The row corresponding to the workflow session will be deleted from the VARA when the workflow is deactivated.)
User	✔	The name of the executing user (including /DEPT where DEPT is the department)
User session	✔	The run ID of the user session (The row corresponding to the user session will be deleted from the VARA when the user logs out.)

[Michael A. Lowry]

The documentation page for Static VARA objects states of the Scope field:

This setting can be used to simplify the script that writes values to variables or reads them.

Here is an example. Let’s say you want to access (read/write) a row in a static VARA object where the row name (key name) is the name of the executing user. If the VARA object has the scope Freely selected, then 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, then 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#,,1)
:PRINT "Value: &Value#"

Admittedly, the script is not that much simpler. Perhaps VARA scope existed before the Automation Engine provided conveniences like predefined variables for user name, workflow name, etc.

The two scopes that may be a bit more useful are User session and Workflow session. With these two scopes, the default key that is used if none is specified is the user session ID or the workflow run ID, respectively. And importantly, with these two scopes, the rows are deleted from the VARA object when the corresponding session/run ID is removed from the Activity table.

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.

: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#,,1)
:PRINT "Value: &Value#"

They key used to write the values will be the session ID of the user who runs the script. In my case, 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 session ID of my user session, visible under Users in Administration (AWI) or System Overview (JUI). As soon as I logged out, this row was 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.

[Michael A. Lowry]

Automic added some of my explanatory text & examples to the documentation page for static VARA objects.

[Michael A. Lowry]

I opened a new enhancement request suggesting a couple of changes to this feature:

Rename VARA Scope to ‘Default key’ & add options