Execution Variables and Functions

 

Execution variables are primarily used with the Jobs LibraryThe Jobs Library is a type of Job. The Jobs Library consists of production-ready built-in Job Steps that perform various tasks that many customers use and/or need. For example, there are File System Job Steps that allow a user to manage files and directories (copy, rename, delete, etc.) on a target OS system. There are managed file transfer (MFT) Job Steps that allow a user to upload and download files using FTP, SFTP and FTPS. The Job Steps provide a script-less approach to building jobs and workflows. A Job Author enters the various Job Step properties, and ActiveBatch executes the tried and proved code to accomplish the task. Job type. Execution variables are sometimes referred to as context variables or runtime variables.  All the terms are referring to the same type of variable.

 

Many Jobs Library Job steps have a special property named “ContextName”. This property is populated with an execution variable name. The scope of the variable is limited to when the step is actually executing. This is very different from ActiveBatch variables (constant and active) which are resolved before the Job is dispatched to the Agent to run.  The Execution variable is being populated while the Job is running, therefore the variable is subject to change during runtime.

 

Note: To distinguish ActiveBatch variables from Execution variables, a slightly different notation is used. Execution variables are referenced with %{name}, whereas ActiveBatch variables use ${name}.

 

All Jobs Library Job steps return their status (success or failure) in a context variable. This means the success or failure of an upstream Job step can be obtained, via a context variable, from a following or downstream Job step. In addition, some steps return value(s), as indicated by a return value icon under the step. The return value(s) are also stored in context variables. Following or downstream Job steps can access a prior step's Return value (if applicable) or Status, since their values are stored in an execution variable.

 

Next, all looping steps (ForEachRow, ForEachValue, ForEachFile, etc.) return data that is accessible to nested steps within the loop - using the execution variable.

 

Lastly, execution variables can be created by a Job author using the Expression step located in the ActiveBatch category of Job steps. When a Execution variable is created using the Expression step, steps that follow the Expression step can access the execution variable.

 

See the example below that depicts the ForEachFile Jobs Library step that uses an Execution variable to access file specification information:

 

 

The ForEachFile Job step is an iterative step that searches for files. In this example, it is searching the directory “C:\extract” looking for files with a pattern of *.log. If any are found, each one will iteratively invoke the nested steps, which includes the Log and DeleteFile steps.

 

The nested Log step is using the ContextName property “File”. File is an execution variable within the Job step “ForEachFile”. Since the contextname property is used within the ForEachFile Job step, accessing the variable becomes ForEachFile.File (Step name.context variable name.itemname). As you can see in the above example, the “File” variable is actually a structure that represents various parts of a file specification. Once you’ve made the desired selection (e.g. %{ForEachFile.File.ParentPath}, add a closing curly brace “}” to complete the variable notation.

 

 

Note: Execution variable names are limited to the following characters: a-z, A-Z, 0-9, space and underscore. Any other characters are illegal.

 

Note: Jobs Library Jobs, like any other Job type, also support the use of ActiveBatch (constant and active variables) in Job properties. As always, they are resolved by the Job Scheduler before the Job is dispatched to an Agent to run.

 

In concert with Execution Variables are a series of functions that you can invoke to help perform various operations without using a Job Step. For example, let’s say you needed to replace some data within a string. ActiveBatch supports two (2) methods for deploying this operation: (1) in-line as part of the execution variable usage and (2) ActiveBatch Expression.

 

 

Suppose we wanted to rename a file as we processed it. In a partial example, the above figure searches for files with an extension of “.log”. As each file is found, the nested step “Log” is executed. Note that rather than specifying File.FullPath we’re using a function Replace to change the “.log” to “.processed_log”. This is an example of an in-line function.

 

 

In the above example, we refine this approach. By adding an ActiveBatch Expression step, we perform the Replace and save the change in another variable. This can be useful if we need to use that variable somewhere else in the workflow.

 

