ActiveBatch Variables

This section provides a general overview of ActiveBatch variables (constant and active) where they are defined, where they are used, how they are resolved, their scope, and other notable facts.

 

A variable stores a value. Every variable has a name and value. The variable name is referenced in objects that support the use of variables. ActiveBatch supports two types of variables: ActiveBatch and Execution.

 

ActiveBatch - These variables (constant or active) are declared in the “Variables” section of an object definition and are evaluated during the pre-processing phase (before a Job is dispatched) of a Plan or Job. Once the Job has been dispatched, ActiveBatch variable evaluation has already been performed by the Job Scheduler.

 

  • Constant variables maintain a constant hard-coded value, specified by the Job author. They can be a string, integer, double, or reference another variable (the referenced variable would be evaluated first).

  • Active Variables are derived from a finite list of data sources that are built into the product, and are read-only. Currently 18 data sources are supported. They are called "active" variables because the data source results may vary from one Job run to next. They are not actively changing during Job execution. As stated above, constant and active variables are resolved before a Job begins execution.

 

Execution - Execution Variables and Functions are declared at execution-time, typically as part of a Jobs Library Job step. This means the scope of an execution variable is typically limited to the Job that is currently executing. That said, execution variables can be stored within an ActiveBatch variable when a value needs to be passed to a downstream (following) Job or Plan.

 

Note: Please click on the Execution Variables link above to learn more about this variable type, as the remaining information in this section applies to ActiveBatch variables - constant and active.

 

Variable names can consist of the following characters: a-z, A-Z, 0-9, underscore (_). A variable name cannot begin with a numeric character. Any other characters are illegal. Variables are case-insensitive. Always try to uniquely name the variable. Unintended consequences can occur if you mix up your use of variables.

 

Note: Jobs Library Job step names are implicitly declared as variables under-the-hood. Therefore, do not name your variables the same name as a ActiveBatch Jobs Library Job step name.

 

Below are uses of ActiveBatch variables:

 

  • Passing data from one Job to another.

  • Variable substitution within a Plan/Job (soft code properties).

  • To act as a constraint (a variable value must be a certain value before the Plan/Job can run).

  • To be exported to a Job as an environment variable. This allows their names and values to be used at execution time.

 

Variables are defined (created) on: (All the objects below have a Variables property sheet, which is where variables are defined.)

 

  • Job Scheduler root

  • Folders

  • Plans

  • Jobs

  • References (Job and Plan)

  • Queues

  • User Accounts

 

Variables are used (referenced) by: (Variables are referenced using ${} syntax - e.g. ${Varname}).

 

  • Jobs

  • Plans

  • References (Job and Plan)

  • Alerts

 

Note: Variables defined on a Queue or User Account can only be referenced by Job and Job references.

 

Variable Scope

 

Variable scope (visibility) depends on where the variable is defined. See the table below which indicates visibility.

 

Object where variable is defined Scope
Root of the Job Scheduler All
Folder Child objects
Plan/Plan References Plan and its child objects
Job/Job References Job only
Queue All Jobs associated with the Queue
User Account All Jobs associated with the User Account

 

Order of precedence that the Job Scheduler uses to locate variable definitions when they are referenced

 

Note: The order in which the items are presented below is the order used by the Scheduler to locate the variable definition. As soon as a match is found, the Scheduler stops looking.

 

  • If a Job is triggered:

    • Queue

    • User Account

    • Job

    • Containers (Plans/Folder) within the Job's full path - parent container first, going all the way up to the Scheduler root, if necessary)

       

  • If a Job is triggered and an environment variable is defined:

    • Queue

    • User Account

    • Environment

    • Job

    • Containers (Plans/Folders) within the Job's full path - parent container first, going all the way up to the Scheduler root, if necessary)

     

  • If a Plan is triggered:

    • Plan

    • Containers (Plans/Folders) within the Plan's full path - parent container first, going all the way up to the Scheduler root, if necessary)

     

  • If an Alert references a variable:

    • The scheduler looks to the object that is associated to the Alert

    • For example, if a Job is using the alert, it looks for the variable on the Job's:

      • Queue

      • User Account

      • Job

      • Containers (Plans/Folders) - parent first, going all the way up to the Scheduler root, if necessary. The Scheduler does not look on the container(s) where the Alert object is stored.

 

Overriding variable resolution order of precedence

 

There are three ways you can override the order in which the Scheduler resolves variables. If you use one of these options, you are essentially telling the Scheduler where to look to find the variable definition. The variable must be defined where you specify the Scheduler to look, or it will be marked as missing.

 

The override syntax is described below. If you use an override option, you must place the override syntax in front of the variable name (for example, ${../VarName}.

 

../ The "dot dot slash" represents a container (Plan, Folder or Scheduler root). This syntax is self-referencing because the two dots mean “go up one level” from this point (Job). You can specify one or more ../'s, where each ../ represents a container in the object's full path, starting with the parent container.  For example, if a Job is triggered and its full path is Folder1/Folder2/Plan1/JobA, and a variable referenced in JobA is ${../../VarName}, the Scheduler would look for the VarName variable definition on Folder2 - the second container closest to JobA (since there are two ../ references). You can use as many ../ references for which there are containers.

 

- The "dash" represents an upstream Job (works with completion triggersClosed A completion trigger provides the ability for a Job or Plan to trigger another Job or Plan after it completes. You can determine which jobs or plans to trigger based on how your Job or Plan completes. For example, you can trigger one set of jobs if your Job completes successfully, and another set if your Job fails. ). When JobA triggers JobB using a completion trigger, JobB can access a variable defined on JobA by referencing it using this option.  The variable syntax is as follows: ${-VarName}. Only one dash in front of the variable name is supported.

 

// The "slash slash" represents the Job or Plan that started the batch run. There is always an initial trigger that starts a batch run (Job, Plan or reference is triggered).  Whatever object is initially triggered is where the Scheduler will look to find the definition when using this option.  The variable syntax is as follows: ${//VarName}.

 

Note: This above override syntax can be used with Built-in Variables variables (for example ${-@LogFileName} would retrieve the Job log file name of an upstream Job).

 

General notes about ActiveBatch variables:

 

  • Constant and active variables are referenced using ${} syntax (e.g. ${VarName}). If an active variable returns multiple fields from a data source, the syntax is ${VarName.DataSourceFieldName}.

  • You can concatenate variables by placing them side-by-side, for example, ${app_path}${filename}.

  • To treat ${ as a literal, double the substitution sequence (i.e. ${$( would yield a literal ${ ).

  • You can nest variables by placing a space between variable name sequences. For example, ${ ${month}Password} Where “month” is Jan, Feb, Mar, etc. would yield variable names of JanPassword, FebPassword, etc. The space between the variables is critically important to avoid invoking the literal escape sequence.

  • There are a few areas within ActiveBatch that substitution syntax (e.g. ${})should not be used when referencing a variable, because all unquoted strings are implicitly considered to be variables. The variables could be any type (active, constant, execution and built-in).

    • Constraint Logic property (on the Constraints property sheet)

    • The IfBranch Jobs Library Job Step (and any other flow control steps that support an expression property)

    • The Expression Jobs Library Job Step

    • Any Jobs Library Job step property where the name is preceded by an "=" sign (e.g. ForEachItem Jobs Library Job step).

 

To add, edit or remove a variable, navigate to the object's Variables property sheet, then click the desired operation. The image below is taken from a Job object.

 

 

Constant variables are identified with a leftmost blue icon, and active variables are identified with the purple icon.

 

When you click the Add or Edit button, the Variable dialog will appear, which is where each variable is configured.