Active Variables

This section describes the active variable data sources.

 

The ActiveBatch active variable supports a variety of data sources. The “active” part of an active variable is the data source. That is, the data source may change over time. All data sources are read-only. You can only retrieve information; data cannot be written to the source.

 

Since active variables access a variety of data sources, it is required that the Job Scheduler use credentials configured in a User Account object as the account to resolve an active variable with. You can specify the User Account object on the variable property sheet, when defining an active variable. The property name is Credentials. If you leave the Credentials property blank, the system uses a default User Account object as follows:

 

• If a Job/Job Reference is triggered

  • Defaults to the Job's Execution > User Account

• If a Plan/Plan Reference is triggered

  • Defaults to the Plan's Execution > Default Credentials to use for Variable and Constraint Processing

 

Using the defaults is convenient, as it avoids the need to assign security on every active variable you create. Both the Credentials account specified on the variables property sheet, and the Execution default User Account would need to be granted access to the data source so the Scheduler can successfully resolve the active variable.

 

Some data sources allow additional security to be established apart from Windows security. For example, the SQL query active variable may need to specify database authentication credentials that are different from those specified with the Job.

 

When the active variable is successfully resolved, it is assigned a value. If the access is not successful, a null string is assigned to the variable, and it is marked as "missing" when you look at the instance history Variables tab. When a single result is produced, that result value is assigned to the variable. When multiple results are produced, ActiveBatch creates a structure within the variable using field names supplied by the data source. Access to the underlying members of a variable requires you use notation like this: variablename.fieldname (e.g. ${VarName.CustID}).

 

Below you will find an image that depicts the active variable data sources you can choose from.  Each active variable is described below.

 

 

Date Arithmetic

 

This data source uses the ActiveBatch Date Arithmetic facility so you can perform date arithmetic operations.

 

 

DateTagExpression is a property in which you can enter any legal Date Arithmetic Uses and Syntax expression.

 

DiskFreeSpace

 

This data source allows you to retrieve the amount of free space on the specified drive (and machine) in a unit that you select (Byte, Kilobyte, Megabyte or Gigabyte) into a named variable.

 

 

Computer Name represents the IP address, hostname or FQDN of the machine whose drive you want to retrieve this information from.

 

Device ID represents the drive letter of the disk drive that you want to retrieve free disk space from.

 

Unit represents a units-value that you want the numeric data to be reduced to. In other words, if Mb is selected you want the value 100 to represent one-hundred-million.

 

Disk Information

 

This data source retrieves various information concerning the specified disk drive letter (on the specified machine). The disk information is returned using the WMI Win32_LogicalDisk class into the named variable.

 

 

Computer Name represents the IP address, hostname or FQDN of the machine whose drive you want to retrieve this information from.

 

Device ID represents the drive letter of the disk drive that you want to retrieve the disk information on.

 

The information returned would be similar to what is depicted in the image below, which is the obtained from the instance history "Variables" tab.

 

 

Since this variable returns a structure, you would need to reference the desired return structure member as such: ${DiskInfoReturn.CreationClassName}.

 

Drive Exists

 

This data source determines if the specified drive letter exists. If so, a Boolean “Yes” is returned. If not, “No” is returned to the named variable. Note: The drive search performed on Job Scheduler machine.

 

 

Drive Name represents the local (Job Scheduler) drive letter you want to verify as to whether it exists.

 

File Content

 

This data source allows you to read the contents of a file into a variable. The maximum size that can be set is 64000 bytes. Note: If local context assumed, the file must be present on the Job Scheduler machine.

 

 

File Name is a property in which you enter the full file specification of the file whose contents you want to read.

 

Maximum Size is a property that represents the maximum amount of data that will be read.

 

File Exists

 

This data source determines if the specified file exists. If so, a Boolean “Yes” is returned. If not, “No” is returned to the named variable. Note: Search performed on Job Scheduler machine if local context assumed.

 

 

File Name represents the file specification you want to determine as to whether it already exists. If so, a Boolean “Yes” is returned. If not, “No” is returned to the named variable.

 

Folder Exists

 

This data source determines if the specified folder exists. If so, a Boolean “Yes” is returned. If not, “No” is returned to the named variable. Note: Search performed on Job Scheduler machine if local context assumed.

 

 

Folder Name represents the path specification you want to determine as to whether it already exists. If so, a Boolean “Yes” is returned. If not, “No” is returned to the named variable.

 

Inifile

 

This data source allows you to retrieve a value from an INI file’s specific named section. The value is set into your named variable.

 

 

File Name represents a full file specification of the INI file.

 

Section represents a named section within the INI file.

 

Value represents a named value within the specified section of the INI file.

 

