Get Started with the Journey Specification

The Journey Specification is a structured JSON representation of a single journey in Journey Builder. The Journey Spec is used via REST API requests to the Marketing Cloud Engagement interaction service. The Journey spec provides developers with a structural syntax to programmatically compose journeys. It also allows Journey Builder engineers to rapidly create a robust ecosystem of Journey Builder functionality. Importantly, the Journey Spec guarantees that all changes to a journey are atomic, which prevents 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.

  • 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.

The journey object has the following properties:

  • id - A unique identifier for this journey that is generated and assigned by the journey API during creation. Read-only.
  • version - This number denotes the iteration of this particular journey. Read-only.
  • 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 value is visible to every user of your Marketing Cloud Engagement account. You can also use this value as a filter with the nameOrDescription query parameter.
  • description - A human readable description of this journey that informs others of purpose. You can also use this value as a filter with the nameOrDescription query parameter.
  • workflowApiVersion - Required. Represents the current release of the Journey Spec.
  • goals - An array of goals containing a single object. Journeys only support one goal.
  • triggers - An array of triggers containing a single object. Journeys only support one trigger.
  • defaults - An object that contains an ordered list of email expressions used to determine which email address to use as the default.
  • activities - An array that includes all the activities of the journey.

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 key used to identify the entry event.
  • name - The display name for the entry event.
  • type - The type of entry event. The only supported value is event.
  • eventDefinitionKey - 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 - Represents the arguments this event expects to be passed. This property is intended to be used at runtime.
  • configurationArguments - Represents the arguments this particular event expects to be passed. This property is intended to be used at publish and runtime.
    • criteria - An XML string that represents the contact filter critieria.

Activity Objects represent nearly every object type in the Journey Spec, with the exceptions of goals and events.

The Activity object has the following properties:

  • id - The unique ID for the activity.
  • key - The unique customer key for the activity.
  • name - The display name for this activity.
  • type - Defines the activity type. The expected input for each activity must be passed as an argument to operate correctly.
  • outcomes - An array of outcome objects.
    • key - The unique customer key for the outcome.
    • next - A string that maps to a valid journey activity key.
  • arguments - An object that represents the arguments that the activity expects to be passed at runtime. Each activity type requires a different set of parameters.
  • configurationArguments - An object that represents the arguments that the activity expects to be passed at publish and runtime. Each activity type requires a different set of parameters.

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:

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.