Show Menu
TOPICS×

External API

Description

The External API activity brings data into the workflow from an external system via an HTTP API call.
The external system endpoints can be public API endpoints, customer management systems, or serverless application instances (e.g., Adobe I/O Runtime ), to mention a few categories.
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.
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

Transitioning from Beta to GA

With Campaign Standard 20.3 release, External API capability has moved trom Beta to General Availability (GA).
As a consequence, if you were using beta External API activities, you need to replace them with GA External API activities in all workflows.  Workflows that use the beta version of External API will stop working starting 20.3 release.
When replacing External API activities, add the new External API activity to the workflow, manually copy over the configuration details, then delete the old activity.
You will not be able to copy over header values as those are masked within the activity.
Next, reconfigure other activities in the workflow which point to and/or use data from the beta External API activity to point to and/or use data from the new External API activity instead. Examples of activities: email delivery (personalization fields), enrichment activity, etc.

Limitations and guardrails

The following guardrails apply to this activity:
  • 50MB http response data size limit (5MB recommended)
  • Request timeout is 10 minutes
  • HTTP redirects are not allowed
  • Non-HTTPS Urls are rejected
  • "Accept: application/json" request header and "Content-Type: application/json" response header are allowed
Starting with the Campaign 20.4 release, the http response data size limit and response timeout guardrails will be lowered to 5MB and 1 minute, respectively. While this change will only affect new External API activities, it is strongly recommended that current implementations of the External API activity align with these new guardrails to follow best practices.
Specific guardrails have been put in place for the JSON:
  • JSON Max Depth : limit the maximum depth of a custom nested JSON that can be processed to 10 levels.
  • JSON Max Key Length : limit the maximum length of the internal key generated to 255. This key is associated with the column ID.
  • JSON Max Duplicate Keys Allowed : limit the maximum total number of duplicate JSON property names, which are used as column ID, to 150.
The activity is not supported JSON structure as:
  • Combining array object with other non-array elements
  • JSON array object is nested within one or more intermediate array objects.
The External API activity is meant for fetching 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.

Configuration

Drag and drop an External API activity into your workflow and open the activity to start the configuration.

Inbound Mapping

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.
The Inbound resource dropdown lets you select the query activity that will create the temporary table.
The Add count parameter checkbox will add 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.
The Inbound Columns section 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.
The customize parameter text 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.

Outbound Mapping

This tab lets you define the sample JSON structure returned by the API Call.
The JSON parser is designed to accommodate standard JSON structure pattern types, with some exceptions. An example of a standard pattern is: {“data”:[{“key”:“value”}, {“key”:“value”},...]}
The sample JSON definition must have the following characteristics :
  • Array elements must contain first-level properties (deeper levels are not supported). Property names will end up becoming column names for the output schema of the output temporary table.
  • JSON elements to be captured must be at 10 or less levels of nesting within the JSON response.
  • Column name definition 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 the Column definition tab.
Flatten checkbox behavior:
The Flatten checkbox (default: unchecked) is provided to indicate whether to flatten the JSON to a key/value map or not.
  • When the checkbox is disabled (unchecked), the sample JSON will be parsed to look for an array object. The user will need to provide a trimmed version of the API response sample JSON format so that Adobe Campaign can determine exactly which array the user is interested in using. At workflow authoring time, the path to the nested array object will be determined and recorded, so that it can be used at execution time to access that array object from the JSON response body received from the API call.
  • When the checkbox is enabled (checked), the sample JSON will be flattened and all the properties that are specified in the provided sample JSON will be used to create columns of the output temporary table, and displayed on the Column Definitions tab. Note that if there are any array object in the sample JSON, then all elements of those array objects will also be flattened.
If the parsing is validated , a message appears and invites you to customize the data mapping in the "Column definition" tab. In other cases, an error message is displayed.

Execution

This tab lets you define the HTTPS Endpoint that will send data to ACS. If needed, you can enter authentication information in the fields below.

Properties

This tab lets you control general properties on the external API activity like the displayed label in the UI. The internal ID is not customizable.

Column definition

This tab appears when the response data format is completed and validated in Outbound Mapping tab.
The Column definition tab 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.

Transition

This tab lets you activate the outbound transition and its label. This specific transition is useful in case of timeout or if the payload exceed the data size limit .

Execution options

This tab is available in most of the workflow activities. For more information, consult the Activity properties section.

Troubleshooting

There two types of log messages added to this new workflow activity: information and errors. They can help you troubleshooting potential issues.

Information

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.
Message format Example
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).

Errors

These log messages are used to log information about unexpected error conditions, that can eventually cause the workflow activity to fail.
Code - Message format Example
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: '[2001]').
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').