nocobase-workflow-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goal

目标

Orchestrate NocoBase workflows end-to-end through NocoBase MCP tools: design trigger logic, build node chains, manage versions, and inspect execution results.

通过NocoBase MCP工具端到端编排NocoBase工作流：设计触发器逻辑、构建节点链、管理版本以及检查执行结果。

Dependency Gate

依赖门槛

Related helper skills:

nocobase-mcp-setup

nocobase-data-modeling

Check whether NocoBase MCP tools are available before planning write operations.
If MCP is not configured, guide the user to use
```
nocobase-mcp-setup
```
.
If MCP tools return authentication errors such as
```
Auth required
```
, stop and ask the user to complete MCP authentication or refresh the MCP connection before continuing.
Data modeling skill may be used to understand related collections and fields when configuring workflow triggers and nodes.

Mandatory MCP Gate

强制MCP准入检查

Confirm the NocoBase MCP server is reachable and authenticated before attempting workflow operations. Do not proceed with any workflow mutation until the MCP server exposes the relevant workflow endpoints.

在尝试进行工作流操作前，确认NocoBase MCP服务器可访问且已完成认证。在MCP服务器暴露相关工作流端点之前，不要进行任何工作流变更操作。

Hard Rules

硬性规则

Never create a workflow with
enabled: true
— always create with
```
enabled: false
```
, complete all trigger and node configuration, then enable.
Never edit a frozen version directly — if
```
versionStats.executed > 0
```
, create a new revision first via
```
workflows:revision
```
. The
```
filter
```
parameter must include
```
{"key":"<key>"}
```
(the workflow's
```
key
```
) to ensure the new version belongs to the same workflow; omitting
```
key
```
will create an independent copy instead. Use the returned new
```
id
```
for all subsequent operations; discard the old
```
id
```
.
Never use an empty
filter
— update and destroy nodes require
```
filter
```
with at least one condition. Confirm the filter is non-empty before calling the API.
Always chain nodes via
upstreamId
— every node (except the first) must reference its upstream node. Do not skip or leave
```
upstreamId
```
unset.
Never create nodes concurrently — node creation calls must be executed one at a time, sequentially. Wait for the previous node to be fully created before creating the next one, because the server adjusts internal link relationships during each creation. Batch/parallel node creation is not supported.
Always wrap filter in
$and
or
$or
— the root of any filter object must be a condition group. See Common Conventions - filter.
Always reference node results by
key
, not
id
— use
```
{{$jobsMapByNodeKey.<nodeKey>.<path>}}
```
where
```
nodeKey
```
is the node's
```
key
```
property (a short random string). Never use the numeric
```
id
```
, never invent a key — always read the actual
```
key
```
from the node record after creating it. See Common Conventions - Variable Expressions.
Always verify after mutation — after creating, updating, or deleting a workflow or node, read back the result to confirm the change took effect.
Do not auto-enable without user confirmation — always ask the user before setting
```
enabled: true
```
.

严禁创建
enabled: true
的工作流——始终以
```
enabled: false
```
状态创建，完成所有触发器和节点配置后再启用。
严禁直接编辑已冻结版本——如果
```
versionStats.executed > 0
```
，先通过
```
workflows:revision
```
创建新修订版本。
```
filter
```
参数必须包含
```
{"key":"<key>"}
```
（工作流的
```
key
```
），确保新版本属于同一个工作流；省略
```
key
```
会创建独立副本而非修订版本。后续所有操作都使用返回的新
```
id
```
，丢弃旧
```
id
```
。
严禁使用空
filter
——更新和删除节点时要求
```
filter
```
至少包含一个条件，调用API前确认filter非空。
始终通过
upstreamId
串联节点——除第一个节点外，每个节点都必须引用其上游节点，不得跳过或不设置
```
upstreamId
```
。
严禁并发创建节点——节点创建调用必须逐个顺序执行，前一个节点完全创建完成后再创建下一个，因为服务器会在每次创建过程中调整内部链接关系，不支持批量/并行创建节点。
始终将filter包裹在
$and
或
$or
中——任何filter对象的根层级必须是条件组，参考通用约定 - filter。
始终通过
key
而非
id
引用节点结果——使用
```
{{$jobsMapByNodeKey.<nodeKey>.<path>}}
```
，其中
```
nodeKey
```
是节点的
```
key
```
属性（短随机字符串）。严禁使用数字
```
id
```
，严禁自行编造key，始终在节点创建完成后从节点记录中读取实际的
```
key
```
，参考通用约定 - 变量表达式。
变更后始终验证——创建、更新或删除工作流/节点后，回读结果确认变更已生效。
未经用户确认不得自动启用——设置
```
enabled: true
```
前必须征得用户同意。

Orchestration Process

编排流程

Planning Phase

规划阶段

Before making any MCP calls, clarify with the user:

Trigger type — what event starts the workflow? → see Trigger Reference
Node chain — what processing steps are needed? → see Node Reference
Execution mode — synchronous or async? See sync vs async
Key parameters — collection names, filter conditions, field mappings, variable expressions

