Velocity macros for data actions


Note: This article applies to the Adobe, AWS Lambda, Google, Microsoft Dynamics 365, Genesys Cloud, Salesforce, web services, and Zendesk data actions integrations.

The data actions integrations allow you to create custom actions. These custom actions include request configurations and response configurations with templates that use the Velocity Template Language. These templates support a range of Velocity macros.

Warning: Escape any use of input or output variables within requestTemplate, successTemplate, or requestUrlTemplate. If you do not properly escape variables with special characters, your data actions will fail at execution.
  • Use esc.jsonString to escape strings inside JSON bodies. See esc.jsonString.
  • Use esc.url() or urlTool.optionalQueryParam() to properly escape path or query parameters for a requestUrlTemplate or requestTemplate if using x-www.form-urlencoded values. See String-escaping library.

Velocity templates are valid for the following fields:

  • requestUrlTemplate
  • headers
  • requestTemplate
  • successTemplate

For more information, see Create a custom action, Request configuration, and Response configuration.

Note: Formal vs. silent formal notation

  • Formal notation: ${variable}

    If the variable is null, formal notation outputs the variable name.

  • Silent formal notation: $!{variable}

    If the variable is null, silent notation outputs an empty string.

Math library

Prefix: math

Use these math macros to perform basic math operation. For more information, see Class MathTool in the Velocity documentation.

String-escaping library

Prefix: esc

Use EscapeTool to escape strings in Velocity templates. EscapeTool provides methods to escape outputs for Java, JavaScript, HTML, XML, and SQL. EscapeTool also provides methods to escape Velocity Template Language characters. For more information, see Class EscapeTool in the Velocity documentation.

Two methods in particular are helpful.

  • $esc.url(): Use this method to escape values for arguments in the urlTemplate. Otherwise, URLs with spaces or other non-URL characters are invalid. 
  • $esc.d(): Use this method to include a dollar sign ($) in a URL.

The following table shows example inputs and outputs of various macros. 

Warning: Do not use JavaScript encoding. $esc.javascript($input) can create invalid JSON that breaks an action.

Macros Inputs Outputs
$esc.java($input) He didn't say, "Stop!" He didn't say, \"Stop!\"
$esc.html($input) "bread" & "butter" "bread" & "butter"
$esc.xml($input) "bread" & "butter" "bread" & "butter"
$esc.sql($input) McHale's Navy McHale''s Navy
$esc.url($input) hello here & there hello+here+%26+there
$esc.dollar $
$esc.hash #
$esc.backslash \
$esc.quote "
$esc.singleQuote '
$esc.exclamation !

encoding.base64

Base64 encodes strings that you provide. 

Template example

