Overview

  • Automations provides a toolset to design and implement complex notification workflows with one API.

  • An Automation is a schema definition that enables the power to easily express complex use cases such as digests, delayed messages, scheduled messages, sending messages to an ad hoc list, and escalation messages.

  • At a high level, an Automation schema is composed of two parts, Context Properties and Steps.

{
"automation": {
"recipient": "abcd-1234-wxyz-6789",
"data": {
"title": "Weekly Digest"
}"steps": [
{
"action": "fetch-data",
"webhook": {
"url": "https://main.app/digest"
},
"merge_strategy": "replace"
},
{
"action": "send",
"template": "WEEKLY-DIGEST",
"profile": {
"email": "test@courier.com"
}
}
]
}
}

Automation Concepts

Automation Run Context

  • Run Context refers to a set of special properties, that are used to invoke and automation. Context properties are available to all steps at Step Execution Time (aka runtime).

  • Run Context can be defined as part of an Ad Hoc Automation or passed as a first class object to an Automation Template.

  • Run Context is composed of the following properties:

    • brand

      • type: string

      • description: A unique identifier that represents the brand that should be used for rendering the notification.

    • data

      • type: object

      • description: An object that includes any data you want to pass to a message template or accessor type. The data will populate the corresponding template variables.

    • profile

      • type: object

      • description: an object that includes any key-value pairs required by your chosen Integrations (see our Provider Documentation for the requirements for each Integration.) If profile information is included in the request and that information already exists in the profile for the recipientId, that information will be merged.

    • template

      • type: string

      • description: A unique identifier that can be mapped to an individual Notification. This could be the "Notification ID” on Notification detail pages (see the Notifications page in the Courier app) or a custom string mapped to the event in settings.

    • recipient

      • type: string

      • description: A unique identifier associated with the recipient of the delivered message, which can optionally map to a Courier managed profile.

Steps

  • Steps are the fundamental building blocks of an Automation schema. Automation steps are a set of discrete actions, which are used together to implement complex messaging workflows.

Automation Schema

  • It is possible to define an Automation Schema in three ways:

  1. Ad Hoc

  2. Automation template

  3. Jsonnet template (advanced)

{
"automation": {
"recipient": "abcd-1234-wxyz-6789",
"data": {
"title": "Weekly Digest"
}"steps": [
{
"action": "fetch-data",
"webhook": {
"url": "https://main.app/digest"
},
"merge_strategy": "replace"
},
{
"action": "send",
"template": "WEEKLY-DIGEST",
"profile": {
"email": "test@courier.com"
}
}
]
}
}
  • Automation templates

    • By default, an Automation Template is a JSON schema definition of the following format:

    • {
      cancelation_token: "",
      steps: [

      ]
      }
    • Run Context is passed in the API request body as a first-class object, and its values are referenced at the step level by using Accessor Types.

    • For more detail see "Building and invoking an automation template"

  • Jsonnet Template (Advanced)

Invoking an Automation

  • Executing or Invoking an Automation produces an Automation Run or an instance of your specific Automation Schema definition

Step Context (message status for send steps only)

Step References

  • You can define a step level reference, by adding a ref property to a step definition.

  • In the conditionals of subsequent steps, you can then reference metadata about the sent message using the word "refs."

  • For example, if you only want to send a followup message if that message hasn't been opened yet, you can define the following automation run:

{
"automation": {
"steps": [
{
"action": "send",
"template": "OUTREACH",
"ref": "outreach"
},
{
"action": "delay",
"delayFor": "24 hours"
},
{
"action": "send",
"template": "FOLLOWUP",
"ref": "followup",
"if": "refs.outreach.status < MessageStatus.Opened"
},

]
}
}

Accessor Types

  • an Accessor Type is a way to resolve dynamic data at the step level

    • For Example, if Run Context is defined as:

    {
    "data": {
    "user": {
    "id": "1234-abcd-5678-wxyz"
    }
    }
    }

    • Then we could access that value at the step level using an accessor:

    {
    "automation": {
    "steps": [
    {
    "action": "send",
    "recipient": {
    "$ref": "data.user.id"
    }
    }
    ]
    }
    }

Conditionals

  • For each type of step, you can define conditions that will determine if a step is executed or not.

  • Adding an if property to a step makes it a conditional step.

  • The value of the if property should be a valid javascript expression that evaluates to a boolean.

  • For example, the following send step has a conditional expression that should evaluate to true. Therefore, the step will be executed.

{
"template": "TEST",
"recipient": "abcd-1234-efgh-5678",
"profile": {
"email": "test@gmail.com"
},
"data": {
"foo": "send-it"
},
"automation": {
"steps": [
{
"action": "send",
"if": "data.foo === 'send-it'"
}
]
}
}

Merge Strategy

Some automation steps require or include a merge strategy. In the following definitions, A = data defined in the step; B = existing data.

  • Replace: overwrites all properties in B from A; remove properties in B that do not exist in A

  • Overwrite: overwrite all properties in B from A

  • Soft-merge: only overwrite properties in B from A that do not yet exist in B

  • None: No changes to B if B already exists; else B = A

Did this answer your question?