External API external-api
Description 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.
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 from-beta-to-ga
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.
Limitations and guardrails 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.
Configuration 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 Campaign Standard will communicate with.
If needed by the endpoint, two types of authentication method are available:
-
Basic authentication: enter your username/password information in the Request Header(s) section.
-
OAuth authentication: By clicking on the Use connection parameters defined in an external account in an external account, you can select an external account where the OAuth authentication 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
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.
Testing
To test out the External API functionality with a simple test endpoint, you can use Postman Echo: https://docs.postman-echo.com.
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.
Errors
These log messages are used to log information about unexpected error conditions, that can eventually cause the workflow activity to fail.
API URL could not be parsed (error: '-2010').
Note: This error is logged when the API URL fails validation rules.
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]').
Failed to create request body JSON. Error when adding 'params'.
Failed to create request body JSON. Error when adding 'data'.
HTTP header key is bad (header key: '%s').
Note: This error is logged when the custom header key fails validation according to RFC
HTTP header value is bad (header value: '%s').
Note: This error is logged when the custom header value fails validation according to RFC
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.
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').