How Data Binding Works

Data binding allows you to bind an activity to data in a running journey. This process greatly simplifies how a marketer or developer dynamically connects data for each contact flowing through a journey. The syntax for data binding is based on the Mustache template language library.

Data binding lets you write expressions evaluated by the Journey Builder engine at runtime, when an activity executes for a contact. The inArguments and outArguments include these expressions. The system doesn't evaluate these expressions when saving, validating, or publishing a journey.

Data binding expressions are case-sensitive. Ensure that the expression exactly match your data extension name and field name.

The standard POST body to an Activity without Data Binding leaves the inArguments and outArguments empty.

While this call contains some useful information, it provides a limited approach. InArguments provide your Activity with information needed to handle internal decisions, update your data, or reach out to services your Custom Activity depends on. OutArguments contain the key and value pair for each field expected on the response body of the request. The following example uses Data Binding within the config.json:

Using Mustache syntax provides a similar experience to using personalization strings. However, data binding is limited to Contacts and Event Data for a journey for the supplied Contact.

To illustrate how Mustache syntax works, assume you use the following JSON data:

To bind the full name of the Contact, use Handlebars syntax.

Using Data Binding with Contact Builder provides a powerful set of data.

  • Contact.Key - The Journey Builder Engine requires this contact key value to provide the appropriate context.
  • InteractionDefaults.Email - Use this pattern to retrieve the default address of the given type for the specified Contact.
  • Contact.Default.[Twitter||Facebook||SMS] - Use this pattern to retrieve the default address (non-email) of the given type for the specified Contact.
  • Contact.Attribute.[FullyQualifiedAttributeName] - Use this pattern to retrieve the specified attribute from the Contact Builder. The fully qualified attribute names generally appear in the form of [AttributeSet Name].[AttributeName]. By default, the attribute set name from Contact Builder's Data Designer is the same as the data extension name. The attribute set name of a system-defined set may be different from the data extension name, so use the attribute set name from Contact Builder. (The attribute set name is different from the attribute group name.) Attribute sets and names can use special characters like spaces, but you must surround these values with double quotation marks. Example: Contact.Attribute."Product Orders"."Product Name"

Here are some examples based on the following data assumptions:

  • The contact opted-in for subscriptions

  • The contact subscribed with Email, Twitter and SMS channels as defaults using the following values:

  • Contact includes related data on an attribute set named Person (using the JSON data from above).

You may need to retrieve information from the running journey's context. An expression can also reference the outArguments from a prior activity in the current journey context using the following placeholder patterns:

  • Interaction.[ActivityCustomerKey].[OutArgumentName] - Uses a journey-unique Activity Customer Key and the Activity specifies the OutArgumentName value.
  • Context.IsTest - Returns true for a journey in Test Mode. Use this parameter when the Activity needs to act differently when running the journey as a test.
  • Context.PublicationId - Use the publication ID to associate the currently executing activity to a particular publication (version) of the journey.
  • Context.DefinitionId - Use the definition ID to associate the currently executing activity to a particular definition of the journey.
  • Context.DefinitionInstanceId - This key identifies the actual instance of a journey. Each time a contact runs through the engine, the engine creates a unique ID. Use this information to match logs.
  • Context.StartActivityKey - This key contains the starting key for the session associated with the activity. The key includes a blank value when starting a new activity. Coming off of a wait, this key contains the key of the wait activity.
  • Context.VersionNumber - This key retrieves the entire journey response body, from which you can pull the journey version number. See the Journey Spec for an example of the response body format.

You can reference an event within an expression (the incoming data associated with the entry event). Adhere to the following pattern when using data binding with events:

An activity can include many different data bound fields. The fields include Mustache expressions specified at journey design time. For instance, for an activity with a databound field expecting an email, the customer can specify {{InteractionDefaults.Email}}.

  • When processing a contact in a journey, the engine evaluates all expressions.
  • Once a journey publishes, and every subsequent hour, the system compiles each expression to ensure evaluation at runtime.
  • When the system can’t compile an expression, publish fails and the system disables the journey. These types of failures could happen if a customer renames or deletes a field or does anything to invalidate the expression.
  • The system compiles all expressions in memory during this hourly validation. This process allows the engine to cache all information needed to retrieve for a given journey, and it speeds up the replacement process of the Mustache placeholders. For example, you can combine all contact calls that can happen within this session of the journey into one contact service call.
  • The defaults property on the journey Object contains an ordered list of email expressions that determine which email address to use as the default, starting with the first expression.

Handlebars allows for complex ways of using placeholders. Use the fully qualified name approach for specifying placeholders to cut down on the change of ambiguation issues. The system checks the inner scope before the outer scope.

If there is non-alpha character, such as a space or a colon, in the attribute set or field name, use double quotation marks with Handlebars syntax.