Functions

Overview

Variables and functions can be used in free-text fields within tasks and workflows. When a variable or function is specified in a free-text field, the Controller inserts its value into the field when the task or workflow is run.

Also, triggers can pass variables and functions into the tasks and workflows they launch.

Universal Controller supports a number of functions that can be specified in free-text fields. They are resolved when a task instance runs or when a Set Variable action containing a function is executed.

Functions are entered using the following formats:
 

${_function}
${_function(arg1, ..., argN)}

Formatting Rules

  • Functions must be written either:
    • In all lower-case characters.
    • Exactly as shown in the tables on this page.
  • Functions have zero, one, or multiple parameters.
  • Each function parameter is one of three specific types:
    • String
    • Integer
    • Boolean
  • String parameters must be enclosed in single or double quotation marks.
  • Integer and Boolean parameters can be enclosed in single or double quotation marks.
  • Optional parameters are identified on this page by being enclosed in [square brackets]. When copying a function from the documentation, be sure to remove the square brackets; otherwise, the function will not resolve.
  • If a function has more than one optional parameter, any optional parameters preceding a specified optional parameter must be included in the function's parameter list. For example:
    • For function ${_responseJsonPath('pathExpression'[,'defaultValue','delimiter',prettyPrint])}, usage ${_responseJsonPath('.outputData','','',true)} would be valid, whereas ${_responseJsonPath('.outputData',,,true)}would not be valid.
    • For function ${_formatDate(['date_time', 'format', day_offset, use_business_days, hour_offset, minute_offset, timezone])}, usage ${_formatDate('2018-09-01','',0,true)} would be valid, whereas ${_formatDate('2018-09-01','',,true)}would not be valid.
  • All functions allow nesting to two levels. That is, a function can be an argument to another function, which itself can be an argument to another function.
    • You must use a double underscore preceding the name of a first-level nested function.
    • You must use a triple underscore preceding the name of a second-level nested function.

    For example, for 2nd day of next month less one Business Day:
${_formatDate('${__dayOfMonth(2,'${___dateadv('yyyy-MM-dd',0,1)}')}','',-1,true)}

Function Categories

Functions are listed alphabetically within the following categories on this page:

Conditional Functions

Return Conditional Value Depending on Equality of String Parameters

Description

Returns a conditional value depending on the equality of two string parameters.
 
(Returns if_value if string value1 is equal to string value2; otherwise, else_value is returned.)

Syntax

${_ifEqual('value1', 'value2', 'if_value', 'else_value'[, ignore_case])}

Parameters

  • value1
    Required; First string.
  • value2
    Required; Second string.
  • if_value
    Required; Return value if value1 equals value2.
  • else_value
    Required; Return value if value1 does not equal value2.
  • ignore_case
    Optional; Specification (true or false) whether or not to ignore case when comparing value1 and value2. Default is false.

Examples

Return Conditional Value Depending on Value of Boolean Parameter

Description

Returns a conditional value depending on the value of a boolean parameter.
 
Returns if_value if value is true; otherwise, else_value is returned.

Syntax

${_ifTrue(value, 'if_value', 'else_value')}

Parameters

  • value
    Required; Boolean value (true or false).
  • if_value
    Required; Return value if value is true.
  • else_value
    Required; Return value if value is false.

Example

Credential Functions

Return Key Location of a Credential

Description

Returns a token representing the Resolvable Credential Key Location that you want to embed.

Syntax

${_credentialKeyLoc('<credential_name>')}

Parameters

  • credential_name
    Required; Name of the Credential.
Example

${_credentialKeyLoc('RCredentialXYZ')} → $(ops_unv_cred_key_loc_c89e7b2caf4247909bc46041df8a2643)

Return Passphrase of a Credential

Description

Returns a token representing the Resolvable Credential Passphrase that you want to embed.

Syntax

${_credentialPassphrase('<credential_name>')}

Parameters

  • credential_name
    Required; Name of the Credential.
Example
${_credentialPassphrase('RCredentialXYZ')} → $(ops_unv_cred_passphrase_c89e7b2caf4247909bc46041df8a2643)

Return Token of a Credential

Description

Returns a token representing the Resolvable Credential Token that you want to embed.

Syntax

${_credentialToken('<credential_name>')}

Parameters

  • credential_name
    Required; Name of the Credential.
