External data sources

External data sources allow you to import custom real-time information from your own systems into Engage. This data can then be accessed and used when creating email send-outs in the email design studio.

For this to work the following is needed:

A public REST API endpoint
The endpoint accessible by a GET method
A JSON payload being returned
API authorization (optional)

External data will be fetched for each send-out batch in Engage and it may differ from contact to contact based on their marketing group. It cannot be used for retrieving personal contact data.

Configuration of external data sources is done in the Configure Engage area of your Engage UI.

Finding the Configure Engage area

Caution

You'll need to have configurator permissions for your Engage account to access the configuration area. To get these permissions, contact your Voyado team.

In the Engage front-end, navigate to Administration and then select Configure Engage:

This will take you from Engage to the configuration area.

Configuration

Here are the settings in the configuration of an external data source:

Name: This is the name that will be shown in the email design studio, allowing this data source to be selected there and the data from it to be used.

Unique ID: The internal name of the data source (lower case with underscore). This must be unique. An error will be shown if you try to save an external data source using a name that's already in use by another data source.

URL: This is the URL to the endpoint that returns the JSON data of the data source. The URL can be static or include parameters defined by {name}, as shown in the second example here. The parameters specified in the URL must be defined in the input schema (see below).

https://yourdomain.com/api-endpoint

https://yourdomain.com/api-endpoint/{Site}/?id={ProductIds}

Authorization: If you need to use an API to access the URL, choose "API key" here.

Header key: Enter a header key (if using one).

Value: Enter the API key value (if using one).

Cache time in seconds: How long Engage will cache the response. Enter 0 here if you don't need it to be cached.

There are three fields concerning JSON schema:

Input JSON schema: These are the values that will be displayed in the email design studio when you select this external data source. The properties shown here ("Numberof", "Range", "Sortorder" etc.) must match those in the output JSON for this data source. The required properties are defined at the bottom. Example:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "Site": {
        "title": "Website language",
            "type": "string"
        },
        "Numberof": {
            "title": "Number of products",
            "description": "AAAA",
            "type": "integer",
            "minimum": 1,
            "maximum": 5
        },
        "Range": {
            "title": "Range",
            "type": "number",
            "minimum": 0.1,
            "maximum": 9.9
        },
        "Sortorder": {
            "title": "Sort order",
            "enum": [
                "lowestprice",
                "highestprice"
            ],
            "type": [
                "string"
            ]
        },
        "Productids": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    },
    "required": [
        "Productids", 
        "Sortorder"
    ]
}

Data type	In the URL	In design studio
string	String	String input
integer	integer string	Number input
number	Number as string	Number input
enum	Enum as string	Single select
array	Comma separated strings	Multi string input

In the case of the JSON given above, the design studio would show the following in the UI (but with empty values in the fields):

Output JSON schema: This JSON informs the system of the form of the payload that is expected from the URL you've configured. The properties listed here can then be used in your email layout for personalization, repeaters and display conditions. Example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "productList": {
      "title": "Product List",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNumber": {
            "title": "Article number",
            "type": "string",
          },
          "imageUrl": {
            "title": "Image url",
            "type": "string",
          },
          "link": {
            "title": "Link url",
            "type": "string",
          },
          "name": {
            "title": "Product title",
            "type": "string",
          },
          "leftinstock": {
            "title": "Number in stock",
            "type": "integer",
            "description": "Short description of the product"
          },
          "releasedate": {
            "title": "Release date",
            "type": "string",
            "format": "date",
          },
          "oncampaign": {
            "title": "Ongoing campaign",
            "type": "boolean",
          },
       },
        "required": [
          "itemNumber",
          "imageUrl",
          "link",
          "name"
        ]
      }
    }
  }
}

Sample JSON payload: Mostly as reference, you can add an example payload here.

Warning

Be careful with required properties. If any of them are missing in the payload, the data will not be valid according to the schema and will not be not sent to the design studio.

Data shown in design studio

The properties from the Output JSON schema can be used in your email layout in various ways:

For personalization: For example, you could add a personalized field for "leftinstock" and one for "link" to a text in an email since these are properties returned from the data source.