Request configuration for data actions

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

You can create custom actions for the data actions integrations. A custom action includes a request and a response in its configuration. For more information, see Create a custom action for integrations.

This article explains the parts of the request. For more information about the response, see Response configuration.

Custom actions use request templates to define the body of POST, PUT, and PATCH requests to remote endpoints or to your AWS Lambda functions. The remote endpoints are defined by requestUrlTemplate. These request templates support the use of macros. For more information, see Velocity macros for data actions.

Notes:

GET requests do not use request templates. The requestTemplate field shows a default value of “${input.rawRequest}”.
Excessively nested JSON objects can affect the performance of the data action service. To maintain the performance, the depth of JSON objects is limited to 50 levels. For more information, see Limits in Genesys Cloud Developer Center.

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 fail at execution.

Use esc.jsonString to escape strings inside JSON bodies.
For more information, see the esc.jsonString section at Velocity macros.
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.
For more information, see the String-escaping library section at Velocity macros and URL form encoding for data actions.

requestTemplate

Request templates use Velocity to define the body of POST, PUT, and PATCH requests. After you save a request template, the API response references it as requestTemplateUri.

For the AWS Lambda data actions integration, any inputs that you specify under requestTemplate will be available in the event parameter of the invoked AWS Lambda function.
For Google Cloud Functions, the $esc.jsonString macro converts strings in a request to JSON.

headers

Headers are key-value pairs that are added as HTTP headers on the request that is sent to the remote endpoint. The header values support Velocity substitution.

Note: If you rely on the API to handle the authorization, do not include authorization in the request header. The integration will automatically populate the header. Otherwise, include your own authorization in the request header.

The AWS Lambda data actions integration adds key-value pairs as clientContext items on the invocation context object. If the attributes exist, the following attributes are automatically set on the context object :

ININ-Conversation-Id
ININ-Organization-Id
ININ-Home-Organization-Id
ININ-Correlation-Id
ININ-User-Id
ININ-Integration-Id

requestType

requestType defines the type of HTTP request in your data action. Available HTTP request types include POST, PUT, and PATCH.

Note: For the AWS Lambda and Google data actions integrations, use POST. This HTTP method ensures that any request body is sent.

requestUrlTemplate

requestUrlTemplate is the remote endpoint that your HTTP request hits or the ARN of the AWS Lambda function that the AWS data actions integration invokes. requestUrlTemplate uses Velocity templates for variable substitution.

Note: If the requestUrlTemplate references an HTTP endpoint, requestUrlTemplate must reference an HTTP Secure (HTTPS) endpoint.

requestTemplateUri

requestTemplateUri is a reference URI for your requestTemplate. When you save the requestTemplate, the integration collapses it. To see the contents of your requestTemplate after you have saved it, issue a GET operation on requestTemplateUri.

Example requestTemplate

Action execution body

The following REST call triggers the action sampleAction123 and passes three properties defined in the inputSchema in the sample action.

curl -X POST https://api.mypurecloud.com/api/v2/integrations/actions/sampleAction123/execute \
  -H 'authorization: bearer *****' \
  -d '{
    "USER_ID": 123,
    "FIRST_NAME":"John",
    "LAST_NAME": "Smith"
}'

The action service finds and replaces any values that reference these three properties in the sample action, including requestUrlTemplate and requestTemplate.

requestTemplate

The action is configured to have the following requestTemplate:

"{"firstName": "$esc.jsonString(${input.FIRST_NAME})","lastName": "$esc.jsonString(${input.LAST_NAME})"},

For more information about escaping, see the esc.jsonString section at Velocity macros for data actions.

The action service replaces the Velocity template placeholders in the sample action, resulting in the following:

{
  "firstName": "John",
  "lastName": "Smith"
}

requestTemplate becomes the body of the HTTP POST sent to the remote endpoint.

Web service call

The modified sample action results in the following web service call:

curl -X POST \
  https://sample.com/users/123 \
  -H 'content-type: application/json' \
  -H 'UserAgent: GenesysCloudIntegrations/1.0' \
  -H 'Company: My company' \
  -d '{
  "firstName": "John",
  "lastName": "Smith"}'

Request to create a new action

The following is an action configured to perform a POST to https://sample.com/users/${input.USER_ID}. inputSchema defines three properties used to construct a request: USER_ID, FIRST_NAME, LAST_NAME. These three properties are referenced in requestTemplate and requestUrlTemplate.

{
  "category": "Sample",
  "contract": {
    "input": {
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Update user's first and/or last name",
        "properties": {
          "USER_ID": {
            "description": "User Id",
            "type": "number"
          },
          "FIRST_NAME": {
            "description": "Users first name",
            "type": "string"
          },
          "LAST_NAME": {
            "description": "User last name",
            "type": "string"
          }
        },
        "required": [
          "USER_ID",
          "FIRST_NAME",
          "LAST_NAME"
        ],
        "title": "Update name request",
        "type": "object"
      }
    },
    "output": {
      ...
    }
  },
  "config": {
    "request": {
      "headers": {
        "Content-Type": "application/json",
        "UserAgent": "GenesysCloudIntegrations/1.0",
        "Company": "My company"
      },
      "requestTemplate" : "{\"firstName\": \"${input.FIRST_NAME}\",\"lastName\": \"${input.LAST_NAME}\"}",
      "requestType": "POST",
      "requestUrlTemplate": "https://sample.com/users/${input.USER_ID}"
    },
    "response": {
      ...
    }
  },
  "name": "Sample Action",
  "secure": true
}

Result of getting the action definition

{
    "id": "<action ID>",
    "name": "Sample Action", 
    ...
    "config: {
        "request": {
            "requestUrlTemplate": "https://sample.com/users/${input.USER_ID}",
            "requestTemplateUri": "/api/v2/integrations/actions/<action ID>/templates/requesttemplate.vm",
            "requestType": "POST",
            "headers": {
                "Content-Type": "application/json",
        	    "UserAgent": "GenesysCloudIntegrations/1.0",
        	    "Company": "My company"
         },
         "response": {
             ...
         }
    },
    "category": "Sample",
    "version": 1,
    "secure": true,
    "selfUri": "/api/v2/integrations/actions/<action ID>"
}

For more information about the configuration in custom actions, see Add configuration and Modify configuration.

For more information, see About custom actions for integrations.

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