External APIactivity brings data into the workflow from an
external systemvia a
The REST endpoints can be a customer management system, an Adobe I/O Runtime instance or an Experience Cloud REST endpoints (Data Platform, Target, Analytics, Campaign, etc).
For security reasons, the use of JSSPs is not supported in Campaign Standard. If you need to execute code, you can call an Adobe I/O Runtime instance via the External API activity.
This capability is currently in public beta. You need to accept the usage agreement before starting using the External API activity. Please note that since this public beta capability has not yet been commercially released by Adobe, it is not supported by Adobe Client Care, it may contain errors and may not function as well as other released features.
The main characteristics of this activity are:
- Ability to pass data in a JSON format to a 3rd party REST API endpoint
- Ability to receive a JSON response back, map it to output tables and pass downstream to other workflow activities.
- Failure management with an outbound specific transition
The following guardrails have been put in place for this activity:
- 5MB http response data size limit
- Request timeout is 60 seconds
- HTTP redirects are not allowed
- Non-HTTPS Urls are rejected
- "Accept: application/json" request header and "Content-Type: application/json" response header are allowed
Please note that the activity is meant for fetching of campaign wide data (latest set of offers, latest scores etc.) not for retrieving specific information for each profile as that can result in large amounts of data being transferred. If the use case requires this, the recommendation is to use the Transfer File activity.
Drag and drop an
External APIactivity into your workflow and open the activity to start the configuration.
Inbound mapping is a temporary table generated by a previous inbound activity that will be displayed and sent as JSON in the UI. Based on this temporary table, user can make modification to inbound data.
Inbound resourcedropdown lets you select the query activity that will create the temporary table.
Add count parametercheckbox will a count value for each row coming from the temporary table. Note that this checkbox is only available if the inbound activity is generating a temporary table.
Inbound Columnssection allow the user to add any fields from the inbound transition table. The selected column(s) will be the keys in the data object. The data object in the JSON will be an array list containing data for selected columns from each row of the inbound transition table.
customize parametertext box lets you add a valid JSON with additional data needed by the external API. This additional data will be added to the params object in the generated JSON.
This tab lets you define the sample
JSON structurereturned by the API Call.
The JSON structure pattern is:
The sample JSON definition must have the
- datais a mandatory property name in the JSON, the content of "data" is a JSON array.
- Array elementsmust contain first-level properties (deeper levels are not supported).Property nameswould end up becoming column names for the output schema of the output temporary table.
- Column namedefinition is based on the first element of the "data" array. Columns definition (add/remove) and the type value of the property can be edited in theColumn definitiontab.
parsing is validateda message appears and invite you to customize the data mapping in the "Column definition" tab. In other cases, an error message is displayed.
This tab lets you define the
HTTPS Endpointthat will send data to ACS. If needed, you can enter authentication information in the fields below.
This tab lets you control
general propertieson the external API activity like the displayed label in the UI. The internal ID is not customizable.
This tab appears when the
response data formatis completed and validated in Outbound Mapping tab.
Column definitiontab allows you to precisely specify the data structure of each column in order to import data that does not contain any errors and make it match the types that are already present in the Adobe Campaign database for future operations.
For example, you can change the label of a column, select its type (string, integer, date, etc.) or even specify error processing.
For more information, refer to the Load File section.
This tab lets you activate the
outbound transitionand its label. This specific transition is useful in case of
timeoutor if the payload exceed the
data size limit.
This tab is available in most of the workflow activities. For more information, consult the Activity properties section.
There two types of log messages added to this new workflow activity: information and errors. They can help you troubleshooting potential issues.
These log messages are used to log information about useful checkpoints during the execution of the workflow activity. Specifically, the following log messages are used to log the first attempt as well a retry attempt (and reason for failure of first attempt) to access the API.
Invoking API URL '%s'.
Invoking API URL 'https://example.com/api/v1/web-coupon?count=2'.
Retrying API URL '%s', previous attempt failed ('%s').
Retrying API URL 'https://example.com/api/v1/web-coupon?count=2', previous attempt failed ('HTTP - 401').
Transferring content from '%s' (%s / %s).
Transferring content from 'https://example.com/api/v1/web-coupon?count=2' (1234 / 1234).
These log messages are used to log information about unexpected error conditions, that can eventually cause the workflow activity to fail.
Code - Message format
WKF-560250 - API request body exceeded limit (limit: '%d').
API request body exceeded limit (limit: '5242880').
WKF-560239 - API response exceeded limit (limit: '%d').
API response exceeded limit (limit: 5242880').
WKF-560245 - API URL could not be parsed (error: '%d').
API URL could not be parsed (error: '-2010').
Note: This error is logged when the API URL fails validation rules.
WKF-560244 - API URL host must not be 'localhost', or IP address literal (URL host: '%s').
API URL host must not be 'localhost', or IP address literal (URL host: 'localhost').
API URL host must not be 'localhost', or IP address literal (URL host: '192.168.0.5').
API URL host must not be 'localhost', or IP address literal (URL host: '').
WKF-560238 - API URL must be a secure URL (https) (requested URL: '%s').
API URL must be a secure URL (https) (requested URL: 'https://example.com/api/v1/web-coupon?count=2').
WKF-560249 - Failed to create request body JSON. Error when adding '%s'.
Failed to create request body JSON. Error when adding 'params'.
Failed to create request body JSON. Error when adding 'data'.
WKF-560246 - HTTP header key is bad (header key: '%s').
HTTP header key is bad (header key: '%s').
Note: This error is logged when the custom header key fails validation according to RFC
WKF-560248 - HTTP header key is not allowed (header key: '%s').
HTTP header key is not allowed (header key: 'Accept').
WKF-560247 - AHTTP header value is bad (header value: '%s').
HTTP header value is bad (header value: '%s').
Note: This error is logged when the custom header value fails validation according to RFC
WKF-560240 - JSON payload has bad property '%s'.
JSON payload has bad property 'blah'.
WKF-560241 - Malformed JSON or unacceptable format.
Malformed JSON or unacceptable format.
Note: This message only applies to parsing response body from the external API, and is logged when trying to validate whether the response body conforms to the JSON format mandated by this activity.
WKF-560246 - Activity failed (reason: '%s').
When activity fails due to HTTP 401 error response - Activity failed (reason: 'HTTP - 401')
When activity fails due to a failed internal call - Activity failed (reason: 'iRc - -Nn').
When activity fails due to an invalid Content-Type header. - Activity failed (reason: 'Content-Type - application/html').