Expression Reference

Literals

Literal values can be used to insert data directly into an expression:

• Strings: "How are you?", 'How are you?'
• Numbers: 40, 30.123
• Arrays: [1, 2, 3]
• Objects: { one: 1, two: 2 }
• Booleans: true, false

Math

Expressions allow you to operate on values. The following operators are available:

• Addition: +
• Subtraction: -
• Division: /
• Division and integer truncation: //
• Division remainder: %
• Multiplication: *
• Power: **

You can use them like this:

2 + 3
=> 5

10 / 5
=> 2

3 * 2
=> 6

Tests and Comparisons

Comparison operators may be used to return a Boolean based on the comparison result of two values:

• Equal (value only): ==
• Strict Equal (value and type): ===
• Not Equal (value only): !=
• Strict Not Equal (value and type): !==
• Greater Than: >
• Greater Than Or Equal: >=
• Less Than: <
• Less Than Or Equal: <=

Expressions also support an “if-else” syntax similar to Python. It can be used to choose from two values:

'Yes' if (variables.Foo == true) else 'No'

This is also useful for selecting default values when a variable is optional and may not be defined:

variables.Foo if variables.Foo else 'Foo'

Built-in Environment Variables

To access the built-in environment variables that are passed to step modules that run as subprocesses, use the following expression:

env.<var name>

The following values are available:

• AGENT_VERSION
• WORKSPACE_PATH
• RUN_PATH
• PROJECT_ID
• RUN_ID
• RUN_NUMBER
• PIPELINE_ID
• PIPELINE_REVISION
• PIPELINE_REVISION_ID
• PIPELINE_NAME
• JOB_ID (only available if the run was a job)

Note that operating system environment variables are not propagated to the values available in the env.* expressions. However, these values are merged into the environment for subprocesses executed by pipelines, such as shell scripts and CLI-drive step modules.

Pipeline Helper Functions

The following top-level helper functions are available when running a pipeline. They’re used in pipeline step properties to help connect steps together.

find_step_by_id(id)

Finds a step in the pipeline by id. Note that you can also access a step by steps.<id>

Returns

A step object, or null if there is no step with the given id. See the step module reference for examples.

find_steps_by_tag(tag)

Finds all steps in the pipeline with the given tag.

Returns

An array of step objects. See the step module reference for examples.

find_steps_by_type(type)

Finds all steps in the pipeline with the given type.

Returns

An array of step objects. See the step module reference for examples.

find_parent_step_by_type(step, type)

Searches a step’s parent dependency chain for the first step with the given type. If multiple parent steps are found at the same distance, an arbitrary parent will be chosen.

Returns

A step object, or null if there is no parent step with the given type. See the step module reference for examples.

Other Helper Functions

The following top-level helper functions are available in any expression.

random_string(generator, length)

Generates a random string using one of several built-in generator functions.

Returns

A randomly generated string.

Examples

To create a random password guaranteed to pass Windows validation (this also works for most Linux systems):

random_string('windowsPassword')
=> "kQi3n49S"

To create a sequence of 10 number characters:

random_string('numeric', 10)
=> "9234576823"

read_file(path, encoding)

Reads a local file on the runner. Only supports text files.

Returns

The content of the file as a string.

Examples

To read a file called “example.txt” from the current run directory:

read_file("example.txt")

To read and parse a JSON file:

read_file("package.json") | parse_json
(read_file("package.json") | parse_json).version

credential(id)

Loads a credential’s data. This helper is not needed for step modules with credential support, however it is often useful for manipulating credential data directly in a pipeline step.

Returns

A credential data object. See the credential reference for more information about credential types.

Examples

To retrieve the password from a Username/Password credential with ID myCred:

credential("myCred").password

Filters

Filters are similar to helper functions, except they are “piped” an input value using the | character. For example,

[1, 2, 3] | join(',')
=> "1,2,3"

This allows chaining of filters to perform complex operations on data:

findStepsByTag('vm') | slice(2) | json_query('[*].properties.name') | join(',')
=> "vm1,vm2"

All filters from Nunjucks are available, as well as some additional filters that are listed below.

Filters used commonly in Refactr are documented in more detail here. For a complete list of built-in filters, see the Nunjucks built-in filters.

capitalize()

Make the first letter uppercase, and the rest lower case.

Returns

The capitalized string.

default(value)

Provides a default value when the filtered value is undefined.

Returns

The default value if the filtered value is undefined, otherwise the filtered value.

first()

Returns the first value of a list.

Returns

The first item.

last()

Returns the last value of a list.

Returns

The last item.

random()

Selects a random item from a list.

Returns

The randomly chosen item.

replace(search, value)

Replaces every occurence of search with value.

Returns

The new string with values replaced.

Examples

Replace hyphens with underscores in a string:

'foo-bar-baz' | replace('-', '_')

=> "foo_bar_baz"

join(delimiter)

Return a string which is the concatenation of the strings in a sequence.

Returns

The joined string.

Examples

To convert an array of FQDN segments into a single FQDN string:

['app1', 'mydomain', 'com'] | join('.')
=> "app1.mydomain.com"

split(delimiter)

Divides a string into an ordered list of substrings, puts these substrings into an array, and returns the array.

Returns

An array containing the substrings.

