novu-design-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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/
.

为任意Novu工作流设计规则——无论你是在仪表盘（无代码）中创建，还是使用

@novu/framework

通过代码创建。此处的决策（渠道、优先级、关键状态、摘要、条件）在两种方式下都是一致的；仅语法有所不同。

采用代码方式创建？请将此技能与
framework-integration/
结合使用，以完成
workflow(...)
、
step.*
、
controlSchema
和Bridge端点的设置。在仪表盘或通过Novu MCP创建？完成此处的设计后，请使用
dashboard-workflows/
填写步骤内容（主题、正文、
editorType
、标头、条件）。

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/

每当你需要确定工作流的形态时，都可以使用它：

"设计订单确认工作流"
"支付失败时应发送到哪些渠道？"
"将此通知设为关键通知"
"是否应对此进行摘要处理？"
"为离线订阅者添加备选方案"
"X场景适合哪种模板？"

请勿将其用于：触发现有工作流（

trigger-notification/

）、编写代码包装器（

framework-integration/

）或在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.

两个独立的设置项。大多数工作流都不会设置这两项。

设置项	取值	默认值	效果
`severity`	`LOW` / `MEDIUM` / `HIGH`	未设置	在收件箱中进行视觉优先级区分（颜色、高亮）；决定摘要跳过规则。
`critical`	`true` / `false`	`false`	绕过订阅者偏好设置，跳过摘要处理，无延迟，使用所有可用渠道。

经验法则：

大多数工作流无需设置
```
severity
```
。仅当需要视觉优先级区分时才设置。
```
HIGH
```
= "今日需处理"（支付失败、明日试用到期）。
```
critical: true
```
= "无论偏好如何都需送达"（账户暂停、安全警报、密码重置）。
```
critical: true
```
⇒ 自动跳过摘要处理，渠道立即发送通知。

查看

references/severity-and-critical.md

获取完整行为矩阵以及

readOnly

与

critical

的区别。

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.

仅使用这些指定的渠道。不要添加备选渠道，不要额外添加其他渠道。如果请求的渠道未在组织中配置，仍需添加，因为用户明确要求了该渠道。

"订单发货时发送推送通知" → 仅一个
push
步骤，无其他内容。

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.

从组织中已配置的渠道中选择，按以下优先级排序，最多选3个渠道：

In-App  >  Email  >  Chat  >  Push  >  SMS

渠道	使用场景	跳过场景
In-App	产品内内容的默认渠道。如果用户在你的产品内，务必包含此渠道。	收件人无法查看（密码重置、一次性验证码、注册前通知）
Email	收据、文档、异步沟通。In-App之后的默认备选渠道。	产品内纯对话式提醒
Chat	如果已配置且 `severity >= MEDIUM` 。面向运维和内部流程的Slack/Teams渠道。	营销类或低优先级提醒
Push	订阅者离线但需要立即知晓时的备选渠道。	订阅者在线（改用In-App）
SMS	最后手段。仅当其他渠道都无法使用时（真正的紧急情况、一次性验证码、合规要求）。	任何适合通过Email或Push发送的内容

查看

references/channel-selection.md

获取完整决策树。

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.

添加摘要步骤时，默认采用：

```
type: "regular"
```
回溯窗口：5分钟
摘要时间：1小时
键：
```
subscriberId
```
（对话式流程需添加
```
+threadId
```
）

跳过摘要处理的情况：

```
severity: HIGH
```
，或
```
critical: true
```

查看

references/digest-defaults.md

获取摘要键的组成方式和对话式流程示例。

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

根据订阅者是否在线调整路由：

状态	行为
在线	立即发送In-App通知。跳过Push。根据优先级延迟发送Email/Chat。
离线	使用Push或Chat吸引用户注意。

默认延迟时间：

B2B应用 → 下一个工作时段
B2C应用 → 约30分钟

“订阅者离线”的判定条件在两种方式下是一致的——查看

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

将用例与模板匹配并复制其结构。每个模板都指定了优先级、关键状态、可操作性和交互类型，以及步骤顺序。

#	用例	优先级	关键状态	备注
1	订单确认	无	false	摘要处理，In-App + Email + Push（仅离线时）
2	你的帖子收到评论	无	false	按 `subscriberId + threadId` 进行摘要处理
3	支付失败	HIGH	false	In-App + Chat + Email + Push（离线时）
4	账户暂停	HIGH	true	所有渠道，无视偏好设置，无摘要处理
5	忘记密码	无	true	仅Email + SMS，无In-App
6	试用明日到期	HIGH	false	In-App + Chat + Email + Push（离线时）
7	明确渠道请求	不适用	不适用	仅使用用户指定的渠道
8	Webhook / 外部API调用	可变	可变	在渠道步骤后添加 `step.http`
9	先获取数据再通知	可变	可变	先执行 `step.http` ；声明 `responseBodySchema`

完整的ASCII流程图 + 各模板元数据请查看

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.

条件决定步骤是否运行。可用于“仅当订阅者离线时发送”、“仅当In-App通知未被查看时发送邮件”等类似的备选场景。

仪表盘创建者编写JSON-Logic：

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

Framework创建者向步骤传递
```
skip: () => boolean
```
回调函数。

语义完全一致。查看

references/step-conditions.md

获取标准代码片段以及各作用域中可用的变量。

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> }}
```
.

不要默认设置优先级——除非确实需要视觉优先级区分，否则保持未设置状态。
critical: true
与
readOnly: true
不同——
```
readOnly
```
仅在偏好设置UI中隐藏工作流；
```
critical
```
在运行时绕过偏好设置和摘要处理。查看
```
references/severity-and-critical.md
```
。
当用户指定渠道时不要添加备选渠道——明确的渠道请求需严格执行。
用户未指定渠道时，渠道数量上限为3——渠道越多，用户越反感，而非覆盖范围越广。
不要将摘要处理与
critical: true
结合——关键工作流必须立即送达。摘要步骤会被自动跳过。
对话式流程的摘要键很重要——如果没有
```
+threadId
```
，帖子A和帖子B的评论会被归入同一摘要。
仅在离线时发送Push——向在线用户发送Push会与In-App提醒重复。
HTTP步骤需要
responseBodySchema
——没有它，下游步骤无法通过
```
{{ 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

渠道选择 — 完整决策树和各渠道指南
优先级与关键状态 — 行为矩阵、偏好设置与摘要处理的交互、
```
readOnly
```
与
```
critical
```
的区别
摘要默认设置 — 时间窗口、键、对话式摘要模式
步骤条件 — JSON-Logic代码片段和Framework的
```
skip
```
等效写法
工作流模板 — 9个参考流程，包含优先级/关键状态/交互表

另请参阅

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

```
dashboard-workflows/
```
— 为仪表盘或Novu MCP工作流编写步骤内容（主题、正文、
```
editorType
```
、标头、条件）
```
framework-integration/
```
— 在代码中实现这些设计（
```
workflow()
```
、
```
step.*
```
、
```
controlSchema
```
、Bridge）
```
manage-preferences/
```
—
```
critical
```
如何与订阅者级偏好设置交互
```
inbox-integration/
```
— 优先级如何在收件箱中视觉呈现
```
trigger-notification/
```
— 工作流设计完成后调用它