External Content is a powerful tool in SAP Emarsys that enables the use of externally available data to create customized experiences. It supports the integration of external data into campaigns to achieve improved personalization.
External Content uses API calls to interact with endpoints and retrieve external data when systems send emails, web, in-app campaigns, or SMS messages with personalization tokens. The API returns JSON replies in a specific format, including data for predetermined response fields. External Content then uses values from specified reference fields as keys to select which external values to use for individual contacts.
SAP Emarsys sends an API request to the client's endpoint through the External Content feature.
Then the client's API responds with the external data that SAP Emarsys uses for personalized content.
External Content Benefits
External Content is beneficial in several scenarios:
Offer a solution when the RDS doesn’t support the database or when establishing connections needs intensive resources.
Use existing data processing logic that is essential for the business strategy alongside SAP Emarsys capabilities.
Offer a time-sensitive solution for linking SAP Emarsys with data sources.
Note
Visit the Help Portal for more information about:
External Content Configuration
The most important elements to understand before starting the configuration:
| External Content Connection | The basic unit of External Content personalization to specify the API endpoint for the requests sent from SAP Emarsys and define the reference and response fields. |
| Reference fields | SAP Emarsys uses reference fields to filter the data and to match it to contacts. External Content sends the values corresponding to these key fields in API requests. |
| Response fields | Response fields have the data that the system inserts into the messages. The response fields send back the data needed for personalization in the API response. |
| Personalization preset | The personalization preset refers to the External Content connection used. This configuration defines the available reference fields in the personalization token. In the preset, use every reference field for the chosen External Content connection. |
| Personalization token | The main use of the token is to specify a single response field from the response fields of an External Content connection. The system inserts this specified field into the messages at the token's location. |
Before starting:
Several presets can use the same External Content connection.
Use the same preset for various tokens when applying the same reference fields. Create a separate token for each response field that needs insertion into a campaign.
Setting up External Content.
Setting up a preset with reference fields for personalization.
Creating a token based on a preset.
The following table offers an overview of the relationship between reference fields, response fields, connections, presets, and tokens.
| External Content Connection | Defines:
|
| Personalization Preset | Uses:
|
| Personalization Token | Uses:
|
Depending on the data used, different personalization scenarios need different numbers of reference fields and different personalization token settings.
Keep a minimal number of External Content connections for easier organization.
Preparation:
While planning External Content connections, consider these points:
Use connections to differentiate among different API endpoints.
Set up various External Content connections for the same endpoint, each with a different set of reference fields.
These steps help make the integration and configuration of External Content in SAP Emarsys effective for specific needs.
Hint
Set up the External Content:
Navigate to Content > External Content to configure the External Content connection and list all existing connections.
Choose a descriptive name that shows the purpose of the connection. Personalization tokens use this name.
Offer the API URL the External Content asks for, and check that it's valid. Example: https://customer.com/api/personal-image-generator.
Select the authentication method from the following options and enter the necessary credentials:
Basic HTTP authentication: Specify the username and password for the client’s API.
OAuth2: Supports the OAuth2 client credential grant.
Enter these parameters:
URL to ask for an access token
Client ID
Client Secret
Scope (optional): This scope limits the data types available to SAP Emarsys
Reference fields connect contact-specific data to the SAP Emarsys database. Make sure that each field includes a value from the data and specifies its use during preset creation.
Indicate which JSON fields appear in the response. Use their content for personalization.
Offer valid database values for testing. Click 'Test' to check the connection and debug using request and response details. When developing the API, include error messages in the response.
Click 'Save' to store the connection and start a test.
External Content Tokens
External Content tokens personalize messages using external data, such as data from a website. The location of the data doesn't affect the process. Store data in a database or manage it with an application, but present it to SAP Emarsys through an API in the advised format, using information from a non-SAP site.
To personalize with External Content, configure and preset the External Content connection. Click ‘Create Token’ to open a window that allows the selection of the token type for creation.
Create an External Content preset:
In the Create Token page, click 'New' in the External Content preset line to open the 'Create External Content Preset' window.
Assign a descriptive name to the External Content preset. It’s necessary to mention this name when choosing the preset for each token.
Choose the External Content connection. Previously defined reference fields appear under 'Set Parameters.'
Edit the Type and Value of available parameters. Each type influences the personalization with External Content. Choose one of the following types:
Contact Field: Match the reference field to an SAP Emarsys contact database field. This process aligns the correct value with the right recipient during personalization.
External Event: Use data from the JSON file of an External Event to define the personalization token, aiming to tailor content to specific event details.
Constant: Enter a value from data sources to filter. For example, if the database includes all seasons but focuses on ‘spring,’ set the constant to ‘spring.’ This method guarantees receiving the correct data.
Confirm each parameter with the checkmark icon and click ‘Continue’ to finish. Then, create the External Content personalization token.
Create an External Content token:
Assign a descriptive token name for easy identification on the token setup page.
Choose a category for the token. Tokens can belong to various categories. Create a new category. Check the 'Create Category' for more details.
Choose the previously created External Content data preset. Click 'Edit' to make changes, or create a new preset if the existing one is unsuitable.
Select the response field from the External Content connection within the preset selected to populate the token.
Verify the SAP Emarsys Scripting Language code under the settings. Copy the code directly into the campaign's content for single use. For regular use, place it in the HTML source of the email template or the Content Block's source for web or in-app campaigns.
Choose the specific item from the array using the item index.
Check the box to prevent sending the message if the personalization token fails to populate.
Include fallback text to show when the field value isn't available. Using fallback text and needing the field for sending can't happen simultaneously.
Specify formatting details for the token.
Note
Use the following format: {{ external_content.name(reference_field1, reference_field2)[index].response_field }}.
The list index begins at ‘0’ for the first item. ‘1’ stands for the second item, ‘2’ the third, and so forth. Use this system to select values when an API call returns several results.
Override the display settings at the campaign level when necessary.
External Content tokens easily pull response data into a campaign by using them as a form of personalization.
Visit this page for more information about the SAP Emarsys Scripting Language (ESL).
Lesson Summary
External Content overview: External Content retrieves real-time external data through API requests during message sends. It supports dynamic personalization in emails, web, in-app, and SMS campaigns.
Configuration and setup: This section defines External Content connections by specifying endpoints, reference fields, and response fields. Use test values to validate connections and store them for use in tokens.
Presets and tokens: Create presets to organize reference fields and link them to personalization tokens. Each token pulls one response field, including formatting, fallback, and validation settings.
Supported authentication methods: External Content supports Basic HTTP and OAuth2 authentication. Offer necessary credentials and parameters to access external APIs securely.
Token usage and personalization: Tokens insert external data into content using Emarsys Scripting Language. Place them directly in HTML templates or use them across various channels for consistent personalization.