External data sources allow you to define a connection to third-party systems, for example if you’re using a hotel booking system to check if the person has registered a room. As opposed to the build-in Adobe Experience Platform data source, you can create as many external data sources as you need.
REST APIs using POST or GET and returning JSON are supported. API Key, basic and custom authentication modes are supported.
Let’s take the example of a weather API service that I want to use to customize my journey’s behaviors according to real-time weather data.
Here are two examples of the API call:
The call is composed of a main URL (https://api.adobeweather.org/weather), two parameter sets (“city” for the city and “lat/long” for the latitude and longitude) and the API key (appid).
Here are the main steps to create and configure a new external data source:
From the list of data sources, click Create data source to create a new external data source.
This opens the data source configuration pane on the right-hand side of the screen.
Enter a name for your data source.
Do not use spaces or special characters. Do not use more than 30 characters.
Add a description to your data source. This step is optional.
Add the URL of the external service. In our example: https://api.adobeweather.org/weather.
We strongly recommend using HTTPS for security reasons. Also note that we don’t allow the use of Adobe addresses that are not publicly available and the use of IP addresses.
Configure the authentication depending on the external service configuration: No authentication, Basic, Custom or API key. For more information on the custom authentication mode, see this section. In our example, we choose:
Add a new field group for each API parameter set by clicking Add a New Field Group. Do not use spaces or special characters in the field group name. In our example, we need to create two field groups, one for each parameter set (city and long/lat).
For the “long/lat” parameter set, we create a field group with the following information:
In case of a GET call requiring parameter(s), you enter the parameter(s) in the Dynamic Values field and they are automatically added at the end of the call. In case of a POST call, you need to:
list the parameters to be passed at call time in the Dynamic Values field (in the example below: “identifier”).
specify them also with the exact same syntax in the body of the sent payload. To do so, you need to add: “param”: “name of your parameter” (in the example below: “identifier”). Follow the syntax below:
{"id":{"param":"identifier"}}
Click Save.
The data source is now configured and ready to be used in your journeys, for example in your conditions or to personalize an email. If the temperature is above 30°C, you can decide to send a specific communication.
This authentication mode is used for complex authentication, frequently used to call API wrapping protocols such as OAuth2, to retrieve an access token to be injected in the real HTTP request for the action.
When you configure the custom authentication, you can click on the button below to check if the custom authentication payload is correctly configured.
If the test is successful, the button turns green.
With this authentication, the action execution is a two-step process:
This authentication has two parts.
The definition of the endpoint to be called to generate the access token:
The definition of the way the access token must be injected in the HTTP request of the action:
authorizationType: defines how the generated access token must be injected in the HTTP call for the action. The possible values are:
tokenInResponse: indicates how to extract the access token from the authentication call. This property can be:
The format of this authentication is:
{
"type": "customAuthorization",
"authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
(optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
"endpoint": "<URL of the authentication endpoint>",
"method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
(optional) "headers": {
"<header name>": "<header value>",
...
},
(optional, mandatory if method is 'POST') "body": {
"bodyType": "<'form'or 'json'>,
"bodyParams": {
"param1": value1,
...
}
},
"tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'"
}
You can change the cache duration of the token for a custom authentication data source. Below is an example of a custom authentication payload. The cache duration is defined in the “cacheDuration” parameter. It specifies the retention duration of the generated token in the cache. The unit can be milliseconds, seconds, minutes, hours, days, months, years.
"authentication": {
"type":"customAuthorization",
"authorizationType":"Bearer",
"endpoint":"http://localhost:${port}/epsilon/oauth2/access_token",
"method":"POST",
"headers": {
"Authorization":"Basic EncodeBase64(${epsilonClientId}:${epsilonClientSecret})"
},
"body": {
"bodyType":"form",
"bodyParams": {
"scope":"cn mail givenname uid employeeNumber",
"grant_type":"password",
"username":"${epsilonUserName}",
"password":"${epsilonUserPassword}"
}
},
"tokenInResponse":"json://access_token",
"cacheDuration":
{ "duration":5, "timeUnit":"seconds" }
}
Cache duration helps to avoid too many calls to the authentication endpoints. Authentication token retention is cached in services, there is no persistence. If a service is restarted, it starts with a clean cache. The cache duration by default is 1 hour. In the custom authentication payload, it can be adapted by specifying another retention duration.