Extracting the data from your feed

This section explains how individual data items can be extracted from the data block fetched by the feed.

Data items can be added on the feed settings page here:

Each data item has a name and a mapping script:

The name will be used later to specify which data goes where in the Email Design System.

The mapping script uses the Liquid templating language. In the simplest case this can be used to extract data. In more advanced use cases data can be reformatted or logic can be used to make decisions on content based on the data.

Data types and how to reference them

The notation used to pull data from a feed depends on the data type selected, as follows:

Json and XML data is available as a liquid object. HTML data can be extracted using special filters

Extracting JSON or XML Data

JSON and XML data are both accessed as objects in liquid, so to get a piece of content from a JSON Feed the liquid will look something like:

#{{json.something.item.somethingelse[0].thing }}

Whereas for XML the liquid will be of the form:

#{{xml.something.item.somethingelse[0].thing }}

It’s easier to write the liquid code if we can see the data structure. To do this go to the Test tab and open the JSON tree in the Response section.

Note that XML feeds will also show as a JSON tree.

Click this to open the JSON tree:

Example

This example is from the (publically available) TicketMaster feed and contains details of an event:

Simple Reference

The name of the event is at the top level of the JSON tree:

It can be referenced as json.name: #{{json.name}}

This can then be verified by looking at the test tab:

It’s also worth noting that text can be added before/after the Lliquid that pulls the value in:

Which looks like this in the test tab:

You can also use Liquid filters in value, for example #{{ json.name | upcase }} , which outputs this:

Nested Reference

Looking again at the JSON tree, we can see that it starts with a { . Lower down the tree, sales is lso followed by a { . This means that this is a block of json within the main block. This can be referenced as json.sales .

If we put #{{json.sales}} as our data item, we will get the content of that block in JSON format as our value:

{"public":{"startDateTime":"2018-09-14T15:00:00Z","startTBD":false,"endDateTime":"2019-01-01T03:30:00Z"},"presales":[{"startDateTime":"2018-09-12T15:00:00Z","endDateTime":"2018-09-14T03:00:00Z","name":"Live Nation Mobile App Presale","description":"Download the Live Nation iPhone App now to access Live Nation Mobile App Presales. Browse, search, and discover….

In this format, the data in the block isn't too useful. However, we can use the next levels of Liquid to pull out data.

In this example, #{{json.sales.public}} pulls out: {"startDateTime":"2018-09-14T15:00:00Z","startTBD":false,"endDateTime":"2019-01-01T03:30:00Z"}

We can go deeper than this, like so: #{{json.sales.public.startDateTime}} which will get the start time. We can also apply a filter to display the date and time in a specific format: #{{json.sales.public.startDateTime | date: "%a, %b %d %Y" }} . You can read more about the date filter on Shopify's website.

Objects and Arrays

So far we have been looking at blocks which start with ‘{‘, these are called objects. They take the form of keys and values. The key is the name of the piece of data, and it forms a pair with the value. In this block the keys are ‘name’, and ‘statecode’ and the values are ‘Tennessee’ and ‘TN’:

{ "name": "Tennessee" "stateCode": "TN" }

The value can, in turn, be another block. Consider the following example:

{ "name": "Taxi For Email" "details": { location: "Location”, email: "[e-mail]" } }

Here the value of ‘details’ is an object, which itself has the keys ‘location’ and email.

Blocks which start with ‘[‘ are not objects; they are arrays. Arrays are not the same as objects. Here is an example of an array:

[ "item 1", "item 2", "item 3"]

An array is a list of values. There are no keys.

For technical reasons, it is quite common to see arrays containing a single block of data in feeds. So it is common to have to get the first element out of an array:

{ results: [ { "title": "The BFG" }] }

We can dig in to get the title as follows:

To pull the title from the above array, you can use the code #{{json.results.first.title}} . The first keyword is used in Liquid to get the first item in the array. You can also switch this for a number. The equivalent to above is: #{{json.results[0].title}} .

With this square bracket notation, any element can be extracted from an array.

In the Ticket Master feed an array of images is given. The first one is images[0] , the next is images[1] and so on. To reference the url of each of the images the following code could be used:

#{{json.images[0].url}}#{{json.images[1].url}}

In data items you can use any liquid filters to add more control to the content you pull from the feed into your emails. For example, removing whitespace, stripping HTML or replacing characters.

Find out more about these filters here: https://shopify.github.io/liquid/basics/introduction/