Workflows Module Recipe

The Workflows module is the admin surface for the workflow engine of your DaaS backend. A definition is a state machine: states, and commands that move an item from one state to another. An assignment says which definition the items of a collection get. An instance is one item on its way through its workflow.

The module gives you six screens:

• WorkflowsManager — the /workflows list: search by name or description, pagination, and permission-gated create, edit and delete.
• WorkflowDetail — the /workflows/[id] editor: name, description, statistics, a states overview, and the state machine drawn as a diagram. States and commands are edited in dialogs or directly on the canvas. The whole machine is one workflow_json document, saved with one request.
• WorkflowAssignmentsManager — the /workflow-assignments list: which workflow runs on which collection, and whether a filter rule narrows it.
• WorkflowAssignmentDetail — the /workflow-assignments/[id] form: the workflow, the collection, and an optional filter rule edited as JSON.
• WorkflowInstancesManager — the /workflow-instances list (read-only): search by collection, state or item id.
• WorkflowInstanceDetail — the /workflow-instances/[id] page (read-only): the instance’s fields, its workflow as a diagram, and the whole transition history, newest first.

This module administers workflows. The button that runs a command on one item is a different component: the workflow-button interface (Component Map).

The pieces

Install

buildpad add workflows-routes

buildpad add workflow-management

pnpm add "@xyflow/react@^12.9.3"

NEXT_PUBLIC_BUILDPAD_DAAS_URL=https://your-daas.example.com

The routes

Six files give you the whole module:

app/[lang]/(authenticated)/
├── workflows/
│   ├── page.tsx            # /workflows                  — WorkflowsManager
│   └── [id]/page.tsx       # /workflows/[id]             — WorkflowDetail (use /workflows/new to create)
├── workflow-assignments/
│   ├── page.tsx            # /workflow-assignments       — WorkflowAssignmentsManager
│   └── [id]/page.tsx       # /workflow-assignments/[id]  — WorkflowAssignmentDetail (use /workflow-assignments/new to create)
└── workflow-instances/
    ├── page.tsx            # /workflow-instances         — WorkflowInstancesManager
    └── [id]/page.tsx       # /workflow-instances/[id]    — WorkflowInstanceDetail

The components do not navigate. Each page passes router callbacks, so your router (and its locale prefix) decides where a click goes.

"use client";
 
import React from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { WorkflowsManager } from '@/components/ui/workflow-management';
 
export default function WorkflowsPage() {
  const router = useLocaleRouter();
 
  return (
    <WorkflowsManager
      onWorkflowClick={(workflow) => router.push(`/workflows/${workflow.id}`)}
      onCreateWorkflow={() => router.push('/workflows/new')}
    />
  );
}

"use client";
 
import React, { use } from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { WorkflowDetail } from '@/components/ui/workflow-management';
 
export default function WorkflowDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);
  const router = useLocaleRouter();
 
  return (
    <WorkflowDetail
      id={id}
      onBack={() => router.push('/workflows')}
      onSaved={() => {
        if (id === 'new') router.push('/workflows');
      }}
    />
  );
}

Component props

Every component also takes translations, a partial override of the workflows dictionary namespace for that one instance.

The three lists

WorkflowDetail

WorkflowAssignmentDetail

When the collections cannot be listed, the Collection field becomes a text field, so the form still works. One backend serves /api/collections to administrators only.

The Filter Rule is a DaaS filter object. Valid JSON that is not an object ([], 123, "x") is refused on the field and nothing is sent. An empty field means no rule.

WorkflowInstanceDetail

The diagram does not mark the current state. The Current State field does.

WorkflowDiagram

Use it on its own to show a workflow on another page.

import { WorkflowDiagram } from '@/components/ui/workflow-management';
 
<WorkflowDiagram workflowJson={definition.workflow_json} readOnly height={360} />

The canvas is a view of workflowJson. A gesture does not change the canvas. It produces the next document and hands it to onChange; the canvas redraws when that document comes back in workflowJson.

WorkflowStateModal and WorkflowCommandModal

WorkflowDetail renders both. Use them directly only when you build your own editor around WorkflowDiagram.

The editor

• A state is dragged by its grip. A click on a state card only selects it.
• A state is edited from its menu. A command is edited by a click on its row or on its arrow.
• A command is added by dragging from a blue dot of one state to another state. The Command dialog opens with the target filled in.
• A command is also added from the state’s menu (Add Command). The Command dialog then asks for the target. This is the way to add a command with the keyboard: a connection can only be drawn with a pointer.
• An arrow can be moved to another state.
• Backspace or Delete removes the selected state or command from the document. The last state cannot be deleted.
• An end state has no outgoing commands. Its dots start no connection, an arrow cannot be moved to start from it, and End State cannot be turned on for a state that has commands.
• Save Changes is disabled while there is nothing to save. An update sends only the keys that changed.

A command is saved on top of the stored command, so keys the dialog has no field for are kept.

An action’s Parameters must be a JSON object. Text that is not JSON, and JSON that is not an object ([], 123, "x"), is refused on the field. The save opens the tab and the action that hold it. An empty field means no parameters.

A definition can be answered without its workflow_json, when the user’s read grant on daas_wf_definition leaves that field out. The editor then shows a notice in place of the statistics and the diagram. It does not draw an empty machine, and it never sends the document. The name and the description can still be saved.

The data layer

The screens are thin. The work is in three hooks that you can use anywhere under DaaSProvider.

import { useWorkflowDefinitions, DaaSRequestError } from '@/lib/buildpad/hooks';
 