date_format(formatter, timezone)

Creates a formatted string representing the current date/time. This helper utilizes the date-fns library to perform the formatting, and also supports zzz timezone tokens.

Returns

The current date/time as a formatted string.

Examples

To produce a calendar date in the format [month]/[day]/[year]:

date_format('MM/dd/yyyy')
=> "11/27/2021"

To produce a date string in ISO 8601 format with a specific timezone:

date_format('yyyy-MM-dd\'T\'HH:mm:ssXXX', 'Pacific/Honolulu')
=> "2021-04-15T11:53:41-10:00"

quote()

Escapes and wraps a string so that it can safely be provided as a single command line argument in a shell.

Returns

The escaped string, which can be provided as a shell command argument.

merge(obj)

Merges two objects together. obj will be merged into the input object and will override keys with the same name. Performs a shallow merge.

Returns

A new object which is the result of merging the two input objects.

merge_deep(obj)

Merges two objects together. obj will be merged into the input object and will override keys with the same name. Performs a recursive merge. Note that array values will be replaced, rather than appended.

Returns

A new object which is the result of merging the two input objects.

ternary(valueA, valueB)

This filter can be used instead of the if-else pattern. It is equivalent to the ternary operator in most programming languages.

Returns valueA if the filtered value is truthy, otherwise returns valueB.

Returns

valueA or valueB depending on the filtered value.

Examples

The following expression evaluates to “Yes” if the value of variables.Foo is true:

(variables.Foo == true) | ternary('Yes', 'No')
=> "Yes"

json_query(query)

The json_query filter lets you query a complex data structure. It can be used to select sub-values from an object or list of objects, like those returned by the find*() helper functions.

json_query utilizes JMESPath as the query language. Visit the JMESPath Examples page to learn more about JMESPath queries and to try out queries using their embedded tester.

Returns

The query result.

Examples

To retrieve a list of names from all steps tagged with the rdsh tag:

findStepsByTag('rdsh') | json_query('[*].properties.name')
=> ["Virtual Machine 1", "Virtual Machine 2"]

parse_json(str)

Parses a JSON string. JSON data structures can be represented natively in Refactr’s engine.

Returns

The result of parsing the JSON.

parse_yaml(str)

Parses a YAML string. At minimum, JSON-compatible YAML features are supported.

Returns

A dictionary data structure containing the parsed YAML.

parse_xml(str)

Parses an XML string, such as that returned by an HTTP response, into a dictionary data structure.

The dictionary contains keys matching the tag names in the XML. Attributes are placed in a sub-dictionary under the special $ key. Inner node text is placed under the special _ key. Child nodes are placed recursively as arrays in their respective tag keys, each having the same structure.

parse_xml utilizes xml2js to perform the parsing.

Returns

A dictionary data structure containing the parsed XML.

Examples

{| my_xml_string | parse_xml |}

Given an XML string:

<foo>
    <bar name="1">Bar 1</bar>
    <bar name="2">Bar 2</bar>
</foo>

parseXML will produce:

{
    "foo": {
        "bar": [
        {
            "_": "Bar 1",
            "$": {
            "name": "1"
            }
        },
        {
            "_": "Bar 2",
            "$": {
            "name": "2"
            }
        }
        ]
    }
}

base64encode(str)

Returns The base64-encoded result.

Examples

'username:password' | base64encode

=> dXNlcm5hbWU6cGFzc3dvcmQ=

base64decode(str)

Returns

The UTF-8 decoded result.

Examples

'dXNlcm5hbWU6cGFzc3dvcmQ=' | base64decode

=> username:password

hmac(type, data, secret)

Computes an HMAC signature for a given string and secret string.

Returns

An HMAC signature string.

Test Expressions

Test expressions perform a comparison or check, and evaluate to true or false. They use the “is” syntax:

<expression to test> is <test function>

e.g., the following expression evaluates to true if the step with id step1 has the content property defined:

steps.step1.properties.content is defined

The following test functions are available:

equalto(value)

Returns true if the input is strictly equal to the value, and false otherwise. Aliased as sameas(value) and eq(value).

ne(value)

Returns true if the input is not strictly equal to the value, and false otherwise.

defined()

Returns true if the input is defined, and false otherwise.

undefined()

Returns true if the input is undefined, and false otherwise.

divisibleby(value)

Returns true if the input is divisible by the value, and false otherwise.

even()

Returns true if the input is an even number, and false otherwise.

odd()

Returns true if the input is an odd number, and false otherwise.

falsy()

Returns true if the input is falsy, which includes false, 0, null, undefined, and empty strings, and false otherwise.

truthy()

Returns true if the input is truthy, which includes true, 1, and non-empty strings, and false otherwise.

greaterthan(value)

Returns true if the input is greater than the value, and false otherwise. Aliased as gt().

lessthan(value)

Returns true if the input is less than the value, and false otherwise. Aliased as lt().

lower()

Returns true if the input is an all-lowercase string , and false otherwise.

upper()

Returns true if the input is an all-uppercase string, and false otherwise.

null()

Returns true if the input is null, and false otherwise.

number()

Returns true if the input is a number, and false otherwise.

string()

Returns true if the input is a string, and false otherwise.

iterable()

Returns true if the input is iterable, which includes arrays and strings, and false otherwise.