Example
${_credentialToken('RCredentialXYZ')} → $(ops_unv_cred_token_c89e7b2caf4247909bc46041df8a264


Return User Name of a Credential

Description

Returns a token representing the Resolvable Credential Runtime User that you want to embed.

Syntax

${_credentialUser('<credential_name>')}

Parameters

  • credential_name
    Required; Name of the Credential.
Example

${_credentialUser('RCredentialXYZ')} → $(ops_unv_cred_user_c89e7b2caf4247909bc46041df8a2643)

Return User Password of a Credential

Description

Returns a token representing the Resolvable Credential Runtime Password that you want to embed.

Syntax

${_credentialPwd('<credential_name>')}

Parameters

  • credential_name
    Required; Name of the Credential.
Example

${_credentialPwd('RCredentialXYZ')} → $(ops_unv_cred_pwd_c89e7b2caf4247909bc46041df8a2643)

Date Functions

Checks if Date Argument Equals Today's Date

Description

Checks if a date argument is equal to today's date in the specified format.
 
Returns true if date is equal to today's date in the specified format; otherwise, false is returned.

Syntax

${_isToday('date'[, 'format', is_relative])}

Parameters

  • date
    Required; Date to compare to today's date.
  • format
    Optional; Format of today's date. Default is yyyy-MM-dd.
  • is_relative
    Optional; Specification (true or false) for whether today's date is relative to the trigger/launch time of the task instance. Default is false.

Examples

Resolve to Current Date and Time

Description

Resolves to the current date and time.

Syntax

${_date(['format', day_offset, hour_offset, minute_offset])}

Parameters

Examples

Resolve to Current Date and Time (Advanced)

Description

Resolves to the current date and time.

Syntax

${_dateadv(['format', year_offset, month_offset, day_offset, hour_offset, minute_offset])}

Parameters

  • format
    Date format. Default format is yyyy-MM-dd HH:mm:ss Z. For details on the format parameter, see https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html
  • year_offset
    Optional; +/- number of years to offset.
  • month_offset
    Optional; +/- number of months to offset.
  • day_offset
    Optional; +/- number of days to offset.
  • hour_offset
    Optional; +/- number of hours to offset.
  • minute_offset
    Optional; +/- number of minutes to offset.

Examples

Resolve to Current Unix Epoch Time

Description

Resolves to the current time in milliseconds since Wed Dec 31 1969 19:00:00 GMT-0500 (EST) – the start of Unix epoch time.

Syntax

${_currentTimeMillis}

Parameters

n/a

Return Date with Offsets

Description

Returns the date after applying offsets. Optionally, can specify the output format.
 

Whether a holiday is treated as a business day or a non-business day is specified by the Exclude Holidays for Business Days Universal Controller system property.

Syntax

${_formatDate(['date_time', 'format', day_offset, use_business_days, hour_offset, minute_offset, timezone])}

Parameters

  • date_time
    Date and time in any of the following formats:
    • yyyy-MM-dd
    • yyyy-MM-dd HH:mm
    • yyyy-MM-dd HH:mm:ss
    • yyyy-MM-dd HH:mm Z
    • yyyy-MM-dd HH:mm:ss Z.
    • yyyy-MM-dd HH:mm:ss.SSS
    • yyyy-MM-dd HH:mm:ss.SSS Z.
    Default is the current date and time.
  • format
    Format of returned date. If date_time specifies a time, the default format is yyyy-MM-dd HH:mm; otherwise, the default format is yyyy-MM-dd. For details on the format parameter, see https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html
  • day_offset
    +/- number of days to offset.
  • use_business_days
    Specification (true or false) for whether day_offset is for business days. Default is false.
  • hour_offset
    +/- number of hours to offset.
  • minute_offset
    +/- number of minutes to offset.
  • timezone
    Time Zone that the date is formatted in.

Example

Return Date with Offsets (Advanced)

Description

Returns the date after applying offsets. Optionally, can specify the output format.
 

Whether a holiday is treated as a business day or a non-business day is specified by the Exclude Holidays for Business Days Universal Controller system property.

Syntax

${_formatDateAdv(['date_time', 'format', year_offset, month_offset, day_offset, use_business_days, hour_offset, minute_offset, timezone])}

Parameters

  • date_time
    Date and time in any of the following formats:
    • yyyy-MM-dd
    • yyyy-MM-dd HH:mm
    • yyyy-MM-dd HH:mm:ss
    • yyyy-MM-dd HH:mm Z
    • yyyy-MM-dd HH:mm:ss Z.
    • yyyy-MM-dd HH:mm:ss.SSS
    • yyyy-MM-dd HH:mm:ss.SSS Z.
    Default is the current date and time.
  • format
    Format of returned date. If date_time specifies a time, the default format is yyyy-MM-dd HH:mm; otherwise, the default format is yyyy-MM-dd. For details on the format parameter, see https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html
  • year_offset
    Optional; +/- number of years to offset.
  • month_offset
    Optional; +/- number of months to offset.
  • day_offset
    Optional; +/- number of days to offset.
  • use_business_days
    Optional; Specification (true or false) for whether day_offset is for business days. Default is false.
  • hour_offset
    +/- number of hours to offset.
  • minute_offset
    +/- number of minutes to offset.
  • timezone
    Time Zone that the date is formatted in.

Examples

Return Date with Time Zone

DescriptionReturns the Date and Time in another time zone.

Syntax

${_formatDateTz('date_time', 'target_time_zone'[, 'output_format'])}

Parameters

  • date_time
    Date and time in any of the following formats:
    • yyyy-MM-dd HH:mm
    • yyyy-MM-dd HH:mm:ss
    • yyyy-MM-dd HH:mm Z
    • yyyy-MM-dd HH:mm:ss Z.
    • yyyy-MM-dd HH:mm:ss.SSS
    • yyyy-MM-dd HH:mm:ss.SSS Z.
  • target_time_zone
    Time zone in which to format the date and time.
  • output_format
    Optional; Format of the date and time in the other time zone.

Examples

Return Day of Week

Description

Returns the day of week for the specified date as a number.

Syntax

${_dayOfWeek(['date', 'first_dow', first_dow_value])}

Parameters

  • date
    Date in any of the following formats:
    • yyyy-MM-dd
    • yyyy-MM-dd HH:mm
    • yyyy-MM-dd HH:mm:ss
    • yyyy-MM-dd HH:mm Z
    • yyyy-MM-dd HH:mm:ss Z.
    • yyyy-MM-dd HH:mm:ss.SSS
    • yyyy-MM-dd HH:mm:ss.SSS Z.
    Default is the current date.
  • first_dow
    Optional; Specification for whether the week starts on Sunday or Monday. Values are sun and mon (not case-sensitive). Default is sun.
  • first_dow_value
    Optional; Starting value for the first day of week. Value must be a non-negative number. Default is 1.

Example

Return Days between Dates

Description

Returns the number of days between date1 and date2.

  • If return value is > 0, date2 is after date1.
  • If return value is < 0, date2 is before date1.
  • If return value is 0, date1 is equal to date2.

The start date is inclusive, but the end date is not.

Syntax

${_daysBetween('date1', 'date2')}

Parameters

  • date1
    Required.
  • date2
    Required.

date1 and date2 are specified in any of the following formats:

  • yyyy-MM-dd
  • yyyy-MM-dd HH:mm
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd HH:mm Z
  • yyyy-MM-dd HH:mm:ss Z.
  • yyyy-MM-dd HH:mm:ss.SSS
  • yyyy-MM-dd HH:mm:ss.SSS Z.

Example

Return Non-Business Day of Month

Description

Returns the Nth non-business day of month for the month of the date specified. Optionally, can start from the end of the month.
 

Whether a holiday is treated as a business day or a non-business day is specified by the Exclude Holidays for Business Days Universal Controller system property.

Syntax

${_nonBusinessDayOfMonth(index, ['date', 'format', reverse])}

Parameters

  • index
    Required; Nth non-business day of month.
  • date
      Date (and time) is specified in any of the following formats:
      • yyyy-MM-dd
      • yyyy-MM-dd HH:mm
      • yyyy-MM-dd HH:mm:ss
      • yyyy-MM-dd HH:mm Z
      • yyyy-MM-dd HH:mm:ss Z.
      • yyyy-MM-dd HH:mm:ss.SSS
      • yyyy-MM-dd HH:mm:ss.SSS Z.
      Default is the current date.
    • format
      Optional; Format of returned date. Default is yyyy-MM-dd. For details on the format parameter, see https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html
    • reverse
      Optional; Specification (true or false) for starting from the end of the month. Default is false.

Examples

Return Nth Business Day of Month

Description

Returns the Nth business day of month for the month of the date specified. Optionally, can start from the end of the month.
 

Whether a holiday is treated as a business day or a non-business day is specified by the Exclude Holidays for Business Days Universal Controller system property.

Syntax

${_businessDayOfMonth(index, ['date', 'format', reverse])}

Parameters

  • index
    Required; Nth business day of month.
  • date
    Date (and time) is specified in any of the following formats:
    • yyyy-MM-dd
    • yyyy-MM-dd HH:mm
    • yyyy-MM-dd HH:mm:ss
    • yyyy-MM-dd HH:mm Z
    • yyyy-MM-dd HH:mm:ss Z.
    • yyyy-MM-dd HH:mm:ss.SSS
    • yyyy-MM-dd HH:mm:ss.SSS Z.
    Default is the current date.
  • format
    Optional; Format of returned date. Default is yyyy-MM-dd. For details on the format parameter, see https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html
  • reverse
    Optional; Specification (true or false) for starting from the end of the month. Default is false.

Examples

Return Nth Day of Month

Description

Returns the Nth day of month for the month of the date specified. Optionally, can start from the end of the month.

Syntax

${_dayOfMonth(index, ['date', 'format', reverse])}

Parameters

  • index
    Required; Nth day of month.
  • date
    Date (and time) is specified in any of the following formats:
    • yyyy-MM-dd
    • yyyy-MM-dd HH:mm
    • yyyy-MM-dd HH:mm:ss
    • yyyy-MM-dd HH:mm Z
    • yyyy-MM-dd HH:mm:ss Z.
    • yyyy-MM-dd HH:mm:ss.SSS
    • yyyy-MM-dd HH:mm:ss.SSS Z.
    Default is the current date.
  • format
    Optional; Format of returned date. Default is yyyy-MM-dd.
  • reverse
    Optional; Specification (true or false) for starting from the end of the month. Default is false.

Examples

Return Number of Business Days between Dates

Description

Returns the number of business days between date1 and date2.

  • If return value is > 0, date2 is after date1.
  • If return value is < 0, date2 is before date1.
  • If return value is 0, date1 is equal to date2.

The start date is inclusive, but the end date is not.
 

Whether a holiday is treated as a business day or a non-business day is specified by the Exclude Holidays for Business Days Universal Controller system property.

Syntax

${_businessDaysBetween('date1', 'date2')}

Parameters

  • date1
    Required.
  • date2
    Required.

date1 and date2 are specified in any of the following formats:

  • yyyy-MM-dd
  • yyyy-MM-dd HH:mm
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd HH:mm Z
  • yyyy-MM-dd HH:mm:ss Z.
  • yyyy-MM-dd HH:mm:ss.SSS
  • yyyy-MM-dd HH:mm:ss.SSS Z.

Example

Mathematical Functions

Add

Description

Return the sum of the augend added with the addend.

Syntax

${_add(augend, addend)}

Parameters

  • augend
    Integer to which the addend is being added.
  • addend
    Integer being added to the augend.

Example

 
Using Variables for augend and addend (${augend} = 17, ${addend} = 5):
 

Divide

Description

Return the quotient of the dividend divided by divisor.

Syntax

${_divide(dividend, divisor)}

Parameters

  • dividend
    Integer being divided by the divisor.
  • divisor
    Integer being used to divide the dividend.

Example

 
Using Variables for dividend and divisor (${dividend} = 100, ${divisor} = 5)
 

Multiply

Description

Return the product of the multiplicand multiplied with the multiplier.

Syntax

${_multiply(multiplicand, multiplier)}

Parameters

  • multiplicand
    Integer being multiplied by the multiplier.
  • multiplier
    Integer being used to multiply the multiplicand.

Example

 
Using Variables for multiplicand and multiplier (${multiplicand} = 100, ${multiplier} = 5):
 

Return Absolute Value

Description

Return the absolute value of the parameter.

Syntax

{_abs(parameter)}

Parameters

  • parameter
    Integer (positive or negative value).

Example

 
Using Variables for parameter (${parameter} = -100):
 

Return Modulo

Description

Return the modulo (remainder) of the dividend divided by divisor.

Syntax

${_mod(dividend, divisor)}

Parameters

  • dividend
    Integer being divided by the divisor.
  • divisor
    Integer being used to divide the dividend.

Example

 
Using Variables for dividend and divisor (${dividend} = 23, ${divisor} = 5):
 

Subtract

Description

Return the difference of the subtrahend subtracted from the minuend.

Syntax

${_subtract(minuend, subtrahend)}

Parameters

  • minuend
    Integer from which the subtrahend is being subtracted.
  • subtrahend
    Integer being subtracted from the minuend.

Example

 
Using Variables for minuend and subtrahend (${minuend} = 100, ${subtrahend} = 5):
 

Other Task Functions

Business Services Membership

Description

Resolves to a delimited list of business service names the task instance is a member of.

Syntax

${_businessServices(['resultDelimiter'])}

Parameters

  • resultDelimiter
    Optional; Delimiter to use when concatenating business service names. If not specified, ", " will be used.
Example

If a task instance is a member of business services A, B, and C.

${_businessServices()}
A, B, C

${_businessServices('\n')}
A
B
C

If a task instance is not a member of any business service, the function will evaluate to empty.

Output Functions

(For Web Service output, see Functions#Web Service Functions.)
 

Note

A prerequisite for the use of these functions is that Automatic Output Retrieval and Wait For Output are selected at task level, with the exception of the EXTENSION output type.

Task Instance Output

Description

Resolves to the output data, of the specified outputType, of the task instance that is resolving the function.

  • If the output record of the specified ouptutType cannot be found, the function will remain unresolved.

Syntax

${_output('outputType'[, 'defaultValue'])}

Parameters

  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • defaultValue
    Optional; Default value to return if the output data is not found. Default is empty ('').

Sibling Task Instance Output

Description

Resolves to the output data, of the specified outputType, of the task instance specified by the siblingName parameter.
 
The sibling task instance must be within the same workflow, and the Execution User of the task instance that is resolving the function must have Read permission for the sibling task instance.

  • If the output record of the specified outputType cannot be found, the function will remain unresolved.

Syntax

${_outputFromTask('siblingName', 'outputType'[, 'defaultValue'])}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • defaultValue
    Optional; Default value to return if the output data is not found. Default is empty ('').

Task Instance Output Number of Lines

Description

Resolves to the number of lines of output data, of the specified outputType, of the task instance that is resolving the function.

  • If the output record of the specified ouptutType cannot be found, the function will remain unresolved.

Syntax

${_outputNumberOfLines('outputType')}

Parameters

  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
Example

${_outputNumberOfLines('STDOUT')}
> 6

Sibling Task Instance Output Number of Lines

Description

Resolves to the number of lines of output data, of the specified outputType, of the task instance specified by the siblingName parameter.

  • The sibling task instance must be within the same workflow, and the Execution User of the task instance that is resolving the function must have Read permission for the sibling task instance.
  • If the output record of the specified outputType cannot be found, the function will remain unresolved.

Syntax

${_outputNumberOfLinesFromTask('siblingName', 'outputType')}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
Example

${_outputNumberOfLinesFromTask('test', 'STDOUT')}
> 8

Task Instance Output by Specific Line(s)

Description

Resolves to the specified line(s) of output data, of the specified outputType, of the task instance that is resolving the function.

  • If the output record of the specified ouptutType cannot be found, the function will remain unresolved.

Syntax

${_outputLines('outputType', startLine, numberOfLines[, 'defaultValue', 'resultDelimiter'])}

Parameters

  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • startLine
    Required; Start line, where 1 is the first line and -1 is the last line.
  • numberOfLines
    Required; Number of lines to return starting from the startLine.
  • defaultValue
    Optional; Default value to return if no lines qualify. Default is empty ('')
  • resultDelimiter
    Optional; Delimiter to use when concatenating matching lines. If not specified, "\n" or "\r\n" depending on original output line endings.

Sibling Task Instance Output by Specific Line(s)

Description

Resolves to the specified line(s) of output data, of the specified outputType, of the task instance specified by the siblingName parameter.
 
The sibling task instance must be within the same workflow, and the Execution User of the task instance that is resolving the function must have Read permission for the sibling task instance.

  • If the output record of the specified outputType cannot be found, the function will remain unresolved.

Syntax

${_outputLinesFromTask('siblingName', 'outputType', startLine, numberOfLines[, 'defaultValue', 'resultDelimiter'])}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • startLine
    Required; Start line, where 1 is the first line and -1 is the last line.
  • numberOfLines
    Required; Number of lines to return starting from the startLine.
  • defaultValue
    Optional; Default value to return if no lines qualify. Default is empty ('').
  • resultDelimiter
    Optional; Delimiter to use when concatenating matching lines. If not specified, "\n" or "\r\n" depending on original output line endings.

Task Instance Output by Line(s) Matching Regular Expression

Description

Resolves to the line(s) of output data that match the specified regular expression, of the specified outputType, of the task instance that is resolving the function by specifying a regular expression.

  • The complete output line is returned.
  • If the output record of the specified ouptutType cannot be found, the function will remain unresolved.

Syntax

${_outputLinesByRegex('outputType', 'regexPattern'[, maxCount, numberOfLinesBefore, numberOfLinesAfter, 'defaultValue', 'resultDelimiter'])}

Parameters

  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • regexPattern
    Required; Regular expression used for determining if a line matches. Regular expression must match the whole line (see Example, below).
  • maxCount
    Optional; Maximum number of matching lines to return. Default is 1.
  • numberOfLinesBefore
    Optional; Number of lines before each matching line to return along with the matching line. Default is 0.
  • numberOfLinesAfter
    Optional; Number of lines after each matching line to return along with the matching line. Default is 0.
  • defaultValue
    Optional; Default value to return if no lines match the regular expression. Default is empty ('').
  • resultDelimiter
    Optional; Delimiter to use when concatenating matching lines. If not specified, "\n" or "\r\n" depending on original output line endings.

Example

STDOUT contains:
Some_Text
ABC=Some_String
More_Text
 
${_outputLinesByRegex('STDOUT', '^ABC=')} Returns empty (the whole Line was not matched)
${_outputLinesByRegex('STDOUT', '^ABC=.*')} Returns ABC=Some_String

Sibling Task Instance Output by Line(s) Matching Regular Expression

Description

Resolves to the line(s) of output data that match the specified regular expression, of the specified outputType, of the task instance specified by the siblingName parameter.
 
The sibling task instance must be within the same workflow, and the Execution User of the task instance that is resolving the function must have Read permission for the sibling task instance.

  • If the output record of the specified outputType cannot be found, the function will remain unresolved.

Syntax

${_outputLinesByRegexFromTask('siblingName', 'outputType', 'regexPattern'[, maxCount, numberOfLinesBefore, numberOfLinesAfter, 'defaultValue', 'resultDelimiter'])}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • regexPattern
    Required; Regular expression used for determining if a line matches.
  • maxCount
    Optional; Maximum number of matching lines to return. Default is 1.
  • numberOfLinesBefore
    Optional; Number of lines before each matching line to return along with the matching line. Default is 0.
  • numberOfLinesAfter
    Optional; Number of lines after each matching line to return along with the matching line. Default is 0.
  • defaultValue
    Optional; Default value to return if no lines match the regular expression. Default is empty ('').
  • resultDelimiter
    Optional; Delimiter to use when concatenating matching lines. If not specified, "\n" or "\r\n" depending on original output line endings.

Task Instance Output By XPath

Description

Resolves to the XML output data of the task instance that is resolving the function, corresponding to the evaluated XPath expression.

  • If the output record cannot be found, the function will remain unresolved.

  • If the output record is found, but the path expression does not yield a result, the function will resolve to the default value.

Syntax

${_outputXPath('outputType', 'xPathExpression'[, 'defaultValue', 'delimiter', prettyPrint])}

Parameters

  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • xPathExpression
    Required; XPath expression. https://www.w3schools.com/xml/xpath_intro.asp
  • defaultValue
    Optional; Default value to return if the result is not found. Default is empty ('').
  • delimiter
    Optional; If xPathExpression evaluates to multiple results, the delimiter to be used to separate those results. Default is new line character (\n).
  • prettyPrint
    Optional; Specification (true or false) for whether or not XML output will be pretty printed (indented). Default is false.

Example

XML

<message>
  <code>10</code>
</message>

Function

${_outputXPath('STDOUT', '//code/text()')}

Result

10

Sibling Task Instance Output By XPath

Description

Resolves to the XML output data of the task instance specified by the siblingName, corresponding to the evaluated XPath expression.

The sibling task instance must be within the same workflow and the Execution User of the task instance that is resolving the function must have Read permission for the sibling task instance.

  • If the output record cannot be found, the function will remain unresolved.

  • If the output record is found but the path expression does not yield a result, the function will resolve to the default value.

Syntax

${_outputXPathFromTask('siblingName', 'outputType', 'xPathExpression'[, 'defaultValue', 'delimiter', prettyPrint])}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • xPathExpression
    Required; XPath expression. https://www.w3schools.com/xml/xpath_intro.asp
  • defaultValue
    Optional; Default value to return if the result is not found. Default is empty ('').
  • delimiter
    Optional; If xPathExpression evaluates to multiple results, the delimiter to be used to separate those results. Default is new line character (\n).
  • prettyPrint
    Optional; Specification (true or false) for whether or not XML output will be pretty printed (indented). Default is false.

Example

XML
<message>
  <code>10</code>
</message>

Function
${_outputXPathFromTask('Sibling_With_XML_Output', 'STDOUT', '//code/text()')}

Result
10

Task Instance Output By JsonPath

Description

Resolves to the JSON output data of the task instance that is resolving the function, corresponding to the evaluated JsonPath expression.

  • If the output record cannot be found, the function will remain unresolved.

  • If the output record is found but the path expression does not yield a result, the function will resolve to the default value.

Syntax

${_outputJsonPath('outputType', 'pathExpression'[, 'defaultValue', 'delimiter', prettyPrint])}

Parameters

  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • PathExpression
    Required; JsonPath expression. https://github.com/json-path/Jsonpath
  • defaultValue
    Optional; Default value to return if the result is not found. Default is empty ('').
  • delimiter
    Optional; If pathExpression evaluates to multiple results, the delimiter to be used to separate those results. Default is new line character (\n).
  • prettyPrint
    Optional; Specification (true or false) for whether or not JSON output will be pretty printed (indented). Default is false.

Example

JSON

{
  "code": 10
}


Function

${_outputJsonPath('STDOUT', '$.code')}


Result

10

Sibling Task Instance Output By JsonPath

Description

Resolves to the JSON output data of the task instance specified by the siblingName, corresponding to the evaluated JsonPath expression.

The sibling task instance must be within the same workflow and the Execution User of the task instance that is resolving the function must have Read permission for the sibling task instance.

  • If the output record cannot be found, the function will remain unresolved.

  • If the output record is found but the path expression does not yield a result, the function will resolve to the default value

Syntax

${_outputJsonPathFromTask('siblingName', 'outputType', 'pathExpression'[, 'defaultValue', 'delimiter', prettyPrint])}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • PathExpression
    Required; JsonPath expression. https://github.com/json-path/Jsonpath
  • defaultValue
    Optional; Default value to return if the result is not found. Default is empty ('').
  • delimiter
    Optional; If pathExpression evaluates to multiple results, the delimiter to be used to separate those results. Default is new line character (\n).
  • prettyPrint
    Optional; Specification (true or false) for whether or not JSON output will be pretty printed (indented). Default is false.

Example

JSON

{
  "code": 10
}

Function

${_outputJsonPathFromTask('Sibling_With_JSON_Output', 'STDOUT', '$.code')}

Result

10

Task Instance Output By JsonPath As Array

Description

Resolves to the JSON output data of the task instance that is resolving the function, corresponding to the evaluated JsonPath expression.

  • If the output record cannot be found, the function will remain unresolved.

  • If the output record is found but the path expression does not yield a result, the function will resolve to the default value.

Syntax

${_outputJsonPathAsArray('outputType', 'pathExpression'[, 'defaultValue', prettyPrint])}

Parameters

  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • PathExpression
    Required; JsonPath expression. https://github.com/json-path/Jsonpath
  • defaultValue
    Optional; Default value to return if the result is not found. Default is empty ('').
  • prettyPrint
    Optional; Specification (true or false) for whether or not JSON output will be pretty printed (indented). Default is false.

Example

JSON

[
  
{
    "message" : "Hello",
    "code" : 10
  },
  {
    "message" : "World!",
    "code" : 20
  }
]


Function

${_outputJsonPathAsArray('STDOUT', '$[*].message', '', true)}

Result

[
    "Hello",
    "World!"
]

Sibling Task Instance Output By JsonPath As Array

Description

Resolves to the JSON output data of the task instance specified by the siblingName, corresponding to the evaluated JsonPath expression.

The sibling task instance must be within the same workflow and the Execution User of the task instance that is resolving the function must have Read permission for the sibling task instance.

  • If the output record cannot be found, the function will remain unresolved.

  • If the output record is found but the path expression does not yield a result, the function will resolve to the default value.

Syntax

${_outputJsonPathFromTask('siblingName', 'outputType', 'pathExpression'[, 'defaultValue', prettyPrint])}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to resolve: STDOUT, STDERR, FILE, EXTENSION, or JOBLOG.
  • PathExpression
    Required; JsonPath expression. https://github.com/json-path/Jsonpath
  • defaultValue
    Optional; Default value to return if the result is not found. Default is empty ('').
  • prettyPrint
    Optional; Specification (true or false) for whether or not JSON output will be pretty printed (indented). Default is false.

Example

JSON
[
  {
    "message" : "Hello",
    "code" : 10
  },
  {
    "message" : "World!",
    "code" : 20
  }
]

Function
${_outputJsonPathAsArrayFromTask('Sibling_With_JSON_Output', 'STDOUT', '$[*].message')}

Result
["Hello","World!"]

Task Instance Output Path

Description

Returns a token representing the path to a temporary file containing the specified task instance output data.

Syntax

${_outputPath('outputType'[, 'fileExtension'])}

Parameters

  • outputType
    Required; Type of output to create a temporary file for: STDOUT, STDERR, FILE, EXTENSION, JOBLOG, WEBSERVICE, SQL, STOREDPROC.
  • fileExtension
    Optional; The extension to use for the temporary file. Can be a maximum of 10 characters.
    • For SQL and STOREDPROC outputType, the result set is translated to comma-separated values (csv), or tab-separated values (tsv), and, therefore, only csv (default) and tsv are supported file extensions.
    • For any other outputType, the default file extension is txt.

Example

application.exe -file ${_outputPath('STDOUT')}
> application.exe -file $(ops_output_path_1638302212442528629FTPBE4AJQV2FT_stdout_txt)
application.exe -file ${_outputPath('SQL')}
> application.exe -file $(ops_output_path_1639503212294078671DNPMULGSEVMHT_sql_csv)
application.exe -file ${_outputPath('SQL', 'tsv')}
> application.exe -file $(ops_output_path_1639503212294078671DNPMULGSEVMHT_sql_tsv)
application.exe -file ${_outputPath('EXTENSION', 'json')}
> application.exe -file $(ops_output_path_1639503212294187671OAI9SM79CNC2V_extension_json)


Sibling Task Instance Output Path

Description

Returns a token representing the path to a temporary file containing the specified sibling task instance output data.

Syntax

${_outputPathFromTask('siblingName', 'outputType'[, 'fileExtension'])}

Parameters

  • siblingName
    Required; Name of a sibling task instance.
  • outputType
    Required; Type of output to create a temporary file for: STDOUT, STDERR, FILE, EXTENSION, JOBLOG, WEBSERVICE, SQL, STOREDPROC.
  • fileExtension
    Optional; The extension to use for the temporary file. Can be a maximum of 10 characters.
    • For SQL and STOREDPROC outputType, the result set is translated to comma-separated values (csv), or tab-separated values (tsv), and, therefore, only csv (default) and tsv are supported file extensions.
    • For any other outputType, the default file extension is txt.

Example

application.exe -file ${_outputPathFromTask('Sibling_Instance_Name', 'STDERR')}
> application.exe -file $(ops_output_path_1639503212294128671YL1B04U3OT55P_stderr_txt)
application.exe -file ${_outputPathFromTask('Sibling_Instance_Name', 'STOREDPROC')}
> application.exe -file $(ops_output_path_1639503212294197671Q13UV8MSH6355_storedproc_csv)
application.exe -file ${_outputPathFromTask('Sibling_Instance_Name', 'STOREDPROC', 'tsv')}
> application.exe -file $(ops_output_path_1639503212294197671Q13UV8MSH6355_storedproc_tsv)
application.exe -file ${_outputPathFromTask('Sibling_Instance_Name', 'WEBSERVICE', 'json')}
> application.exe -file $(ops_output_path_1639503212294088671CAWMP3VNQ468B_webservice_json)



Script Functions

Returns Path to Data Script

Description

Returns a token representing the path to a Data Script that you want to embed.

Syntax

${_scriptPath('script_name')}

Parameters

  • script_name
    Required; Name of the Data Script.

Example

Script Name: MyDataScript

Script UUID: 507ffdbd0eba4b62b0e31e0fd22f6bec

${_scriptPath('MyDataScript')} --> $(ops_unv_script_path_507ffdbd0eba4b62b0e31e0fd22f6bec)

Note

The Agent will replace the resolved token with a path to a temporary file containing the content of the Data Script.

For additional details, refer to Embedding a Data Script.

Note

_scriptPath requires Agent 6.4.0.0 or later.

SQL/Stored Procedure Functions

Return Column Names for SQL Results from Current Task

Description

Returns the column names for the SQL results from the current SQL or Stored Procedure task. Column names are separated by the specified separator.

Syntax

${_resultsColumnNames(['separator'])}

Parameters

  • separator
    Optional; Column name separator. Default is comma (,).

Return Column Names for SQL Results from Sibling Task

Description

Returns the column names for the SQL results from a sibling SQL or Stored Procedure task, within the same workflow. Column names are separated by the specified separator.

Syntax

${_resultsColumnNamesFromTask('name'[, 'separator'])}

Parameters

  • name
    Required; Name of the sibling task that the results should come from. The task must be within the same workflow.
  • separator
    Optional; Column name separator. Default is comma (,).

Return SQL Results from Current Task

Description

Returns all SQL results from the current SQL or Stored Procedure task. Columns are separated by the specified separator and rows are separated by a new line.

Syntax

${_resultsAll(['separator', 'rowSeparator'])}

Parameters

  • separator
    Optional; Column separator. Default is comma (,).
  • rowSeparator
    Optional; Overrides default New Line character.

Return SQL Results from Sibling Task

Description

Returns all SQL results from a sibling SQL or Stored Procedure task, within the same workflow. Columns are separated by the specified separator and rows are separated by a new line.

Syntax

${_resultsAllFromTask('name'[, 'separator', 'rowSeparator'])}

Parameters

  • name
    Required; Name of the task that the results should come from. The task must be within the same workflow.
  • separator
    Optional; Column separator. Default is comma (,).
  • rowSeparator
    Optional; Overrides default New Line character.

Return SQL Warnings from Current Task

Description

Returns all SQL warnings from the current SQL or Stored Procedure task. Columns are separated by the specified separator and rows are separated by a new line.

Syntax

${_SQLWarnings(['separator'])}

Parameters

  • separator
    Optional; Column separator. Default is comma (,).

Return SQL Warnings from Sibling Task

Description

Returns all SQL warnings from a sibling SQL or Stored Procedure task, within the same workflow. Columns are separated by the specified separator and rows are separated by a new line.

Syntax

${_SQLWarningsFromTask('name'[, 'separator'])}

Parameters

  • name
    Required; Name of the sibling task that the warnings should come from. The task must be within the same workflow.
  • separator
    Optional; Column separator. Default is comma (,).

Return String Value of Row/Column by Column Name

Description

Returns the string value of a row/column from a previously executed SQL task within the same workflow, or from the current SQL task.

Syntax

${_resultsColumn('name', 'colname'[, rownum, 'default_value'])}

Parameters

  • name
    Required; Name of a sibling SQL task within the same workflow from which you want the function to fetch results. If you want to execute the function against the current task, use an empty string for the name parameter.
  • colname
    Required; Name of column to retrieve.
  • rownum
    Optional; Numeric row number in result set to retrieve. Default is 1.
  • default_value
    Optional; Default value to return if result not found.

Return String Value of Row/Column by Column Number

Description

Returns the string value of a row/column from a previously executed SQL task within the same workflow, or from the current SQL task.

Syntax

${_resultsColumnByNo('name', colnum[, rownum, 'default_value'])}

Parameters

  • name
    Required; Name of a sibling SQL task within the same workflow from which you want the function to fetch results. If you want to execute the function against the current task, use an empty string for the name parameter.
  • colnum
    Required; Number of column to retrieve. First column in result is 1, second is 2, and so on.
  • rownum
    Optional; Numeric row number in result set to retrieve. Default is 1.
  • default_value
    Optional; Default value to return if result not found.

Return String Values of Columns

Description

Returns the string values of columns in a specific row in CSV (comma-separated values) format, from a previously executed SQL task within the same workflow, or from the current SQL task.

Syntax

${_resultsColumnsCSV('name'[, rownum])}

Parameters

  • name
    Required; Name of a sibling SQL task within the same workflow from which you want the function to fetch results. If you want to execute the function against the current task, use an empty string for the name parameter.
  • rownum
    Optional; Numeric row number in result set to retrieve. Default is 1.

String Functions

String Functions can accept:

  • String content in a String parameter.
  • Variable name in a String parameter (prefixed with _var) from which string content can be obtained.
  • Integer and Boolean parameters.

For String functions that accept a String value parameter directly, the value parameter can be specified using hard-coded text, variables, functions, or any combination of the three.
 

Note

When using String functions that accept a String value parameter directly, you should be aware of expectations with respect to escape characters and escape sequences (see Functions#Escape Sequences, below).


For String functions that accept a variable name parameter, the fully resolved value of the variable by the specified name will be used as the String value argument. The variable must be fully resolvable and must not contain an unresolved function.


Note

Indexing functions use zero-based numbering; that is, the initial element is assigned the index 0.

Escape Sequences

An escape character preceded by a backslash (\) is an escape sequence (see the following table for a list of escape sequences).

If you are using a String function to manipulate a String value that potentially may contain an escape sequence, you should use the String function that accepts a variable name parameter to allow for passing the value to the function without the escape sequence being interpreted.
 

Escape Sequences

Escape Sequence Description

\t

Insert a tab in the text at this point.

\b

Insert a backspace in the text at this point.

\n

Insert a newline in the text at this point.

\r

Insert a carriage return in the text at this point.

\f

Insert a formfeed in the text at this point.

\'

Insert a single quote character in the text at this point.

\"

Insert a double quote character in the text at this point.

\\

Insert a backslash character in the text at this point.

Convert Characters in Value to Lower Case

Description

Converts all of the characters in the value to lower case using the rules of the default locale.

Syntax

${_toLowerCase('value')}

Parameters

  • value
    Required; String to convert to lower case.

Convert Characters in Variable to Lower Case

Description

Converts all of the characters in the variable to lower case using the rules of the default locale.

Syntax

${_varToLowerCase('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.

Convert Characters in Value to Upper Case

Description

Converts all of the characters in the value to upper case using the rules of the default locale.

Syntax

${_toUpperCase('value')}

Parameters

  • value
    Required; String to convert to upper case.

Convert Characters in Variable to Upper Case

Description

Converts all of the characters in the variable to upper case using the rules of the default locale.

Syntax

${_varToUpperCase('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.

Escape Characters in Variable Using XML Entities

Description

Escapes the characters in a variable value using XML entities.

Syntax

${_varEscapeXml('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function. The variable value will be escaped for insertion into XML.

Example

Variable Name:
escape_me
 
Variable Value:
`1234567890\E-=[]\;',./ ~!@#$%^&*()_+{}|:"<>?
 

${_varEscapeXml('escape_me')} --> `1234567890\E-=[]\;&apos;,./ ~!@#$%^&amp;*()_+{}|:&quot;&lt;&gt;?

Escape Characters in Variable Using JSON String Rules

Description

Escapes the characters in a variable value using JSON string values.

Syntax

${_varEscapeJson('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function. The variable value will be escaped for insertion into JSON.

Example

Variable Name:
escape_me
 
Variable Value:
`1234567890\E-=[]\;',./ ~!@#$%^&*()_+{}|:"<>?
 

${_varEscapeJson('escape_me')} --> `1234567890\\E-=[]\\;',.\/ ~!@#$%^&*()_+{}|:\"<>?

Escape Characters in Variable Using JavaScript String Rules

Description

Escapes the characters in a variable value using JavaScript String rules.

Syntax

${_varEscapeJavaScript('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function. The variable value will be escaped for insertion into JavaScript.

Example

Variable Name:
escape_me
 
Variable Value:
`1234567890\E-=[]\;',./ ~!@#$%^&*()_+{}|:"<>?
 

${_varEscapeJavaScript('escape_me')} --> `1234567890\\E-=[]\\;\',.\/ ~!@#$%^&*()_+{}|:\"<>?

Escape Characters in Variable Using HTML Entities

Description

Escapes the characters in a variable value using HTML entities. (Supports all known HTML 4.0 entities.)

Syntax

${_varEscapeHtml('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function. The variable value will be escaped for insertion into HTML.

Example

Variable Name:
escape_me
 
Variable Value:
`1234567890\E-=[]\;',./ ~!@#$%^&*()_+{}|:"<>?
 

${_varEscapeHtml('escape_me')} --> `1234567890\E-=[]\;',./ ~!@#$%^&amp;*()_+{}|:&quot;&lt;&gt;?

Escape Characters in Variable as a Literal Pattern

Description

Returns a literal regular expression pattern String for the value of the specified variable.
 
This method produces a String that can be used to create a Pattern that would match the String as if it were a literal pattern.

Syntax

${_varLiteralPattern('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function. The variable value will be escaped for insertion into a regular expression as a literal pattern.

Example

Variable Name:
escape_me
 
Variable Value:
`1234567890\E-=[]\;',./ ~!@#$%^&*()_+{}|:"<>?
 

${_varLiteralPattern('escape_me')} --> \Q`1234567890\E\\E\Q-=[]\;',./ ~!@#$%^&*()_+{}|:"<>?\E

Randomly Generate a String

Description

Randomly generates a String with a specified length.

Syntax

${_randomString(length[, 'excludeCharacters', 'defaultCharacters'])}

Parameters

  • length
    Required; String length.
  • excludeCharacters
    Optional; String containing characters to exclude from the default character set.
  • defaultCharacters
    Optional; String for overriding default character set.

Note

The following characters are included in the default character set, in addition to the space character.

${_randomString(24, '', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890@#$%*')} --> 5*L8T1RN#$AQWEKPA@BQ19JD

Example

Replace Substring of Value with Regular Expression

Description

Replaces each substring of value that matches the specified regular expression, regex, with the specified replacement.

Syntax

${_replaceAll('value', 'regex', 'replacement')}

Parameters

  • value
    Required; Input string.
  • regex
    Required; Regular expression.
  • replacement
    Required; Replacement string.

Replace Substring of Variable with Regular Expression

Description

Replaces each substring of variableName that matches the specified regular expression, regex, with the specified replacement.

Syntax

${_varReplaceAll('variableName', 'regex', 'replacement')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.
  • regex
    Required; Regular expression.
  • replacement
    Required; Replacement string.

Return Base64 Encoded String

Description

Returns the value of the specified variable encoded using the Base64 encoding scheme.

Syntax

${_varEncodeBase64('variableName'[, 'charset'])}

Parameters

  • variableName
    Required; Name of the variable whose value will be encoded using the Base64 encoding scheme.
  • charset
    Optional; Name of the charset; default UTF-8.
Example

Where Variable rawstring contains a value of "Test String":

${_varEncodeBase64('rawstring')} --> VGVzdCBTdHJpbmc=

Return Copy of Value with Whitespace Omitted

Description

Returns a copy of value, with leading and trailing whitespace omitted.

Syntax

${_trim('value')}

Parameters

  • value
    Required; String to trim.

Return Copy of Variable with Whitespace Omitted

Description

Returns a copy of variableName, with leading and trailing whitespace omitted.

Syntax

${_varTrim('variableName')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.

Return Index of Substring in String Value

Description

Returns the index within the string value of the first occurrence of the specified substring, str.

Syntax

${_indexOf('value', 'str')}

Parameters

  • value
    Any string.
  • str
    Substring to search for. If the str argument occurs as a substring within the value, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.

Return Index of Substring in String Variable

Description

Returns the index within the string variable of the first occurrence of the specified substring, str.

Syntax

${_varIndexOf('variableName', 'str')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.
  • str
    Required; Substring to search for. If the str argument occurs as a substring within the variable, the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.

Return Index of Substring Plus Offset in String Value

Description

Returns the index within this string of the first occurrence of the specified substring plus the specified offset. The integer returned is the smallest value.

Syntax

${_indexOfWithOffset('value', 'str', offset)}

Parameters

  • value
    Required; Any string.
  • str
    Required; Substring to search for. If the str argument occurs as a substring within the value, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.
  • offset
    Required; Number (positive or negative) to offset the found index.

Return Index of Substring Plus Offset in String Variable

Description

Returns the index within this string of the first occurrence of the specified substring plus the specified offset. The integer returned is the smallest variable.

Syntax

${_varIndexOfWithOffset('variableName', 'str', offset)}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.
  • str
    Required; Substring to search for. If the str argument occurs as a substring within the variable, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.
  • offset
    Required; Number (positive or negative) to offset the found index.

Return Index of Rightmost Occurrence of Substring in String Value

Description

Returns the index within the string value of the rightmost occurrence of the specified substring, str.

Syntax

${_lastIndexOf('value', 'str')}

Parameters

  • value
    Required; Any string.
  • str
    Required; Substring to search for. If the str argument occurs one or more times as a substring within the value, then the index of the first character of the last such substring is returned. If it does not occur as a substring, -1 is returned.

Return Index of Rightmost Occurrence of Substring in String Variable

Description

Returns the index within the string variable of the rightmost occurrence of the specified substring, str.

Syntax

${_varLastIndexOf('variableName', 'str')}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.
  • str
    Required; Substring to search for. If the str argument occurs one or more times as a substring within the variable, then the index of the first character of the last such substring is returned. If it does not occur as a substring, -1 is returned.

Return Index of Rightmost Occurrence of Substring Plus Offset in String Value

Description

Returns the index within this string of the rightmost occurrence of the specified substring, plus the specified offset. The returned index is the largest value.

Syntax

${_lastIndexOfWithOffset('value', 'str', offset)}

Parameters

  • value
    Required; Any string.
  • str
    Required; Substring to search for. If the str argument occurs as a substring within the value, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.
  • offset
    Required; Number (positive or negative) to offset the found index.

Return Index of Rightmost Occurrence of Substring Plus Offset in String Variable

Description

Returns the index within this string of the rightmost occurrence of the specified substring, plus the specified offset. The returned index is the largest variable.

Syntax

${_varLastIndexOfWithOffset('variableName', 'str', offset)}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.
  • str
    Required; Substring to search for. If the str argument occurs as a substring within the variable, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.
  • offset
    Required; Number (positive or negative) to offset the found index.

Return Length of Value

Description

Returns the length of value.

Syntax

${_length('value')}

Parameters

  • value
    Required; Any string.

Return Length of Variable

Description

Returns the length of variableName.

Syntax

${_varLength('variableName'[, useEmptyForUndefined])}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.
  • useEmptyForUndefined
    Optional; Specification (true or false) for the handling of a missing variable name. Default is false.
    • If useEmptyForUndefined = true, the function will return 0.
    • If useEmptyForUndefined = false, the function will remain unresolved if the variable name does not exist.

Return New String that is Substring of Value

Description

Returns a new string that is a substring of value. The substring begins at beginIndex and extends to the character at endIndex -1.

Syntax

${_substring('value', beginIndex[, endIndex])}

Parameters

  • value
    Required; String to make a substring from.
  • beginIndex
    Required; Beginning index, inclusive.
  • endIndex
    Optional; Ending index, exclusive.

Example

Return New String that is Substring of Variable

Description

Returns a new string that is a substring of variableName. The substring begins at beginIndex and extends to the character at endIndex -1.

Syntax

${_varSubstring('variableName', beginIndex[, endIndex])}

Parameters

  • variableName
    Required; Name of the variable being passed into the function.
  • beginIndex
    Required; Beginning index, inclusive.
  • endIndex
    Optional; Ending index, exclusive.

Examples

If the value of the food variable is hamburger, and the value of the face variable is smiles:
 

Return URL-Encoded String

Description

Returns a URL-encoded string according to the ASCII Encoding Reference for UTF-8; all non-alphanumeric characters are replaced with their equivalent hexadecimal escape sequences.

Syntax

${_varEncodeUrl('variableName')}

Parameters

  • variableName
    Required; Name of the variable whose value will be converted to a URL encoded string.
Example

Where Variable rawstring contains a value of “ABC$%^----DEF":

${_varEncodeUrl(‘rawstring’)} --> ABC%24%25%5E----DEF


System Functions

Display Variables

Description

Displays all the defined and built-in variables associated with the task instance.

Syntax

${_scope}

Parameters

(none)

Example

Generate Random Number

Description

Generates a random number between max (inclusive) and min (inclusive)

Syntax

${_random([max, min])}

Parameters

  • max
    Optional; Upper bound (inclusive) on the random number. Default is 9.
  • min
    Optional; Lower bound (inclusive) on the random number. Default is 0.

Resolve to GUID (Globally Unique ID)

Description

Resolves to a 32-byte GUID (Globally Unique ID).

Syntax

${_guid}

Parameters

(none)

Resolve to Host Name

Description

Resolves to the hostname of the machine running the Controller, if available.

Syntax

${_hostname}

Parameters

(none)

Resolve to IP Address

Description

Resolves to the IP address of the machine running the Controller.

Syntax

${_ipaddress}

Parameters

(none)

Resolve to SYS_ID

Description

Resolves to the sys_id of the first task instance found within the same workflow specified by the sibling name.

Syntax

${_siblingid('sibling_name')}

Parameters

  • sibling_name
    Required; Sibling name.

Example

Resolve to Variable Value

Description

Locates the specified variable in the specified sibling task instance within the same workflow and resolves to the variable value.

Syntax

${_varLookup('sibling_name', 'variable_name'[,'def'])}

Parameters

  • sibling_name
    Required; Name of the sibling task instance from which the function is collecting the variable value.
  • variable_name
    Required; Name of the variable being collected by the function.
  • def
    Optional; Default value to return if the variable is not defined in the sibling task instance.

Resolve Variable

Description

Resolves the variable specified by the variable_name parameter and substitutes the default_value if the variable cannot be resolved.

Syntax

${_resolve('variable_name', 'default_value')}

Parameters

  • variable_name
    Required; Variable name.
  • default_value
    Required; Default value to use if the variable cannot be resolved.

Resolve Variable (Advanced)

Description

Resolves the variable specified by the variable_name parameter and substitutes the default value if the variable cannot be resolved.

Syntax

${_resolveadv('variable_name', 'default_value', [use_default_if_blank])}

Parameters

  • variable_name
    Required; Variable name.
  • default_value
    Required; Default value to use if the variable cannot be resolved.
  • use_default_if_blank
    Optional; Specification (true or false) for whether or not to use the default value if the variable is empty or blank. (If use_default_if_blank is false, _resolveadv behaves like Functions#_resolve.)

Universal Task Functions

Convert Array Field Variable

Description

Given the variable name representing the Array field, generate a String of delimited Array field entry data.

Note

The function does not support resolving embedded functions found within the content of the Array field; it, only supports the resolution of embedded variables.

Syntax

${_convertArrayFieldVariable('arrayFieldVariableName'[,'delimiter', 'separator', 'keyQuote', 'valueQuote'])}

Parameters

  • arrayFieldVariableName
    Required; Name of the variable for the Array Field; for example, ops_af_p2.
  • delimeter
    Optional; Value to be used to delimit the Name from the Value. Default is =.
  • separator
    Optional; Value to be used to separate one entry/row from the next. Default is comma (,).
  • keyQuote
    Optional; Quoting to be used around the Name. Default is "no quoting."
  • valueQuote
    Optional; Quoting to be used around the Value. Default is "no quoting."

Example

Get Array Field Variable Value

Description

Given the variable name representing the Array field and the name of an entry in the Array field, return the value for the entry.

Note

The function does not support resolving embedded functions found within the content of the Array field; it, only supports the resolution of embedded variables.

Syntax

${_getArrayFieldVariableValue('arrayFieldVariableName', 'name')}

Parameters

  • arrayFieldVariableName
    Required; Name of the variable for the Array Field; for example, ops_af_p1.
  • name
    Required; Name of the entry for which the value is to be returned.

Example