Batching

NOTE

This feature is currently in Public Beta and is under active development. Please note that the API may change and that this feature is not covered under the Enterprise SLA.

Batching is a feature of Automations that aggregates events, consolidating what would have been multiple notifications into a single update. This dramatically reduces spam and improves the probability that notifications are read. The functionality can operate based on any of the three criteria:

1. Period of inactivity: If no events occur in a defined span (for instance, an hour), then all events prior to the last notification are bundled into a single notification.
2. Maximum event count: Notifications are held back until a certain count of events, say 100, have accumulated. These events are then summarized in a single notification.
3. Maximum wait time: All events that would have initiated notifications within a predefined duration, such as a 24-hour period, are summarized into a single notification.

Batching is possible across channels (eg. email, SMS, chat, in-app inbox, push) and providers (eg. Twilio, Sendgrid, email SMTP, Slack, MS Teams, WeChat).

Example Use Cases

Article Performance Summarization

Imagine an article published on a news website that generates an event for each view, comment, and share. Instead of sending a notification for each individual event, these events can be batched within an automation. Once the initial surge of activity has subsided or the maximum wait time is reached, the batch compiles view count, top comments, and share count data. This information is then forwarded to the next step, allowing the author to receive a summarized report via email.

Data Warehouse Analytics

A company dealing with large amounts of data may produce a varying number of reports with different completion times. An event is generated upon the completion of each report. With batching, these reports can be grouped together and sent in a single email once all the reports for the day are generated.

Social Media Engagement

Consider a user who creates a popular post that receives numerous likes within minutes of being published. Instead of sending a notification for each like, batching can be employed to notify the user once the post hasn't received new likes for a few minutes. For example, "Your post received 17 likes."

Creating A Batch

To create a batch, use the "Add to Batch" action, then click anywhere within the batch node to open the editor within the sidebar.

Configuring A Batch

To configure a batch, click on the batch node to open an editor in the sidebar.

Batches have the following configuration options:

Parameter	Description
Wait Period	Defines the period of inactivity before a batch is considered complete. If no events are received within this time frame, the batch will be finalized and sent to the next step.
Max Wait	Defines the maximum amount of time to wait before finalizing the batch. If this time frame is reached, the batch will immediately complete, even if an event had been received within the "wait period."
Retain Items	Defines the number of items to be retained and sent along with the batch. Retention does not affect the tracked count. If retain is set to 10 items and 15 items are received, the passed count will be 15, and the passed items will be 10. Options: First 10, Last 10, Highest 10 (requires Sort Key), Lowest 10 (requires Sort Key).
Sort Key	Required when Highest or Lowest is selected for Retain Items. Defines the key of the data object to be used to determine item ordering. For example, if sort key is set to upvotes, and the automation is invoked with { "data": { "upvotes": 5 } }, 5 will be the value used to determine the order and position of the event in the items array.
Max Items	(Optional) Defines the maximum number of events to include in a batch before completion. When a batch has received this number of events, it will immediately finalize and send the batch to the next step.
Category Key	(Optional) Allows events to be grouped by categories. See Working with Categories for more details.

Invoking a Batch

When a batch node is invoked, Courier checks if there is an ongoing batch run for that node. If not, Courier creates one, marks the automation as pending, and does not proceed to the next step until the batch is complete.

If there is an existing batch run, Courier will add the data object for that run to the existing batch and terminate / complete the automation run. Any steps connected to the batch will not be executed. This means the nodes following a batch node will only be executed once per batch run.

Once a batch is complete, the data objects from each invocation are aggregated and passed onto the next step

{
  batch: {
    // The number of events received for this category, may be different than items.length
    // depending on item retention configuration.
    count: number;
    // The an array of the data objects of each automation added to this batch.
    items: any[];
  }
}

For example if a batch automation was invoked 3 times with the following values

// Invoke 1
{
  data: {
    like_from: "Drew";
  }
}

// Invoke 2
{
  data: {
    like_from: "Alex";
  }
}

// Invoke 3
{
  data: {
    like_from: "Abby";
  }
}

The steps following the batch node would be provided this data object:

{
  batch: {
    count: 3,
    items: [
      { like_from: "Drew" },
      { like_from: "Alex" },
      { like_from: "Abby" },
    ]
  }
}

This data can be accessed from a notification template using variable syntax. Because fields from the data object are spread globally onto the template, there refs.data is omitted from within a template:

Accessing batch data from a notification template

Working With Categories

It is possible to group events by category in a batch run when the Category Key is set to a dynamic value such as refs.data.category_key. In such a case, the batch is aggregated by category:

Accessing batch data from a notification template

For example, in the batch node, Category Key is set to refs.data.category_key. Each time the automation is invoked, a category_key is supplied.

Given the following invocations:

// Invoke 1
{
  data: {
    category_key: "likes",
    like_from: "Drew"
  }
}

// Invoke 2
{
  data: {
    category_key: "likes",
    like_from: "Alex"
  }
}

// Invoke 3
{
data: {
  category_key: "comments",
  comment: "Excellent post!"
  }
}

The data object passed to the steps following the batch node would be:

{
  likes: {
    count: 2,
    items: [
      { like_from: "Drew" },
      { like_from: "Alex" }
    ],
  },
  comments: {
    count: 1,
    items: [{ comment: "Excellent post!" }],
  },
}