Get Started with the Journey Specification

The Journey Specification is a structured JSON representation of a single journey in Journey Builder. It allows Journey Builder to scale to meet the massive enterprise demands that true, event-driven, one-to-one cloud applications offer.

The Journey Spec is used via REST API requests to the Marketing Cloud Interaction Service.

The largest benefit of the Journey Spec is that it provides developers with a structural syntax to programmatically compose journeys. Some other benefits include:

  • Makes the Marketing Cloud Interaction Service available for customers and developers to create journeys completely via REST API requests.
  • Provides constructs for composing extremely complex journeys in Journey Builder without the need of a browser.
  • Designed to be somewhat readable by humans (assuming a basic understanding of JSON formatting), with textual references for statuses and options instead of cryptic database enumerations.
  • Allows developers to quickly use CRUD (Create, Read, Update, and Delete) operations in conjunction with journeys.
  • Allows for the Journey Builder APIs to have a constant, portable definition format for journeys, which can easily be shared in support and social.
  • Allows Journey Builder engineers to rapidly create a robust ecosystem of Journey Builder functionality.
  • Guarantees that all changes to a journey are atomic, preventing partial data corruption.

The Journey Spec is represented using a JSON serialized string. Journey, event, activity, and goals are the four (4) primary object properites the specification makes available:

  • Journey: (sometimes called interaction) The core object, without this object you are unable to create any other properties of a journey using the spec.
  • Event: This is called a trigger in the Journey Spec and determines entry settings for the journey.
  • Activity: Instead of separating Waits, Activities, Exits, and so on, the Journey Spec calls all of these activities. Outcomes are used to map one activity to the next activity in the flow of a journey, once the current activity has completed.
  • Goal: This object is how Journey Builder can provide information on the success of a journey.

Using the primary objects of the Journey Spec, you can create extremely complex journeys using just a text editor and a REST client.

Important considerations about the Journey Spec hierarchy

  • The trigger contains the eventDefinitionKey of the entry event that will trigger this journey. There can only be a single entry event.
  • There is no start activity. The first activity is the activity which has no preceding activity. It is generally the first one in the list of activities.
  • There is no end activity. Endings or exits are denoted by an outcome with a next value of null. Contacts will be ejected from the journey when they reach that outcome.
  • Goal is unique, and is not an activity (primarily due to the fact that it may or may not cause a person to exit the journey).
  • Journey keys must be unique within a MID.
  • Activity keys must be unique within a journey.
  • Arguments may contain expressions to be processed by the engine using Data Binding. Use the Mustache template language to write these expressions. These expressions can access data that are available in the journey context (e.g. contact data) or data that are the output of a previous activity.
  • Outcomes will be an array of outcome objects on the activity. The outcome object(s) will denote the next activity/activities.

Journey Object

The journey object has the following properties:

  • id [read-only] - A unique identifier for this journey that is generated and assigned by the journey API during creation.
  • version [read-only] - This number denotes the iteration of this particular journey.
  • key [required] - The customer key (also a unique identifier within the MID) for this journey. This is defined by the developer and can be used to address this journey in most API calls.
  • name [required] - The display name used in the Journey Builder UI for this journey, this will be visible to everyone who logs into your Marketing Cloud account. This can also be used as a filter with the nameOrDescription Query param.
  • description - The human readable description of this journey that informs others of purpose. This can also be used as a filter with the nameOrDescription Query param.
  • workflowApiVersion [required] - This number represents the current release of the Journey Spec that the Journey Builder APIs will expect in order to understand how to parse and properly respond to your API requests. This specification defines version "1.0".
  • goals - This is an array of goals containing a single object. (We currently only support a single goal per journey.)
  • triggers - This is an array of triggers containing a single object. (We currently only support a single trigger per journey.)
  • defaults - This object contains an ordered list of email expressions used to determine which email address to use as the default, starting with the first expression.
  • activities - This is an array that includes all the activities of the journey.

Example Journey Object

Event Object

An event (called trigger in the Journey Spec) is an object on the journey Object that determines the entry settings for the journey. The recommended type for events fired via the API and for custom events is Event, which uses the contact model and an optional expression to determine when contacts should enter the journey.

The Event object has the following properties:

  • key - The MID-unique key used to identify this entry Event.

  • name - The display name for this Entry Event which will be shown in the Journey Builder UI.

  • type - The type of Entry Event this is (only value currently supported is event.

  • eventDefinitionKey - This is the key used to filter appropriate events into filter for evaluation on entry into the journey. Do not include a period in the event definition key.

  • arguments - This object represents the arguments this Event expects to be passed for use at runtime.

  • configurationArguments - This object represents the arguments this particular event expects to be passed for use both at publish and runtime.

    • criteria - This is an XML string that represents the contact filter critieria.

Activity Objects

Activity Objects represent almost every object type in the Journey Spec. The only objects that are not technically considered an activity are goals and events.

Supported Activity types:

The Activity object has the following properties:

  • id - This is the Marketing Cloud-provided unique ID for this particular activity.

  • key - This is the customer key (journey-unique) for this particular activity.

  • name - This is the display name for this activity, it will be shown in the Journey Builder UI.

  • type - This property defines what type of activity this is. The expected input for each activity must be passed as an argument to operate correctly.

  • outcomes - This is an array of 'outcome' objects (the following represents a single, generic outcome object).

    • key - This is the customer key (journey-Unique) for this particular outcome.
    • next - This value is a string which must map to a valid, journey-unique activity key.

  • arguments - This is an object which represents the arguments this particular activity expects to be passed for use at runtime. Each activity type has its own unique argument parameters which are expected (see below).

  • configurationArguments - This is an object which represents the arguments this particular activity expects to be passed for use both at publish and runtime. Each activity type has its own unique argument parameters which are expected (see below).

Activity Outcome

The outcome objects provide some context for decision activities in determining which outcome they should select from the array. For example, on a RandomSplit the arguments are used to determine the likelihood that each contact has of traversing each outcome. Here is an example of an activity outcome:

Goal Object

The goal object is used to measure effectiveness of an associated journey. Goals are only evaluated via their criteria / Filter XML.

The goal object has the following properties:

  • name - The display name for this goal.

  • key - The customer key for this goal.

  • type - The type of goal this is (only option currently is ContactEvent).

  • description - The description for this goal, will be displayed in the Journey Builder user interface.

  • metaData - A set of properties which are not specific to the definition or execution of this Event, but are related to it.

    • conversionUnit - This value is used for deterministic evaluations of the goal, can be either "percentage" or "wholenumber".
    • conversionValue - Based on the conversionUnit this is the metric Journey Builder uses to determine if the goal has been satisfied.

Using the above JSON, we could make a PUT request to Journey Builder and update our original journey with this new goal.