Using the Expression Builder

Once you have selected a Placeholder to use for the Parameter within the Playbook Action, you have the option to use the JSON results. Having access to the JSON results provides you with a huge amount of information that the action returns which you can then utilize in successive Playbook actions and flows.

The JSON result data can be manipulated using the Expression Builder in order to extract the relevant data for the action input.

The Expression Builder allows the parsing and manipulating of JSON results and further utilizing them in subsequent actions in an intuitive manner. The Expression Builder generates a variety of dynamic transformation functions that can be chained together and previewed and tested, thereby allowing for an interactive experience for the transformation and parsing of raw action results.

What does the Expression Builder screen look like?

A typical Expression Builder screen looks like this:

It contains the following information:

JSON Sample:
This is an example of potential data and is not based on real time results. The actual data may be different and may contain more or less fields from the example. If the analyst knows of extra fields that will be returned in run time then they can type the relevant key path in the syntax textbox.

Functions
The following pipe functions are supported:

• First (x) - Return first X elements of an array
• Last (x) - Return last X elements of an array
• Min (KeyPath) - return an element of an array by the minimum
• Max (KeyPath) - return an element of an array by the maximum
• Filter (ConditionKey, Operator, Value) - Filter objects by field
• DateFormat ("pattern") - format date by given pattern ('yyyy/dd/mm HH:mm:ss') to supported format ("YYYY-MM-DDThh:mm:ssZ"). Learn more about custom date and time format strings.
• Count () - return the number of elements in expression
• OrderBy ("keyPath", "direction") - order array by given child field
• toLower () - convert expression to lower case letters
• toUpper () - convert expression to upper case letters
• Replace ("x", "y") - replace string in an expression
• Distinct () - remove duplicates from an array
• getByIndex ("index") - Get items of an array by a specified index or a list of indexes
• split ("delimiter") - Divides a string into an array of substrings, using a specified delimiter
• join ("delimiter") - Concatenates an array of strings into a single string, using a specified delimiter
• trim () - Removes leading and trailing whitespaces from a string
• trimChars ("characters") - Removes specified characters from the beginning and end of a string. Leading and trailing whitespaces are always removed, even if not explicitly specified
• substring (start, end) - Extracts a substring from a string, using a specified start index and an optional end index
• incrementValue (value) - Increases a numeric value by a specified amount. If no amount is specified, the value is incremented by 1
• setIfEmpty ("defaultValue") - Returns the provided default value if the input value is empty
• toUnixtime () - Converts a human-readable date and time string (for example, "2014/03/12T13:37:27Z" or "2014-03-12T13:37:27+01:00") to a Unix timestamp, expressed in UTC
• ifThenElse ("operator", "comparedValue", "trueResult", "falseResult") - Evaluates a condition and returns the first expression if true, otherwise returns the second expression

Expression:
The Expression field is where you insert the JSON results together with the functions and pipes to add several functions together and build the expression. We will explore examples of building expressions later on in this document.

Run / Results:
After filling in the Expression Builder, clicking Run will display the Results based on the JSON Sample Data shown in the Expression Builder.

Refer to Use Cases for Expression Builder to see more information.