Goal

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

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

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.

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

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

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

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

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.

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.

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

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

nocobase-workflow-manage

NPX Install

Tags

SKILL.md Content

Goal

Dependency Gate

Mandatory MCP Gate

Hard Rules

Orchestration Process

Planning Phase

Creating a New Workflow

Editing an Existing Workflow

Diagnosing a Failed Execution

Error Handling

Verification Checklist

Reference Index