Design Workflow

Design rules for any Novu workflow — independent of whether you author it in the Dashboard (no-code) or in code with

@novu/framework

. The decisions here (channels, severity, critical, digest, conditions) are the same on both surfaces; only the syntax differs.

Authoring in code? Pair this skill with
framework-integration/
for
workflow(...)
,
step.*
,
controlSchema
, and Bridge Endpoint setup. Authoring in the Dashboard or via the Novu MCP? After designing here, fill in step content (subject, body,
editorType
, headers, conditions) using
dashboard-workflows/
.

When to use this skill

Use it whenever you need to decide what a workflow should look like:

"Design an order-confirmation workflow"
"Which channels should I send for a payment failure?"
"Make this notification critical"
"Should this be digested?"
"Add a fallback for offline subscribers"
"What's the right template for X?"

Do not use it for: triggering an existing workflow (

trigger-notification/

), authoring code wrappers (

framework-integration/

), or rendering severity in the UI (

inbox-integration/

Severity & Critical

Two independent dials. Most workflows set neither.

Dial	Values	Default	Effect
`severity`	`LOW` / `MEDIUM` / `HIGH`	unset	Visual prioritization in the Inbox (color, glow); informs digest skip rules.
`critical`	`true` / `false`	`false`	Bypass subscriber preferences, skip digest, no delays, all available channels.

Rules of thumb:

Leave
```
severity
```
unset for most workflows. Only set it when visual prioritization is needed.
```
HIGH
```
= "deal with this today" (payment failed, trial expiring tomorrow).
```
critical: true
```
= "deliver regardless of preferences" (account suspended, security alert, password reset).
```
critical: true
```
⇒ digest is automatically skipped and channels deliver immediately.

See

references/severity-and-critical.md

for the full behavior matrix and the

readOnly

critical

distinction.

Channel Selection

If the user specified channels

Use only those channels. Do not add fallbacks. Do not add extras. If the requested channel isn't configured in the organization, add it anyway because the user explicitly asked for it.

"Send a push notification when the order ships" → one
push
step. Nothing else.

If the user did NOT specify channels

Pick from channels configured in the organization, in this priority order, up to 3 channels:

In-App  >  Email  >  Chat  >  Push  >  SMS

Channel	Use it for	Skip it when
In-App	Default for in-product content. Always include if the user is in your product.	The recipient can't see it (password reset, OTP, pre-signup)
Email	Receipts, documentation, async communication. Default fallback after In-App.	Pure conversational pings inside the product
Chat	If configured AND `severity >= MEDIUM` . Slack/Teams for ops & internal flows.	Marketing or low-severity nudges
Push	Fallback when subscriber is offline but needs immediate awareness.	Subscriber is online (use In-App instead)
SMS	Last resort. Only when no other channel works (true emergencies, OTP, regulatory).	Anything that fits in Email or Push

See

references/channel-selection.md

for the full decision tree.

Digest Defaults

When you add a digest step, default to:

```
type: "regular"
```
look-back window: 5 minutes
digest time: 1 hour
key:
```
subscriberId
```
(and
```
+threadId
```
for conversational flows)

Skip the digest when:

```
severity: HIGH
```
, or
```
critical: true
```

See

references/digest-defaults.md

for digest key composition and conversational examples.

User-State Logic

Adapt routing based on whether the subscriber is online:

State	Behavior
Online	Send In-App immediately. Skip Push. Delay Email/Chat based on severity.
Offline	Use Push or Chat to get attention.

Default delays:

B2B apps → next work hour
B2C apps → ~30 minutes

The condition for "subscriber offline" is the same on both surfaces — see

references/step-conditions.md

Workflow Templates

Match the use case to a template and copy its shape. Each template specifies severity, critical, actionable, and interaction type, plus the step ordering.

#	Use case	Severity	Critical	Notes
1	Order Confirmation	none	false	Digested, In-App + Email + Push (offline only)
2	Comment on Your Post	none	false	Digested by `subscriberId + threadId`
3	Payment Failed	HIGH	false	In-App + Chat + Email + Push (offline)
4	Account Suspended	HIGH	true	All channels, no preferences, no digest
5	Forgot Password	none	true	Email + SMS only, no In-App
6	Trial Expiring Tomorrow	HIGH	false	In-App + Chat + Email + Push (offline)
7	Explicit Channel Request	n/a	n/a	Use only the channels the user specified
8	Webhook / External API Call	varies	varies	Add `step.http` after channel steps
9	Fetch Data then Notify	varies	varies	`step.http` first; declare `responseBodySchema`

Full ASCII flows + per-template metadata in

references/workflow-templates.md

Step Conditions

Conditions decide whether a step runs. Use them for "send only if subscriber is offline", "send email only if In-App wasn't seen", and similar fallbacks.

Dashboard authors write JSON-Logic:

{ "==": [{ "var": "subscriber.isOnline" }, "false"] }

Framework authors pass a
```
skip: () => boolean
```
callback to the step.

The semantics are identical. See

references/step-conditions.md

for the canonical snippets and the variables available in each scope.

Common Pitfalls

Don't set severity by default — leave it unset unless you actually need visual prioritization.
critical: true
is not the same as
readOnly: true
—
```
readOnly
```
only hides the workflow from the Preferences UI;
```
critical
```
bypasses preferences and digests at runtime. See
```
references/severity-and-critical.md
```
.
Don't add fallbacks when the user named the channels — explicit channel requests are exact.
Cap the channel count at 3 when the user didn't specify channels. More channels = more annoyance, not more reach.
Don't combine digest with
critical: true
— critical workflows must deliver immediately. The digest step is auto-skipped.
Digest key matters for conversational flows — without
```
+threadId
```
, a comment on Post A and a comment on Post B end up in the same digest.
Push only when offline — sending push to an online user duplicates the In-App alert.
HTTP step needs
responseBodySchema
— without it, downstream steps can't read response properties via
```
{{ steps.<id>.<prop> }}
```
.

References

Channel Selection — full decision tree and per-channel guidance
Severity & Critical — behavior matrix, preference & digest interactions,
```
readOnly
```
vs
```
critical
```
Digest Defaults — windows, keys, conversational digest patterns
Step Conditions — JSON-Logic snippets and Framework
```
skip
```
equivalents
Workflow Templates — the 9 reference flows with severity/critical/interaction tables

novu-design-workflow

NPX Install

Tags

SKILL.md Content