Navigating Data in a Data Graph

Before you read this section, review the concepts in Understanding Data Graphs in Marketing Cloud Next.

With Handlebars, it’s common to use dot notation to access nested fields in a JSON object. In Marketing Cloud Engagement, you can use the get helper function as an alternative to dot notation. By using the get function, you can filter and sort objects, which isn't possible with dot notation.

The get function uses a simple syntax:

For the collection parameter, specify the object or array that contains the data you want to retrieve. For the indexOrKey parameter, specify the numerical index (zero-indexed) for arrays or the name of the target field or object.

For example, assume that the data in your data graph resembles this JSON object.

When you write Handlebars code that uses the get helper function, it’s helpful to start from the inside and work outward. When you use data from the data graph, the first step is to return the root data graph (get @root "$dataGraph"). Use the returned data as the first argument in the outer get function, and then specify the field to return from that data (in this case, ssot__FirstName__c) as the second argument. For example, to return the individual's first name, which is found in the ssot__FirstName__c field in the first level of the object, use this code.

Handlebars includes the #with helper, which defines a context area. This helper is useful when you want to access multiple objects or properties that are nested several levels deep in a data object.

For example, if you know that you want to refer to several fields in the ssot__Individual__dlm array from the preceding section, you can create an alias to the object. This example shows how to associate the first object in the ssot__Individual__dlm array to the alias Individual and then use properties from that object in the HTML body of a message.

Using aliases makes your template code easier to understand and can prevent errors that result from traversing complex objects.

The filter helper function has this syntax:

For the list parameter, specify the object that contains the data to filter. For the fieldName parameter, specify the field to filter on. For the next two parameters, specify the filter criteria. Finally, for the filterAs parameter, specify the data type to use in the filter.

This example uses the sample JSON object from the preceding section. The code uses nested get functions. The innermost get function returns the root data graph object. The get function outside of that returns the content of the IndividualIdentityLink__dlm object in the data graph. From that object, the filter function returns all data in which the value of the ssot__DataSourceObjectId__c is a string that equals "Contact".

The function returns an object that matches the filter criteria.

The sort helper function has this syntax:

For the list parameter, specify the object that contains the data to filter. For the fieldName parameter, specify the field to sort on. For sortOrder, specify whether to sort in ascending (asc) or descending (desc) order. Finally, for sortAs, specify the data type to use in the sort operation.

This example uses the same sample JSON object from the preceding section and builds on the filter example.

This code example uses line breaks and indentation to improve readability. This example is valid, but with Handlebars it’s more common for a section of code such as this to be combined onto one line.

Working from the inside out, this code example completes these steps:

  1. Returns the root data graph (get @root "$dataGraph").
  2. From the root data graph, returns the content of the IndividualIdentityLink__dlm object.
  3. From the IndividualIdentityLink__dlm object, returns the object for which the value of the ssot__DataSourceObjectId__c property is a string that equals "Contact".
  4. From the filtered object, returns the contents of the BookStoreProfile__dlm object.
  5. From the BookStoreProfile__dlm object, returns the contents of the BookStore__dlm object.
  6. From the BookStore__dlm object, returns the contents of the BookStoreEvent__dlm object sorted in ascending date order by the EventDate__c property.

The code returns the list of objects from the BookStoreEvent__dlm array, sorted by date from earliest to latest.