const { fetchDefinitions, getDefinition } = useWorkflowDefinitions();
 
const { items, total, totalPages } = await fetchDefinitions({ search: 'approval', page: 1, limit: 25 });

Each hook returns loading, error (the last failure’s message), errorInfo (the same failure as a DaaSRequestError), and its methods:

A list method takes { page?, limit?, search? } (defaults: page 1, 25 rows) and resolves to a WorkflowListResult<T>:

interface WorkflowListResult<T> {
  items: T[];         // rows of this page
  total: number;      // rows matching the request across all pages
  totalPages: number; // at least 1
  page: number;       // page that was served
  limit: number;      // page size that was served
}

Four details matter when you call the hooks yourself:

• fetchDefinitions returns one page. For a picker, use fetchAllDefinitions, which reads every page.
• updateDefinition resolves to nothing. Read the definition again with getDefinition when you need the stored form. description: null clears the description.
• A WorkflowDefinitionRecord has no workflow_json when the caller’s grant withholds that field. This is not an empty machine: do not draw one, and do not send one back.
• deleteDefinition is refused (kind: 'invalid') for a definition that is assigned to a collection or has instances. The message says which.

Typed errors

Every method rejects with a DaaSRequestError. It is an Error whose message is a readable sentence, with three more fields:

try {
  const instance = await getInstance(id);
} catch (err) {
  if (err instanceof DaaSRequestError && err.kind === 'notFound') {
    // draw a not-found state
  }
}

A failed load never resolves to an empty list, and a get never resolves without a record.

Editor logic

The functions that build and check a workflow_json document are pure and live in @/lib/buildpad/utils: buildWorkflowCommand, buildWorkflowState, applyWorkflowCommandSave, applyWorkflowStateSave, removeWorkflowState, removeWorkflowCommand, moveWorkflowState, reconnectWorkflowCommand, findWorkflowCommandProblem, findWorkflowStateProblem, findWorkflowConnectionProblem, findWorkflowDefinitionProblem, normalizeWorkflowJson, isWorkflowFilterRule and parseWorkflowFilterRule. Use them when you write a custom editor, so your saves keep the keys your form does not show.

Permissions

The checks use the collection names both backends enforce. They are exported from @/lib/buildpad/types as WORKFLOW_COLLECTIONS.

• The gates come from usePermissions().canPerform(collection, action). Administrators pass every gate.
• Until the permissions are known, no write control is drawn and the editors take no edit: no Add or New button, no row menu, no Save button, a covered form, and a diagram without its edit controls. The controls appear when the answer is in, so a user without a right does not see its button first. A new route does not open its form and does not draw access-denied before then. Reading does not wait: the lists and the records load at once. A later refresh of the permissions (a renewed token, another scope) keeps the controls as they were until its answer is in.
• A row menu with no allowed action is not drawn.
• The gates only hide controls. The API enforces the same collections, so a hidden button is not the protection.
• Gate your navigation links too, so a user without read access to daas_wf_definition does not see the Automation group.
• Two pickers read other collections: the Command dialog’s Policies tab reads daas_policies, and the assignment form’s Workflow picker reads daas_wf_definition. A failed load is a notification, and the stored value is kept.

Who may run a command

A command stores two lists: policies (policy ids) and module_access_keys. A caller who holds any listed policy or any listed key may run the command. A command with neither list is open to every authenticated user.

The Command dialog edits policies. It has no field for module_access_keys: it keeps the stored keys on save and shows a notice that the command is gated by them. Set the keys through the API.

Both backends

The module works against the Next.js DaaS (Supabase) and the Go engine. The hooks read both pagination vocabularies (count / totalCount / totalPages, and meta.filter_count / meta.total_pages), accept data: null as an empty page, and always send page and limit.

The routes it calls:

• GET, POST /api/workflows; GET, PATCH, DELETE /api/workflows/[id]
• GET, POST /api/workflow-assignments; GET, PATCH, DELETE /api/workflow-assignments/[id]
• GET /api/workflow-instances, /api/workflow-instances/[id] and /api/workflow-instances/[id]/history
• GET /api/permissions/me (the gates), /api/policies (the Policies tab) and /api/collections (the Collection picker)

Prerequisites

• DaaSProvider above the pages. The module installs under the authenticated layout, where DaaSProviderWrapper supplies the DaaS URL, the session token and the tenant scope header.
• <Notifications /> from @mantine/notifications mounted once. Saves, deletes and failed loads report through it. The generated root layout mounts it.
• An i18n provider for a language other than English. The strings are the workflows namespace, shipped in English and Indonesian. The generated I18nProvider selects the catalog for the active locale. To change a string, set it under buildpad.workflows in your dictionary, or pass translations to one component. Without a provider the components render the English defaults.
• @xyflow/react ^12.9.3 in your package.json.
• React Flow’s attribution. The diagram shows a small “React Flow” link in a corner of the canvas. hideAttribution removes it. React Flow is MIT licensed, and its authors ask organisations that remove the attribution to support the project . The default leaves it on; the decision is yours.
• No extra styling. The components use the design tokens through the Mantine theme and follow the color scheme. See the Styleguide.

See the components live

Every surface is in the Workflows Storybook. Run it locally with pnpm storybook:workflows (port 6013). The fixture stories run on mock data. The Live DaaS stories of WorkflowsManager, WorkflowDetail, WorkflowAssignmentsManager and WorkflowInstancesManager connect to a real DaaS instance through the storybook-host proxy (pnpm dev:host).