Summarize the complete plan in natural language and confirm with the user before making any MCP calls.

Then map the requested action to the corresponding MCP-exposed endpoint:

Workflow CRUD and revisions →
```
workflows:*
```

Node operations →

workflows/<workflowId>/nodes:create

and

flow_nodes:*

Execution inspection →
```
executions:*
```
Job detail inspection →
```
jobs:get
```

在发起任何MCP调用前，和用户明确以下内容：

触发器类型——什么事件会启动工作流？→ 参考触发器参考
节点链——需要哪些处理步骤？→ 参考节点参考
执行模式——同步还是异步？参考同步vs异步
核心参数——集合名称、过滤条件、字段映射、变量表达式

在发起任何MCP调用前，用自然语言总结完整方案并和用户确认。

然后将请求的操作映射到对应的MCP暴露端点：

工作流CRUD和版本管理 →
```
workflows:*
```

节点操作 →

workflows/<workflowId>/nodes:create

和

flow_nodes:*

执行结果检查 →
```
executions:*
```
任务详情检查 →
```
jobs:get
```

Creating a New Workflow

创建新工作流

Create workflow →

POST /api/workflows:create

with

type

title

sync

enabled: false

Configure trigger →

POST /api/workflows:update?filterByTk=<id>

with

config

Add nodes in order →

POST /api/workflows/<workflowId>/nodes:create

for each node, chaining via

upstreamId

Configure each node →

POST /api/flow_nodes:update?filterByTk=<nodeId>

with

config

Verify → read back the workflow with nodes to confirm trigger config, node count, order, and each node's config are correct

Enable workflow → confirm with the user, then

POST /api/workflows:update?filterByTk=<id>

with

enabled: true

Test / verify →

POST /api/workflows:execute?filterByTk=<id>&autoRevision=1

创建工作流 → 调用

POST /api/workflows:create

，传入

type

、

title

、

sync

、

enabled: false

配置触发器 → 调用

POST /api/workflows:update?filterByTk=<id>

，传入

config

按顺序添加节点 → 为每个节点调用
```
POST /api/workflows/<workflowId>/nodes:create
```
，通过
```
upstreamId
```
串联

配置每个节点 → 调用

POST /api/flow_nodes:update?filterByTk=<nodeId>

，传入

config

验证 → 回读带节点的工作流，确认触发器配置、节点数量、顺序以及每个节点的配置正确

启用工作流 → 和用户确认后，调用

POST /api/workflows:update?filterByTk=<id>

，传入

enabled: true

测试/验证 → 调用

POST /api/workflows:execute?filterByTk=<id>&autoRevision=1

Editing an Existing Workflow

编辑现有工作流

Fetch workflow with nodes and version stats →

GET /api/workflows:get?filterByTk=<id>&appends[]=nodes&appends[]=versionStats

Check if version is frozen (
```
versionStats.executed > 0
```
)
- Yes → create a new revision first:
```
POST /api/workflows:revision?filterByTk=<id>&filter={"key":"<key>"}
```
  The
```
key
```
  is the workflow's
```
key
```
  field (obtained from the workflow record in step 1). It must be provided to create a revision of the same workflow. Omitting
```
key
```
  creates an independent copy instead. Use the returned new
```
id
```
  for all subsequent operations. Discard the old
```
id
```
  .
- No → proceed directly

Edit as needed:

Update trigger config →

POST /api/workflows:update?filterByTk=<id>

with

config

Add node →

POST /api/workflows/<workflowId>/nodes:create

Update node config →

POST /api/flow_nodes:update?filterByTk=<nodeId>

Delete node →

POST /api/flow_nodes:destroy?filterByTk=<nodeId>

Move node →

POST /api/flow_nodes:move?filterByTk=<nodeId>

with body

{ "values": { "upstreamId": <targetId>, "branchIndex": null } }

(

upstreamId: null

moves to the front;

branchIndex

specifies a branch,

null

for the main chain)

Copy node →

POST /api/flow_nodes:duplicate?filterByTk=<nodeId>

with body

{ "values": { "upstreamId": <targetId>, "branchIndex": null } }

Verify → read back modified nodes to confirm changes took effect

Enable (if needed) → confirm with the user, then

POST /api/workflows:update?filterByTk=<id>

with

enabled: true

获取工作流及节点、版本统计信息 → 调用

GET /api/workflows:get?filterByTk=<id>&appends[]=nodes&appends[]=versionStats

检查版本是否已冻结（
```
versionStats.executed > 0
```
）
- 是 → 先创建新修订版本：调用
```
POST /api/workflows:revision?filterByTk=<id>&filter={"key":"<key>"}
```
```
key
```
  是工作流的
```
key
```
  字段（从步骤1的工作流记录中获取），必须传入该参数才能创建同一工作流的修订版本，省略
```
key
```
  会创建独立副本。后续所有操作都使用返回的新
```
id
```
  ，丢弃旧
```
id
```
  。
- 否 → 直接继续操作

按需编辑：

更新触发器配置 → 调用

POST /api/workflows:update?filterByTk=<id>

