Digest Engine

The digest engine collects multiple trigger events, aggregates them into a single message, and delivers that new payload to the next workflow step. This becomes useful when a user would otherwise receive a large number of notifications, and you want to avoid over-notifying. When you use a Digest action step, Novu automatically batches the incoming trigger events based on the subscriberId and an optional digestKey that can be added to control the digest logic of the events.

Digest action step

After adding a digest step to a workflow, each node that will be below the digest node will be only triggered once in the specified digest interval. You can decide to send messages before adding a digest node and they will be triggered in real-time.

Digest configuration

Digest key

If specified, the digest engine will group the events based on the digestKey and subscriberId, otherwise the digest engine will group the events based only on the subscriberId.

The digest key might come useful when you want a particular subscriber to get events grouped on a custom field. For example when an actor likes the user's post, you might want to digest based on the post_id key.

Time interval

The time interval determines how long the digest engine will wait before sending the message once created. You can specify the amount and the unit that best suits your needs.

In the image below, 5 is the interval amount, and mins is the interval unit. Interval units can be sec(s), min(s), hour(s), or day(s).

Digest strategy types

The strategy which Novu should use to handle the digest step. More details on available strategies below.

Novu allows you to define different digest strategies depending on the actual use-case you are trying to achieve. At this point we allow you to select from 2 strategies:

• Regular
• Look-back
• Scheduled

Let's explore them in detail:

Regular strategy

In regular strategy, a digest will always be created for the specified window time. Which means that from the first event trigger, if no active digest exists for this subscriber, one will be created and the user will receive the message only when the digest window time is reached.

Look-back strategy

In the Look-Back strategy, before creating a digest, Novu will check if a message was sent to the user in the Look-back period. If a message was sent, a digest will be created. Otherwise, a message will be sent directly to the user and the digest creation will be skipped.

Look-back digest has two intervals, digest interval and look-back window. First, it checks if any event is triggered within the past look-back window, only then a digest is created for the digest interval. If not, the event is considered non-digest and workflow execution continues to the next step.

Example

Let's set the digest interval as 20 minutes and the look-back interval as 15 minutes.

If we trigger the first event. Since it is the first event and there was no event triggered in the past 15 minutes (look-back interval), this event will send a message immediately (without digest). Now, if we trigger a second event within 15 minutes range, then a new digest will be created with this second event. From now on, for the next 20 minutes (digest interval), all triggers will be digested, and after 20 minutes, the workflow will carry forward to the next step with digested events as a payload.

Scheduled digest

Digest incoming events for the specified time. Once that time threshold since the first event has passed, proceed to the next workflow step.

Available timeframes:

• Minutes
• Hours
• Daily
• Weekly

Consuming digested events

The digest step collects and groups multiple events over time. Once digested, the results can be used directly in your notification templates to create clear and concise summaries, such as daily digests or batch notifications.

Novu provides built-in variables that expose the results of the digest step. These variables can be referenced in your templates to display totals, format summaries, or present grouped event data using LiquidJS filters.

Digest variables

Digest variables can be used to reference the list of events and their count, making it possible to create dynamic content inside your templates based on the actual events processed during the digest window.

steps.digest-step.events

The steps.digest-step.events variable is an array that contains all the events collected by the digest step. Each item in the array represents a digested event, including the payload with which the workflow was triggered.

You can loop through it to build dynamic message lists, such as comment summaries or blog post digests, and use it with LiquidJS filters.

New posts published: {{steps.digest-step.events | toSentence:'payload.title', 2, 'more'}}

If two events were collected, the rendered message would be:

New posts published: Scaling Node.js Apps, and Designing for Accessibility

If three or more events were collected, the rendered message would be:

New posts published: Scaling Node.js Apps, and Designing for Accessibility, and more.

steps.digest-step.eventCount

The steps.digest-step.eventCount variable holds the total number of events collected during the digest step window. It is an integer value and can be used directly or passed into LiquidJS filters like pluralize to generate grammatically correct summaries.

You have {{steps.digest-step.eventCount | pluralize: "new comment"}}.

If one event was collected, then the rendered message would be:

You have 1 new comment.

If two events were collected, then the rendered message would be:

You have 2 new comments.

Digest template variables

Digest template variables are designed to simplify how you represent digested event data in user-facing messages. They wrap digest variables and LiquidJS filters to output preformatted summaries with minimal effort.

steps.digest-step.countSummary

The countSummary variable returns a sentence fragment summarizing the total number of digested events with correct pluralization.

This variable is built on top of:

• steps.digest-step.eventCount
• The LiquidJS pluralize filter

Internally, countSummary uses the event count to apply plural logic. To use countSummary in the editor, select it from the variables dropdown. This will automatically insert the variable like this:

You have {{steps.digest-step.eventCount | pluralize: 'notification'}}

For example, if the digest collected five events, then the output would be:

You have 5 notifications

If only one event was collected:

you have 1 notification

steps.digest-step.sentenceSummary

The sentenceSummary variable returns a sentence-style string listing key items from the digested events array, such as a list of names, and gracefully handles formatting depending on the number of items present.

This variable is built on top of:

• steps.digest-step.events
• The LiquidJS toSentence filter

You can configure the toSentence filter by passing:

• A key path to extract from each item (for example, payload.name). This is a required argument.
• The number of items to display before collapsing (for example, 3)
• The suffix to use for remaining items (for example, "others")

Internally, sentenceSummary uses the events array to generate the sentence. To use sentenceSummary in the editor, select it from the variables dropdown. This automatically inserts the variable as shown:

{{steps.digest-step.events | toSentence:'payload.name', 3, 'others'}} replied to your post.

If the events contain names "Radek", "Dima", and five more users, then the result would be:

Radek, Dima, and 5 others replied to your post.

If there are only two events:

Radek and Dima replied to your post.

These variable allows for dynamic personalization without writing custom iteration logic in your template.

Email editor digest block

The digest block is available in the email editor when working with workflows that include a digest step. It loops over the events collected by your digest step and displays them in your email content, handling both layout and repetition automatically.

When you add a digest block to your email template:

• It automatically inserts a repeat block that loops over steps.digest-step.events, with the maximum number of iterations defaulting to five.
• Inside this loop, you define the structure once (for example, how each comment or notification looks), and it repeats for every event.
• Inside the loop, you can also use the special alias variable current to reference the item currently being processed (for example, current.payload.name).
• The block also supports rendering a summary using the steps.digest-step.eventCount variable, typically with the pluralize LiquidJS filter.

You don’t need to write any code manually. The Email Editor handles the looping logic for you. Simply drag the digest block into your message and customize the layout visually using the available variables.

Frequently Asked Questions

If scheduled digest is set for 9:00 AM daily then will the digest be sent at 9:00 AM every day without any event triggered?"

If scheduled digest is sent for 9:00 daily, then novu will collect all events triggered between 9:00 AM today till 9:00 AM tomorrow and send the digest at 9:00 AM tomorrow. This process is repeated daily. If there is no any event triggered between 9:00 AM today and 9:00 AM tomorrow, then no digest will be sent.

What is the difference between Regular and Scheduled Digest set to 1 Hour?

Both digests are same in this case.

If digest step fails, will the workflow continue to the next step?

No, workflow execution will stop immediately if the digest step fails due to an error.