Function Name/Arguments	Description
AbatGetDate (date-tag [,base-date])	Uses ActiveBatch Date Arithmetic syntax for date-tag. Base-date is today if omitted; other Base Date is the base date for calculations. Returns a date string.
Concat (string-array)	Concatenates elements of a string array and returns a string.
Contains (string, search-string [,case])	Determines if ‘search-string’ is present within ‘string’. ‘Case’ is Boolean and if omitted or false indicates a case insensitive search. Returns a Boolean value.
DateAdd (date-part, number, date)	Add ‘number’ to date. Date-part determines the unit that ‘number’ is interpreted as. Date-part can be one of the following: yy = year; mm = month; dd = day; hh = hour; mi =  minutes; ss = seconds Returns a date.
DateDiff (date-part, date1, date2)	Subtracts the difference from ‘date2’ using ‘date1’ and yields a value that is interpreted by the unit of ‘date-part’ (see DateAdd above). For example, if ‘dd’ is specified the difference would be in days.
DateValue (year, month, day)	Create a ‘date’ using year, month and day arguments. Returns a date.
GetDate()	Provide today’s date and time. Returns a date.
GetPathPart (path-part, path)	Extracts a ‘part’ of the path specification provided. Pathpart can be one of the following: Server = UNC server; Share = UNC share; Device = device; directory = directory; Filename = filename; extension = extension; IsUNC = Does the path use UNC? Returns a string.
GetUtcDate ()	Provides today’s date and UTC time. Returns a date.
IndexOf (string, search-string [,case])	Returns an index (starting position; zero based) in a ‘string’ based on the search-string. ‘Case’ is Boolean and if not specified is assumed to be False in which a case insensitive search is performed.
Join (separator, string-array)	Joins elements of a string array and appends a separator character between each element. Returns a string.
Len (string)	Returns the length of a string.
PadLeft (string, total-width [,pad-char])	Pads a string to be right-aligned by inserting spaces to the left of the string. If ‘pad-char’ is specified then that character is used as the padding character. Returns a string.
PadRight (string, total-width [,pad-char])	Pads a string to be left-aligned by inserting spaces to the right of the string. If ‘pad-char’ is specified then that character is used as the padding character. Returns a string.
ParseDate (string)	Converts a date in many supported locale formats and returns a ‘date’.
Randomizer (field-mask, exceptions)	Generates a random set of characters based on the fieldmask and exceptions. Field-mask character values are: &=lowercase, %=uppercase, $=lower/upper case, ^=symbol, !=alphanumeric, +=Hexadecimal, #=Integer (0-9), *=wildcard, \=escape. Any other characters used are literal. Exceptions indicate characters not to use as part of randomizer function return value.
Replace (string, old, new [,case])	Replaces ‘old’ with ‘new’ in ‘string’. ‘Case’ is Boolean and if omitted or false indicates a case insensitive search. Returns a string.
Split (string, separator)	Splits a ‘string’ based on a separator character. Returns a string-array.
Substring (string, start [,length])	Extracts a substring from ‘string’ using ‘start’ position (zero-based). If ‘length’ is omitted then the remaining string length is used; otherwise ‘length’ is used. Returns a string.
Trim ([trim-char])	Trims all leading and trailing occurrences of spaces. If ‘trim-char’ is specified then that set of parameters are used for removal. Note: The character must be enclosed by single (and not double) quote marks. Returns a string.
TrimEnd([trim-char])	Trims all trailing occurrences of spaces. If ‘trim-char’ is specified then that set of parameters are used for removal. Note: The character must be enclosed by single (and not double) quote marks. Returns a string.
TrimStart([trim-char])	Trims all leading occurrences of spaces. If ‘trim-char’ is specified then that set of parameters are used for removal. Note: The character must be enclosed by single (and not double) quote marks. Returns a string.
XPathQueryFromFile(file.query)	Returns a list of XML nodes from the given file and query. File - the XML file's full path.  Query -The XPath query used to find the specific XML node.  Example: ${XPathQueryFromFile("\\Sys1\ShareFolder\testxml.xml", "/bookstore/book")[1].OuterXml}.
XPathQueryFromXML(XMLString.query)	Returns a list of XML nodes from the XML and query. XMLString - The XML string to search. Query - The XPath query used to find the specific XML node. Example: ${XPathQueryFromXML("${XMLVar}", "/root/nodes/node")[1].InnerXml}  Note: In this example the XMLString is stored in a constant variable named XMLVar.

 

Note: Functions are only supported on Microsoft Windows Execution Agents running V9 and above. You can expect this Operating System restriction to be removed in a future release.