，传入

config

添加节点 → 调用

POST /api/workflows/<workflowId>/nodes:create

更新节点配置 → 调用

POST /api/flow_nodes:update?filterByTk=<nodeId>

，传入

config

删除节点 → 调用

POST /api/flow_nodes:destroy?filterByTk=<nodeId>

移动节点 → 调用

POST /api/flow_nodes:move?filterByTk=<nodeId>

，请求体为

{ "values": { "upstreamId": <targetId>, "branchIndex": null } }

（

upstreamId: null

表示移动到最前面；

branchIndex

指定分支，

null

表示主链）

复制节点 → 调用

POST /api/flow_nodes:duplicate?filterByTk=<nodeId>

，请求体为

{ "values": { "upstreamId": <targetId>, "branchIndex": null } }

验证 → 回读修改后的节点，确认变更已生效
启用（如有需要） → 和用户确认后，调用
```
POST /api/workflows:update?filterByTk=<id>
```
，传入
```
enabled: true
```

Diagnosing a Failed Execution

诊断执行失败

List executions to find the failed one:

GET /api/executions:list?filter[workflowId]=<id>&sort=-id

Get execution detail with jobs (exclude result to reduce size):

GET /api/executions:get?filterByTk=<execId>&appends[]=jobs&appends[]=workflow.nodes&except[]=jobs.result

Find the failed job — look for
```
job.status
```
values of
```
-1
```
(FAILED),
```
-2
```
(ERROR), or
```
-3
```
(ABORTED)
Get full job detail to see the error:
```
GET /api/jobs:get?filterByTk=<jobId>
```
Inspect
```
result
```
for the error message or output that caused the failure.
Fix the issue (update node config or create a new revision if version is frozen), then re-execute.

列出执行记录找到失败的条目：调用

GET /api/executions:list?filter[workflowId]=<id>&sort=-id

获取执行详情和关联任务（排除结果以减少体积）：调用

GET /api/executions:get?filterByTk=<execId>&appends[]=jobs&appends[]=workflow.nodes&except[]=jobs.result

找到失败的任务——查找
```
job.status
```
值为
```
-1
```
（失败）、
```
-2
```
（错误）或
```
-3
```
（中止）的记录
获取完整任务详情查看错误：调用
```
GET /api/jobs:get?filterByTk=<jobId>
```
检查
```
result
```
字段获取导致失败的错误信息或输出。
修复问题（更新节点配置，若版本已冻结则创建新修订版本），然后重新执行。

Error Handling

错误处理

MCP returns 400/422: Read the error message carefully. Common causes: invalid node
```
type
```
, missing required config fields, referencing a non-existent
```
upstreamId
```
. Fix the parameter and retry.
MCP returns 401/403: Stop all operations. Ask the user to re-authenticate or refresh the MCP connection.
Node creation fails: Do not continue adding downstream nodes. Fix or remove the failed node first, then resume.
Revision creation fails: The original workflow may be in an inconsistent state. Re-fetch the workflow to verify its current state before retrying.

MCP返回400/422：仔细阅读错误信息，常见原因：无效的节点
```
type
```
、缺少必填配置字段、引用不存在的
```
upstreamId
```
。修复参数后重试。
MCP返回401/403：停止所有操作，要求用户重新认证或刷新MCP连接。
节点创建失败：不要继续添加下游节点，先修复或移除失败的节点后再恢复操作。
修订版本创建失败：原始工作流可能处于不一致状态，重试前重新获取工作流确认其当前状态。

Verification Checklist

验证检查清单

After completing any workflow operation, verify:

Workflow exists and has the correct
```
type
```
,
```
title
```
, and
```
sync
```
mode
Trigger
```
config
```
matches the planned configuration
Node count and order match the plan (check
```
upstreamId
```
chain)
Each node's
```
type
```
and
```
config
```
are correct
Filter conditions are non-empty where required (update, destroy nodes)
```
enabled
```
status matches the intended state
For edits on frozen versions: the new revision
```
id
```
is being used, not the old one

完成任何工作流操作后，验证以下内容：

工作流存在，且
```
type
```
、
```
title
```
和
```
sync
```
模式正确
触发器
```
config
```
与规划的配置一致
节点数量和顺序与规划一致（检查
```
upstreamId
```
链路）
每个节点的
```
type
```
和
```
config
```
正确
要求非空的过滤条件均非空（更新、删除节点场景）
```
enabled
```
状态与预期一致
若编辑的是已冻结版本：正在使用新修订版本的
```
id
```
，而非旧id

Reference Index

参考索引

Topic	File
Common conventions (collection, filter format)	references/conventions/index.md
Architecture, data model & concepts	references/modeling/index.md
Triggers	references/triggers/index.md
Nodes	references/nodes/index.md
Endpoint mapping used through MCP	references/http-api/index.md

主题	文件
通用约定（集合、filter格式）	references/conventions/index.md
架构、数据模型与概念	references/modeling/index.md
触发器	references/triggers/index.md
节点	references/nodes/index.md
MCP使用的端点映射	references/http-api/index.md