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.

NOTE

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

Backwards compatibility notices

With the Campaign Standard 20.4 release, the http response data size limit and response timeout guardrails have been lowered to align with best practices - see Limitations and guardrails. These guardrail modifications will not take effect on existing External API activities; therefore, it is recommended that you replace existing External API activities with new versions in all workflows.

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.

NOTE

You will not be able to copy over activity-specific header values as those are masked within the activity.

Limitations and guardrails

The following guardrails apply to this activity:

  • 5MB http response data size limit (note: this is a change from the 50MB limit in the previous release)
  • Request timeout is 1 minute (note: this is a change from the 10 minutes timeout in the previous release)
  • HTTP redirects are not allowed
  • Non-HTTPS Urls are rejected
  • “Accept: application/json” request header and “Content-Type: application/json” response header are allowed

Specific guardrails have been put in place:

  • 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.
CAUTION

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 connection endpoint. The URL field allows you to define the HTTPS Endpoint that will send data to ACS.

If needed by the endpoint, two types of authentification method are available:

  • Basic authentification: enter your username/password information in the Request Header(s) field.

  • OAuth authentification: By clicking on the Use connection parameters defined in an external account, you can select an external account where the OAuth authentification is defined. For more information, refer to the External accounts section.

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

NOTE

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.

Message format
Example
Invoking API URL '%s'.

Invoking API URL 'https://example.com/api/v1/web-coupon?count=2'.

Retrying API URL '%s' due to %s in %d ms, attempt %d.

Retrying API URL 'https://example.com/api/v1/web-coupon?count=0' due to HTTP - 401 in 2364 ms, attempt 2.

Transferring content from '%s' (%s / %s).

Transferring content from 'https://example.com/api/v1/web-coupon?count=2' (1234 / 1234).

Using cached access token for provider ID '%s'.

Using cached access token for provider ID 'EXT25'. Note: EXT25 is the ID (or name) of the external account.

Fetched access token from server for provider ID '%s'.

Fetched access token from server for provider ID 'EXT25'. Note: EXT25 is the ID (or name) of the external account.

Refreshing OAuth access token due to error (HTTP: '%d').

Refreshing OAuth access token due to error (HTTP: '401').

Error refreshing OAuth access token (error: '%d').

Error refreshing OAuth access token (error: '404').

Failed to fetch the OAuth access token using the specified external account on attempt %d, retrying in %d ms.

Failed to fetch the OAuth access token using the specified external account on attempt 1, retrying in 1387 ms.

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 - A HTTP 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').

WKF-560278 - "Error initializing OAuth helper (error: '%d')" .

This error indicates that the activity could not initialize the internal OAuth2.0 helper facility, due to error in using the attributes configured in the external account to initialize the helper.

WKF-560279 - "HTTP header key is not allowed (header key: '%s')."

This warning (not error) message indicates that the OAuth 2.0 external account has been configured to add a credential as an HTTP header, but the header key used is not allowed because it is a reserved header key.

WKF-560280 - External account of '%s' ID cannot be found.

External account of 'EXT25' ID cannot be found. Note: This error indicates that the activity is configured to use an external account, which can no longer be found. This is most likely to happen when the account has been deleted from the DB, and as such not likely to happen in normal operating circumstances.

WKF-560281 - External account of '%s' ID is disabled.

External account of 'EXT25' ID is disabled. Note: This error indicates that the activity is configured to use an external account, but that account has been disabled (or marked inactive).

WKF-560282 - Protocol not supported.

This error indicates that the external account associated with the activity is not a OAuth2.0 external account. As such, this error is unlikely to happen unless there is some corruption or manual changes to the activity configuration.

WKF-560283 - Failed to fetch the OAuth access token.

Most common cause of this error is misconfiguration of the external account (for eg. using the external account without testing that the connection is successful). Might be possible that url/credentials on the external account are changed.

CRL-290199 - Cannot reach page at: %s.

This error message is shown on the external Accounts UI screen when setting it up for OAuth. It means that the URL for the external authorization server is either incorrect/changed/response from the server is Page not found.

CRL-290200 - Incomplete/Incorrect credentials.

This error message is shown on the external Accounts UI screen when setting it up for OAuth. This means that credentials are either incorrect or missing some other required credentials to connect to the auth server.

On this page