Ping

 

This date source allows you to issue a ‘classic’ Ping to determine whether a system is alive and responding to ping requests.

 

 

ComputerName is a property representing the machine you want to ping. The machine can be specified as an IP address, hostname or FQDN. Note: The machine must be capable of responding to a ping request.

 

PowerShell Script

 

 

This data source is a Powershell script that allows you to retrieve a value or object based on its execution.

 

Script represents the Powershell script itself. The data returned must be one of: string, integer or Boolean (which is returned as True or False). Note: ActiveBatch currently does not support use of the #Import as part of this specific operation.

 

Registry Value

 

This data source allows you to retrieve the value of a registry value (from a specified machine, hive and key structure).

 

 

Computer Name represents the IP address, hostname or FQDN of the machine whose registry you want to access.

 

Hive represents one of the hives you can select with the dropdown.

 

Key represents a key structure specification where each key is separated by a backslash (“\”).

 

Value represents the registry value-name you want to retrieve a value from.

 

Service State

 

This date source allows you to retrieve the state of a specified Windows service (on a specified machine).

 

 

Computer represents the IP address, hostname or FQDN of the machine whose Service you want to access.

 

Service Name represents the name of the Windows Service (not the description). In this example, the ActiveBatch Job Scheduler service name is being used.

 

SQL Query

 

This data source allows you to issue a SELECT query and place a single row of data into the named variable. The variable will be a structure that consists of the columns (or fields) that are returned from your query.

 

 

ConnectionString is a property that represents a Microsoft UDL connection string.

 

UserAccount is a property that contains a User Account object whose security credentials will allow the proper access to the database. Note: This property is only used for databases which use SQL database authentication (not Windows).

 

CommandText is a property that contains the SELECT statement in which the result set will consist of zero or one (1) row of information. If your command text returns more than 1 row, only 1 row is stored in the variable, the remaining rows are discarde.

 

Note: If you need to process more than one row of data, please see the For-Each-Row Jobs Library Job Step.

 

User Input

 

This data source allows you to request data from a user interactively. It is used when configuring a variable constraint. The user supplies the data through the “Respond” command.

 

Note: This Active Variable action can only be defined and performed within a Constraint. Therefore, it is not accessible via the Variables property sheet. You must navigate to the Constraints property sheet, then, in the General section, click Add, then select Variable. You will see UserInput as an Active Variable option.

 

 

Message is the message you want to display.

 

Input Type is the type of data you are interested in. Ranging from OK CANCEL to Text.

 

Input Icon is the icon that will appear in the message box.

 

Generate Alert indicates whether this message should also be considered an alert (and appear in the Alerts View).

 

Severity indicate the type of message this is (i.e. Success, Error, etc).

 

The contents of the data entered is available when accessing the properties of the instance, then clicking on the Variables tab. See the built-in variable @Constraints. The image below depicts the contents of this variable.

 

 

VBscript Expression

 

This data source allows you to specify a legal VBscript expression. The expression can contain arithmetic, comparison, concatenation or Boolean operators. Boolean results are returned as “Yes” or “No” to represent true or false indications.

 

 

Evaluate Data Type is either True or False.

 

Value is your VB Expression.

 

Web Services

 

This data source allows you to execute a Web Services method and retrieve data to a named variable.

 

 

Service Description is a property representing the URL of the Web Service.

 

Method is a property representing the method of the Web Service.

 

Note: Microsoft SOAP Toolkit 3.0 must be installed on the Job Scheduler machine.

 

WMI Ping

 

This data source allows you to issue a WMI Ping to determine whether a Windows machine is alive and responding. The WMI Ping can be thought of as authenticated and higher-level ping since you need to present security credentials and the WMI service must be running.

 

 

Computer Name represents the IP address, hostname or FQDN of the machine you want to WMI ping.

 

Namespace represents a valid WMI namespace.

 

User Account represents a User Account object whose security credentials are appropriate for access.

 

WMI Query

 

This data source allows you to issue a WQL query using WMI and retrieve information that will populate the named variable you supply. The variable is a structure consisting of field name information for each member of the WMI class that’s selected. Only a single row of information can be supplied in this action.

 

 

Computer Name represents the IP address, hostname or FQDN of the machine you want to WMI query.

 

Namespace represents a valid WMI namespace.

 

Query String represents a legal WQL statement.

 

XPath Query

 

This data source allows you to issue an XPath Query on an XML file and retrieve various pieces of information from the XML file into a named variable.

 

 

File Name represents the full file specification of the XML file you want to issue the query on.

 

XPath represents a legal XPath Query expression.

 

Method indicates the type of information you want the query to return.