External data sources concept_t2s_kqt_52b
External data sources allow you to define a connection to third-party systems, for example if you鈥檙e using a hotel booking system to check if the person has registered a room. As opposed to the build-in 蜜豆视频 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鈥檚 take the example of a weather API service that I want to use to customize my journey鈥檚 behaviors according to real-time weather data.
Here are two examples of the API call:
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
The call is composed of a main URL (https://api.adobeweather.org/weather), two parameter sets (鈥渃ity鈥 for the city and 鈥渓at/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.
note note NOTE 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.
note caution CAUTION We strongly recommend using HTTPS for security reasons. Also note that we don鈥檛 allow the use of 蜜豆视频 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:
- Type: 鈥淎PI key鈥
- Value: 鈥1234鈥 (this is the value of our API key)
- Name: 鈥渁ppid鈥 (this is the API key parameter name)
- Location: 鈥淨uery parameter鈥 (the API key is located in the URL)
-
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 鈥渓ong/lat鈥 parameter set, we create a field group with the following information:
- Used in: displays the number of journeys that use a field group. You can click the View journeys icon to display the list of journeys using this field group.
- Method: select the POST or GET method. In our case, we select the GET method.
- Response Payload: click inside the Payload field and paste an example of the payload returned by the call. For our example, we used a payload found on a weather API website. Verify that the field types are correct. Each time the API is called, the system will retrieve all the fields included in the payload example. Note that you can click on Paste a new payload if you want to change the payload currently passed.
- Dynamic Values: enter the different parameters separated by a coma, 鈥渓ong,lat鈥 in our example. Since the parameter values depend on the execution context, they will be defined in the journeys. See this page.
- Sent Payload: this field does not appear in our example. It is only available if you select the POST method. Paste the payload that will be sent to the third-party system.
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: 鈥渋dentifier鈥).
-
specify them also with the exact same syntax in the body of the sent payload. To do so, you need to add: 鈥減aram鈥: 鈥渘ame of your parameter鈥 (in the example below: 鈥渋dentifier鈥). Follow the syntax below:
code language-none {"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.
Custom authentication mode section_wjp_nl5_nhb
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:
- Call the endpoint to generate the access token.
- Call the REST API by injecting in the proper way the access token.
This authentication has two parts.
The definition of the endpoint to be called to generate the access token:
-
endpoint: URL to use to generate the endpoint
-
method of the HTTP request on the endpoint (GET or POST)
-
headers: key/value pairs to be injected as headers in this call if required
-
body: describes the body of the call if the method is POST. We support a limited body structure, defined in the bodyParams (key/value pairs). The bodyType describes the format and encoding of the body in the call:
- 鈥榝orm鈥: meaning that the content type will be application/x-www-form-urlencoded (charset UTF-8) and the key/value pairs will be serialized as is: key1=value1&key2=value2&鈥
- 鈥榡son鈥: meaning that the content type will be application/json (charset UTF-8) and the key value pairs will be serialized as a json object as is: { 鈥渒ey1鈥: 鈥渧alue1鈥, 鈥渒ey2鈥: 鈥渧alue2鈥, 鈥
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:
- bearer: indicates that the access token must be injected in the Authorization header, such as: Authorization: Bearer <access token>
- header: indicates that the access token must be injected as a header, the header name defined by the property tokenTarget. For instance, if the tokenTarget is myHeader, the access token will be injected as a header as: myHeader: <access token>
- queryParam: indicates that the access token must be injected as a queryParam, the query param name defined by the property tokenTarget. For instance, if the tokenTarget is myQueryParam, the URL of the action call will be: <url>?myQueryParam=<access token>
-
tokenInResponse: indicates how to extract the access token from the authentication call. This property can be:
- 鈥榬esponse鈥: indicates that the HTTP response is the access token
- a selector in a json (assuming that the response is a json, we don鈥檛 support other formats such as XML). The format of this selector is json://<path to the access token property>. For instance, if the response of the call is: { 鈥渁ccess_token鈥: 鈥渢heToken鈥, 鈥渢imestamp鈥: 12323445656 }, the tokenInResponse will be: json: //access_token
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 鈥渃acheDuration鈥 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" }
}