Request configuration for data actions

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.

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.

• Adobe
• AWS Lambda

requestType

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

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. 

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.