Custom Field Arrays of Data

Arrays of data can be stored within Custom Fields to provide an almost unlimited amount of storage.

Arrays of data can be useful for holding shopping basket contents, flight itineraries etc. and array elements can then be referenced within Email Templates using the Template Language.

Template Language Coding

Referencing array data stored in Custom Fields within Templates is possible through the use of the $json variable name.

For example, where Custom Field #1 stores the example data below 'first_name' of the 'customer' element could be referenced in Template Language coding using...

{?$json.contacts_data_1.customer.first_name?}

Array Data Format

Arrays of data can be stored within any Custom Field using the normal methods for updating User data (API, Imports and manually editing Users) by providing a serialised JSON string in place of the usual data.

When viewing Custom Fields through the User Edit screen, any fields that contain a correctly encoded JSON string will have a preview button next to it. Clicking this will bring up a human-readable view of the JSON data.

Example Array Data

The following is an example array in JSON format representing a customer record and order details:

{
    "customer": {
        "first_name": "Joe",
        "last_name": "Bloggs",
        "account": "CR024676"
    },
    "order": {
        "invoice": "AYD24367",
        "order_total": "134.99",
        "currency_symbol": "\u00a3",
        "delivery_date": "",
        "address": {
            "line_1": "10 Station Road",
            "line_2": "",
            "city": "Birmingham",
            "county": "West Midlands",
            "country": "UK",
            "postcode": "B1 2CD"
        },
        "items": [
            {
                "product_code": "340440",
                "description": "Mens 574 Sonic Trainers",
                "qty": 1,
                "net": "75.00"
            },
            {
                "product_code": "IF526",
                "description": "Racing Forecaster Mens Hoody Black",
                "qty": 1,
                "net": "59.99"
            }
        ]
    }
}

Array data is stored as JSON serialised objects. Data can either be in the form of associative or numerically indexed arrays - see notes on compatibility.

More information can be found on JSON, including links to supporting libraries across a variety of languages at json.org.

Debugging

If email tests aren't rendering as expected it is possible to write out the contents of arrays into the template itself to see the exact format the data has been stored in. This can be done using the |@json_encode modifier.

Using the example array above, if the data was stored in contacts_data_1, the contents can be output as below:

Usage

{?$json.contacts_data_1|@json_encode?}

Output

{"customer":{"first_name":"Joe","last_name":"Bloggs","account":"CR024676"},"order":{"invoice":"AYD24367","order_total":"134.99","currency_symbol":"\u00a3","delivery_date":"","address":{"line_1":"10 Station Road","line_2":"","city":"Birmingham","county":"West Midlands","country":"UK","postcode":"B1 2CD"},"items":[{"product_code":"340440","description":"Mens 574 Sonic Trainers","qty":1,"net":"75.00"},{"product_code":"IF526","description":"Racing Forecaster Mens Hoody Black","qty":1,"net":"59.99"}]}}

Compatibility Notes

When storing JSON encoded data, all key names should abide by the following rules:

  • A key name must start with a letter or underscore.
  • A key name cannot start with a number.
  • A key name can only contain alpha-numeric characters and underscores (A-z, 0-9 and _).
  • Key names are case-sensitive.

Any names that do no follow the above rules will not be accessible via the Template Language and may cause issues within other features such as Targeting and Automation.

Related Pages