Batch
Learn about batch node functionality within SuprSend workflows
Batch node aggregates multiple triggers into a single batch output to send one consolidated notification rather than sending notification for every user activity. Batching events are useful when a user needs to be notified about a lot of events happening at once but doesn’t need a notification for every single event within the batch. For example, if you have a product where users can interact with each other’s content and post 5 comments in 10 minutes. In this case, rather than sending 5 notifications, you can batch the events for 10 minutes and send one notification about the 5 comments that the user received.
How batching works
Opens batch window
When a workflow reaches the batch node, it opens a batch for given batch window.
Aggregates incoming triggers
When the batch window is open, all the workflows initiated for the recipient with the same workflow slug and batch key are aggregated in the batch. Batches are created unique for each recipient and batch key combination for that workflow.
Move to next workflow step once batch window is closed
After the batch window is closed, it will send one notification for each batch created in the batch window. Also, with retain batch events, you can limit the number of event data that should be retained in the batch for sending the notification. The output variable structure of a batch is different from the data in your event properties. Refer Using batch variables in templates to know more.
Batch Window
Batch window is the time for which batch should be open for. After receiving the first event, batch window opens and all the events coming in this interval will be accumulated. The next node is executed after the batch window is closed. There is a setting Flush first item immediately
which bypasses batch window and sends the first trigger immediately and accumulates the rest.
There are 3 types of window type: Fixed (fixed for all users), Dynamic (Passed in trigger payload), Relative (relative to a future timestamp, eg. 10 mins before task due time).
Batch Key
This is the property in your track event
call used for defining uniques batches of the events. By default, event will be batched per user. You can use batch key to create multiple batches per user. Batches are created for each unique distinct_id
and batch_key
combination. For instance, you can add post_id
as your batch key if you want to send separate notifications for comments on different linkedin posts.
Retain Batch Events
It will define the number of event data that will be included in your batch variable. You have the option to display either the first n events or the last n events in your batch output. By default, the first 10 events are included in your batch output variable once the batch window closes. You can customize the number of events to any value between 2 and 100.
Flush first item immediately
When this setting is enabled, the first trigger sends a notification immediately, while subsequent triggers are grouped into a batch.
Here, the batch is opened on receiving the first item irrespective of the flush setting. The only difference is, unlike a normal batch, the first item will not be included in batch events and will continue execution past the batch step.
The output structure of the first notification matches the batch structure, with $batched_events_count = 1
. You can use this count in your workflow or templates to customize content based on whether the notification is sent immediately or as part of a batch.
Example Use Case: Send anomaly alert with first notification sent at the occurrence of first error and next alert sent after 30 mins if there are further errors. These could be the template content for single vs batched trigger:
- First notification (sent immediately):
A new error encountered in your account - {{$batched_events.\\\\\\\[0\\\\\\\].error_message}}
- Batched notification (sent after grouping all errors from 2nd error onwards):
{{$batched_events_count}} errors occurred in your account in the last 30 mins - {{#each $batched_events}}{{error_message}}{{/each}}
Using Batch variables in templates
Batch output variable has 2 type of variables:
$batched_events
array : All the event properties corresponding to a batched event is appended to this array and can be used in the template in the array format. The number of event properties returned here is limited by retaining batch events.$batched_event_count
: This count represents the number of events in a batch and is utilized to render the batch count in a template. For instance, you might send a message like,Joe left 5 comments in the last 1 hour
where 5 corresponds to $batched_event_count.
📘 Please note that Retain batch events setting doesn’t impact the count, it just limits the number of event properties returned in $batched_events
array.
Let’s understand the batch variable structure with an example of task comments with below notification content.
Here is a list of events triggered in the batched window:
Output variable of the batch will have $batched_events_count
and $batched_events
array of all properties passed in the event payload as shown below:
This is how you’ll add the variable in your template to render the desired notification content.
You can also test this behaviour via Enable batching
option in Mock data button on template details page. Once enabled, you’ll start getting $batched_events\\\\\\\*
variable in auto suggestion on typing {{
in template editor. The variables in mock data will be treated as event properties and Event Count
will imitate the number of times this event will be triggered in the batch.
Transforming Batch Variable Output
There can be cases where you need to split the batch output variables into multiple arrays based on keys in your input data. For example, to send a message like You have got 5 comments and 3 likes on your post in the past 1 hour
where post and likes are interaction_type in your input payload. You can use data transform node and generate relevant variables using JSONNET editor to handle this usecase.
Let’s take below example. There are 3 post interactions, 2 comments and 1 like and this is your workflow trigger.
Without transformation, batch output will look like this:
We’ll add 3 variables in data transform node
comment_count
: to get the count of all interactions whereinteraction_type = comment
like_count
: to get the count of all interactions whereinteraction_type = like
all_comments
: to fetch all array objects whereinteraction type = comment
After data transform node, output variables will contain 3 additional keys generated above. You can use these variables in your template to send the desired message as You have got {{comment_count}} comments and {{like_count}} likes on your post in the past 1 hour.
.