Encoded field is $encoding.base64(\"${first} and ${second}\")

Template example results

Inputs Resolved templates

first == cat

second == dog

Encoded field is Y2F0IGFuZCBkb2c=

esc.jsonString

When you build JSON bodies for POST, PUT, and PATH requests, you must escape any strings. This macro escapes quotes and other characters based on JSON encoding rules.

Note: esc.jsonString treats Unicode characters differently than EscapeTool.javascript() does. 

Template example

$esc.jsonString(${input.json})

Template example results

Inputs Resolved templates
This is a string with {an embedded tab}, ", and {an embedded new line}, and a Cyrillic letter Ԃ "This is a string with \\t, \\\", and \\n, and a Cyrillic letter Ԃ"
Note: Because Unicode characters in strings are standard in the JSON encoding specifications, Unicode characters are not escaped to the \u0000 form.

successTemplateUtils.firstFromArray

This macro extracts the first element from the provided JSON array string and has two parameters. The first parameter, which is the input array for the extracted value, is required. The second parameter, which specifies the response that is returned when the array is empty, is optional and by defaults returns nothing. If the array is not empty, the second parameter is ignored. 

If the input for firstFromArray is data extracted through the translationMap JSONPath, then no string escaping is needed. In the following template examples, ids could come from a translationMap entry, such as "ids": "$.idArray".

Template examples and results

Template examples Inputs Resolved templates
${successTemplateUtils.firstFromArray("${ids}")} ids == "[1, 2, 3]" 1
ids == "[{\"id\":1}, {\"id\":2}, {\"id\":3}, {\"id\":4}]" {\"id\":1}
ids == "[]"
ids == "" This input results in an error.
${successTemplateUtils.firstFromArray(\"${ids}\", \"{}\")} ids == "[1, 2, 3]" 1
ids == "[{\"id\":1}, {\"id\":2}, {\"id\":3}, {\"id\":4}]" {\"id\":1}
ids == "[]" {}
ids == "" This input results in an error.
${successTemplateUtils.firstFromArray(\"${ids}\", \"$esc.quote $esc.quote\")}* ids == "[1, 2, 3]" 1
ids == "[{\"id\":1}, {\"id\":2}, {\"id\":3}, {\"id\":4}]" {\"id\":1}
ids == "[]" ""
ids == "" This input results in an error.

* This template example uses EscapeTool to escape characters . For more information, see String-escaping library.

urlTool.optionalQueryParam

This macro formats a key-value pair as a query parameter, unless the value is empty. Otherwise, the macro returns an empty string. Do not include the ampersand (&) in your template; the macro automatically adds the ampersand. See the Template example results.  Only use the macro after at least one required query parameter. In the following template example, the required query parameter is ${input.AMOUNT}.

Note: Use silent formal notation: $!{variable}.

Template example

amount=${input.AMOUNT}$urlTool.optionalQueryParam(\"description\", $!{input.DESCRIPTION})

Template example results

Inputs Resolved templates

input.AMOUNT == 30

input.DESCRIPTION == potatoes

amount=30&description=potatoes

input.AMOUNT == 30

input.DESCRIPTION == ""

amount=30

Java string method macros

Use Java string methods in Velocity templates to manipulate string variables, such as changing the case of a value or extracting a value from a string. For more information, see Class String in the Java 11 documentation.

In the following example, the toUpperCase() method converts the string value of variable $a to upper case. The split() method splits the variable $b into an array of strings. Variable $d concatenates values from variable $a, variable $b, and the first item in the array for variable $c.

Template example

#set($a = ${input1.string1} )
#set($a = $a.toUpperCase() )
#set($b = ${input1.string2} )
#set($c = $b.split("\+") )
#set($d = "We are using ""${a}"" ""${b}"" ""$c[1]"" to render this." )
$d

Template example results

Inputs Resolved templates

input.string1 = value1

input.string2 = value1+value2

We are using "VALUE1" "value1+value2" "value2" to render this.

Microsoft Dynamics macros

msdynamics.fieldSearchFilter

This macro builds a search filter given a value and a list of fields that you want to search. The macro compares the value to each of the fields in the list.

Template example

$msdynamics.fieldSearchFilter(\"$input.EMAIL_ADDRESS\", [\"emailaddress1\", \"emailadress2\"]

Template example results

Inputs Resolved templates
input.EMAIL_ADDRESS = TestMail@example.com emailaddress1 eq 'TestMail@example.com' or emailaddress2 eq 'TestMail@example.com'

msdynamics.phoneNumberFilter

This macro builds a search filter given a phone number and a list of fields that you want to search. The macro strips unsupported characters and any non-digit values, such as + and parentheses, from the phone number and adds “or” between each field. This search filter is useful for comparing a phone number to multiple phone numbers in an account record.

Template example

$msdynamics.phoneNumberFilter(\"$input.PHONE_NUMBER\", [\"telephone1\", \"telephone2\"])

Template example results

Inputs Resolved templates
input.PHONE_NUMBER = +1 (555) 555-0123 telephone1 eq '+1 (555) 555-0123' or telephone2 eq '+1 (555) 555-0123' or telephone1 eq '15555550123' or telephone2 eq '15555550123'

Salesforce macros

salesforce.escReserved

This macro escapes reserved characters from Salesforce SOQL/SOSL queries made in a URL. Salesforce reserves the following characters: ? & | ! { } [ ] ( ) ^ ~ * : \ " ' + -. This macro ensures that the characters are properly escaped. For more information, see FIND {SearchQuery} in the Salesforce documentation.

Template example

FIND {$salesforce.escReserved(${input.PHONE_NUMBER})} IN PHONE FIELDS

Template example results

Inputs Resolved templates
input.PHONE_NUMBER == (555) 555-5555 FIND {\(555\) 555\-5555} IN PHONE FIELDS

For more information, see About custom actions for integrations.

For more information about the integrations, see About the data actions integrations.