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.

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 vs 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

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:

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.

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

1. Don't set severity by default — leave it unset unless you actually need visual prioritization.
2. 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.
3. Don't add fallbacks when the user named the channels — explicit channel requests are exact.
4. Cap the channel count at 3 when the user didn't specify channels. More channels = more annoyance, not more reach.
5. Don't combine digest with critical: true — critical workflows must deliver immediately. The digest step is auto-skipped.
6. 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.
7. Push only when offline — sending push to an online user duplicates the In-App alert.
8. 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

See Also

• dashboard-workflows/ — author step content (subject, body, editorType, headers, conditions) for Dashboard or Novu MCP workflows
• framework-integration/ — implement these designs in code (workflow(), step.*, controlSchema, Bridge)
• manage-preferences/ — how critical interacts with subscriber-level preferences
• inbox-integration/ — how severity surfaces visually in the Inbox
• trigger-notification/ — invoking a workflow once it's designed