Response 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.

This article explains the parts of the response. For information about requests, see Request configuration.

Custom actions use translation maps and success templates to convert raw responses from remote web services or  your AWS Lambda function into resolved responses that conform to the defined success schemas. These success templates support the use of macros. For more information, see Velocity macros for data actions.

Raw responses

When an action executes for the data actions integrations, the entire response is called the raw response. However, raw responses do not necessarily match the format defined in the success schema for an action. If the raw response does not match, then you can use translation maps and success templates to reformat the data.

Note: Google Cloud Functions return a stringified JSON response that actions convert to JSON before processing translation maps.

Translation maps

Translation maps contain key-value pairs that map property names to the returned values (or object) from the evaluation of JSONPath expressions.

Translation map defaults

Translation map defaults contain key-value pairs that set translation map keys to a default value. The default value is used if the JSONPath expression configured in the translation map fails to resolve a value. Null values do not fall back to defaults.

Success templates

Success templates use the variable notation from the Velocity Template Language. Success templates use the property name from translation maps to insert data returned by the JSONPath expressions. In general, all data in success templates are treated as literals in the output. Items within ${} are references to values from the translation map. For more information, see The Apache Velocity Project documentation.

Resolved responses

Success templates create resolved responses that must conform to the success schemas. Otherwise, errors result.

Success schemas

Success schemas define the required format of an action’s response. 

Use cases

Often you want to use a translation map and success template to convert raw responses in the following situations:

  • Your raw response contains multiple objects. Multiple objects must be returned as members of another object for the resolved output to match the success schema.
  • Your raw response contains values or conversion types, such as arrays, that you want to translate to discrete values.
  • You only want to return a specific subset of data.
  • You want to guarantee the order of the returned attributes.

If the response from the third-party matches the success schema, then you want to return the raw response without any manipulation. In this case, use the default request template. If no other value is provided, then the default request template uses the built-in rawResult context value. The success template then passes the entire result without using a translation map to extract values.

${rawResult}

Example Salesforce GetContactByPhoneNumber action

Raw response

The following is an example raw response from Salesforce when the Salesforce GetContactByPhoneNumber action executes.

{
  "searchRecords": [
    {
      "attributes": {
        "type": "Contact",
        "url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
      },
      "Email": null,
      "FirstName": "Jack",
      "HomePhone": null,
      "Phone": "(317) 555-0123",
      "Id": "003G000001LrjlTIAR",
      "LastName": "Teller",
      "MobilePhone": null,
      "OtherPhone": null,
      "MailingStreet": null,
      "MailingCity": null,
      "MailingState": null,
      "MailingCountry": null,
      "MailingPostalCode": null
    }
  ]
}

The raw response contains a root node (searchRecords). The searchRecords object represents the contact information returned from Salesforce.

Translation map

The translation map pulls segments of data from the raw response. In this case, we want to pull the entire node searchRecords. 

Notes: 
  • Property names in the translation map must start with a letter (a-z, A-Z) and only contain letters, numbers (0-9), hyphens (-), or underscores (_). 
  • If the name of your value contains a space, add brackets and single quotes around the name, for example “contact”: “$.[‘Search Records’]”.

"translationMap": {
  "contact": "$.searchRecords"
}

The JSONPath expression $.searchRecords extracts the searchRecords object from the raw response and assigns it the alias “contact”. The success template uses the alias.

Success template

The success template references the alias “contact” that was created in the translation map. The alias points to an object in the raw response that contains all the values needed to match the success schema.

${contact}

Resolved response

The success template creates a resolved response for the action. The resolved response is the response that the action returns. 

[
    {
      "attributes": {
        "type": "Contact",
        "url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
      },
      "Email": null,
      "FirstName": "Jack",
      "HomePhone": null,
      "Phone": "(317) 555-0123",
      "Id": "003G000001LrjlTIAR",
      "LastName": "Teller",
      "MobilePhone": null,
      "OtherPhone": null,
      "MailingStreet": null,
      "MailingCity": null,
      "MailingState": null,
      "MailingCountry": null,
      "MailingPostalCode": null
    }
]

Example action for use with a payment provider

Raw response

The following is an example raw response with an action when we charge a credit card.

{
  "id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
  "object": "charge",
  "amount": 999,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "balance_transaction": "txn_1AS7Iv2eZvKYlo2CjrARHR6C",
  "captured": true,
  "created": 1496854005,
  "currency": "usd",
  "customer": "cus_AFEwvtMn3H17af",
  "description": null,
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": "in_1AS6Mf2eZvKYlo2C9QEibbxz",
  "livemode": false,
  "metadata": {
  },
  "on_behalf_of": null,
  "order": null,
  "outcome": {
    "network_status": "approved_by_network",
    "reason": null,
    "risk_level": "normal",
    "seller_message": "Payment complete.",
    "type": "authorized"
  },
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [
 
    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_1AS7Iv2eZvKYlo2CmgEX0bHw/refunds"
  },
  "review": null,
  "shipping": null,
  "source": {
    "id": "card_19ukSY2eZvKYlo2CHlYUs1DM",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": "94301",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": "cus_AFEwvtMn3H17af",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2018,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "source_transfer": null,
  "statement_descriptor": null,
  "status": "succeeded",
  "transfer_group": null
}

Translation map

The translation map pulls segments of data from the raw response. In this case, we want to pull four fields from the raw response.

"translationMap": {
  "idValue": "$.id",
  "paidValue": "$.paid",
  "outcomeValue": "$.outcome",
  "sourceValue": "$.source"
}

The JSONPath expressions $.id, $.paid, $.outcome, and $.source extract the values from the raw response and assign them to the aliases idValue, paidValue, outcomeValue, and sourceValue. The translation map defaults set the default value for sourceValue. The success template uses all of these aliases.

Translation map defaults

The translation map defaults set keys in the translation map to default values. In this case, the response did not include a source property so we set sourceValue to the default value “UNKNOWN”.

"translationMapDefaults": {
  "sourceValue": "\"UNKNOWN\""
}

Responses from payment providers may or may not include the source property in the translation map. To ensure that we use the source property if the response includes it and do not throw an error if the response does not include it, set sourceValue in the translation map defaults to “UNKNOWN”.

If responses do not include any other fields in the translation map, the action fails.

Success template

The success template builds a valid JSON response, which references the aliases idValue, paidValue, and outcomeValue that were created in the translation map. The aliases point to values in the raw response that are needed to match the success schema.

{
   "id": ${idValue},
   "outcome": ${outcomeValue},
   "paid": ${paidValue},
   "source": ${sourceValue}
}
Note: The text outside ${} is treated as literals.

Resolved response

The success template creates a resolved response for the action. The resolved response is the response that the action returns.

{
   "id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
   "outcome": {
      "network_status": "approved_by_network",
      "reason": null,
      "risk_level": "normal",
      "seller_message": "Payment complete.",
      "type": "authorized"
   },
   "paid": true,
   "source": "UNKNOWN"
}

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 data actions integrations.