nocobase-app-plugin-workflow

Design, validate, invoke, and diagnose source-managed NocoBase 3 workflow definitions.

9|3|Updated Aug 14, 2026
One-click install
npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-workflow-nocobase
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: nocobase-app-plugin-workflow
Source: https://github.com/nocobase/nocobase3/tree/main/packages/plugins/app-plugin-workflow/skills/nocobase-app-plugin-workflow
Command: npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-workflow-nocobase

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Deciding whether business logic belongs in a durable workflow or plain typed code is hard, and authoring NocoBase 3 workflow DSL packages without knowing the exact contracts leads to invalid definitions, failed builds, and misdiagnosed runs. This Skill guides the full lifecycle of source-managed workflows so definitions, invocations, and diagnostics follow the actual plugin contracts. ## Core Features & Use Cases - Architecture decisions: Decide whether a business behavior belongs in Workflow, ordinary typed code, or a combination, based on durability, branching, and observability needs. - DSL authoring and validation: Author workflow.ts packages with Condition, Run, and Terminate instructions, input schemas, administrator parameters, and result contracts, then run the five-phase checker and Artifact build. - Invocation and management: Trigger workflows through workflowServiceToken, handle accepted/skipped receipts and event-key deduplication, and use the authenticated management API for enablement, parameters, and manual runs. - Execution diagnostics: Diagnose runs by status model, node attempts, payloads, and logs, and distinguish root causes such as module errors, input validation, or timeout aborts. - Use Case: A developer needs a quotation approval process that branches on a risk score and retains execution history. The Skill helps decide the Workflow/code boundary, author the quotation-decision package with run scripts, validate and build the Artifact, trigger it with an idempotent event key, and diagnose a failed node attempt. ## Quick Start Use the nocobase-app-plugin-workflow skill to decide whether my business process needs a NocoBase workflow and then author and validate the workflow package.

Frequently Asked Questions about nocobase-app-plugin-workflow

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a workflow in NocoBase 3?▼

Create a directory under the configured workflow source root (default server/workflows) containing workflow.ts that default-exports a const annotated WorkflowSourceAst from defineWorkflow(). Define inputSchema, parameters, and nodes using ConditionInstruction, RunInstruction, and TerminateInstruction, then run pnpm nocobase workflow check on the package.

When should I use a NocoBase workflow instead of plain code?▼

Use Workflow when the business needs a durable, inspectable process lifecycle with persisted state, branching history, timeouts, or event-key idempotency. Keep atomic validation, calculations, single-transaction mutations, and external integrations in ordinary typed services or run scripts.

How do I trigger a NocoBase workflow from business code?▼

Resolve workflowServiceToken from app.container and call trigger(workflowKey, input, options?). The key is the DSL package directory name, input must match the declared inputSchema, and the receipt is either accepted with an event key or skipped with a reason; execution is asynchronous.

Does the workflow check command validate run scripts?▼

No. The check command runs typecheck, evaluate, schema, semantic, and compile phases on workflow.ts only; it does not verify that config.module exists or that the named run export compiles. Validate run scripts with the application's own typecheck, tests, and server build.

Why does my workflow trigger return skipped?▼

A skipped receipt means the workflow key was not found or the current revision is disabled, and no run is created. Verify the directory-derived key, that a current revision exists, and enablement state; do not poll for a run after a skipped receipt.

Can I rerun a failed NocoBase workflow with the same event key?▼

No. Reusing an event key deduplicates the same business event and will not re-execute a confirmed failed run. Recovery requires a deliberately new invocation, an authorized manual run of a selected revision via the management API, or explicit compensation.