Tutorial: Create a workflow from zero

This tutorial starts with no pre-built intake scaffold. You will author a workflow manually. Replace yourteam with your account slug.

Prerequisites

• workflow.manage permission or account owner. (The product seeds a workflow_admin role with this permission on some teams.)
• At least one form schema and (optionally) one data entity you can attach to steps—create them first under /home/yourteam/admin/forms and /home/yourteam/admin/dataentities.

Step 1 — Open Workflow admin

Go to /home/yourteam/workflow/admin. You should see the list of workflows and a control to create a new workflow.

Step 2 — Create the workflow shell

Click to add a workflow and fill in:

• Name — Human-readable (e.g. Capital request).
• Slug — URL-safe identifier used in operative URLs (e.g. capital-request). If you leave it blank, the UI often derives it from the name.
• Version — String (e.g. 1). This is the workflow definition version, distinct from form/entity versions.
• Status — Typically active, inactive, or draft depending on whether you want it listed for operators.

Submit to create the row. The page reloads and your workflow appears in the list. Open it to reach /home/yourteam/workflow/admin/{workflowId}.

Step 3 — Workflow metadata (editor header)

On the edit page, set or adjust:

• Name, Slug, Version, Status
• Effective from / Effective until — Optional datetimes controlling when this definition is considered active for new instances (policy may still respect status).

Use Save workflow (or equivalent) so the row updates.

Step 4 — Definition JSON and graph (optional BPMN)

The editor includes a definition JSON area that can embed a validated workflow_graph structure describing steps, edges (next_steps), gateways, participant_groups, and links to form_schema_id / data_entity_id at the graph level.

There is also a BPMN panel that imports/exports XML and can stay in sync with the graph when you use the provided sync actions. If you are not comfortable with BPMN yet, you can rely on the Steps card alone (next section)—the app can still persist a coherent graph for many cases.

Tip: After structural edits, save and refresh if the UI prompts you—some environments sync relational workflow_steps rows from the graph on update.

Step 5 — Build steps (required path)

Use the Steps section to add and maintain ordered steps. For each step you can configure:

Use Add step to append, Edit to change, Delete to remove. The editor validates server-side.

Typical linear pattern

1. start — next_steps → first human step.
2. One or more task steps — each with a form (and optional entity).
3. Optional gateway — routes by outcome.
4. end — next_steps empty.

Step 6 — Step permissions (roles and security)

Expand permissions for each step. Each row defines:

• role_type — system (built-in: owner, member, workflow_admin) or account (pick one of your custom account roles).
• can_view — User sees the step in the instance.
• can_capture — User may submit data / complete the step.

Add multiple rows per step to model handoffs (e.g. member captures submit, custom role “Approver” captures approval).

Save permissions per step applies workflow_step_permissions in the database.

Step 7 — Verify in operative

Visit /home/yourteam/operativeworkflow. Your workflow should appear if status and effective dates allow it. Start a new instance, walk the steps, and confirm task inbox behavior at /home/yourteam/operativeworkflow/tasks if assignments are used.

Checklist

• [ ] Slug unique and stable for bookmarks.
• [ ] Every task that collects data has the right form + entity.
• [ ] next_steps form a complete path to an end step.
• [ ] Permissions match who may view vs submit each step.