Request configuration for data actions


Note: This article applies to the Adobe, AWS Lambda, Microsoft Dynamics 365, PureCloud, 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 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.

Note: GET requests do not use request templates. The requestTemplate field shows a default value of “${input.rawRequest}”.
Warning: Be sure to 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.

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.

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 supports 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 Adobe data actions integration adds key-value pairs to actions at runtime for authentication handling. The following attributes are automatically set:

  • x-api-key
  • x-gw-ims-org-id
  • x-sandbox-name (if configured)

    You can add a sandbox name to the integration credentials or as a header in an action. If the sandbox name is set in both places, the integration uses the header configured in the data action. For more information, see Add a data actions integration

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

  • 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 data actions integration, 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 in the Velocity macros for data actions article.

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: PureCloudIntegrations/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": "PureCloudIntegrations/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": "PureCloudIntegrations/1.0",
        	    "Company": "My company"
         },
         "response": {
             ...
         }
    },
    "category": "Sample",
    "version": 1,
    "secure": true,
    "selfUri": "/api/v2/integrations/actions/<action ID>"
}

For 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 Adobe data actions integration, About the AWS Lambda data actions integration, About the Microsoft Dynamics 365 data actions integration, About the PureCloud data actions integration, About the Salesforce data actions integration, About the web services data actions integration, and About the Zendesk data actions integration.