URI (URL) form encoding for data actions

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

Some APIs, especially login APIs, need URL form encoding for HTTP requests. To configure a Genesys Cloud data action for URI encoding:

Create a Content-Type request header with the value x-www-form-urlencoded.
Set the Request Body Template in the UI, or requestTemplate in JSON or Terraform with the parameters as key-value pairs separated by ampersand (&). For example, key1=value1&key2=value2.
Note: The request body is not JSON, it is a string formatted as URL query arguments.
Use $esc.uriEncode() around values or variables that contain any URL reserved characters, such as / ? : @ – . _ ! ~ $ & ‘ ( ) * + , ; =.

JSON example

"config": { 
     "request": { 
          "requestTemplate": "grant_type=client_credentials&scope=customers_read_write&audience=$esc.uriEncode(\"https://api.example.com/v1/customers\")", 
          "headers": { 
               "Authentication": "Basic $encoding.base64(\"${credentials.clientid}:${credentials.clientSecret}\"", 
               "Content-Type": "application/x-www-form-urlencoded" 
               },
          "requestType": "POST", 
          "requestUrlTemplate": "${credentials.loginUrl}" 
       } 
   }

The following example shows the user input values that have the reserved characters:

"config": {
	"request": {
		"headers": {
			"Content-Type": "application/x-www-form-urlencoded"
		},
		"requestUrlTemplate": "https://api.example.com/v1/customers",
		"requestTemplate": "description=$esc.uriEncode(\"${input.DESCRIPTION}\")&email=$esc.uriEncode(\"${input.EMAIL}\")",
		"requestType": "POST"
	}
}

Note: To protect from injection attacks, always use the $esc.uriEncode() function with the user input. Because the data actions cannot automatically escape the user input with special characters, you have to use the function where applicable for security purposes. Though the data comes from an entity that is invoked includes Architect or Script, escaping must be done when handling the URLs and URL forms.

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