Tutorial 5: Workflow Automation

The status field on your tasks is just a dropdown right now — any user can set it to any value at any time. Workflow automation turns that into a controlled state machine: tasks can only move between states through defined transitions. The existing status dropdown is hidden in DaaS Studio in favour of a dedicated workflow_state field managed by the DaaS workflow engine.

By the end you’ll have:

• A task workflow with four states: Todo, In Progress, In Review, Done
• Four transitions wired up: Start, Submit for Review, Approve, Request Changes
• A WorkflowButton component in the task detail page that renders only the valid next transitions for the current state

Locking transitions down to specific roles, and firing actions on transition (notifications, promotions), are covered in the Going further appendix at the end.

Prerequisites

• Completed Tutorial 4: Role-Based Access.
• Manager and Member roles exist in your DaaS backend.

/create-workflow

npx @buildpad/cli@latest add workflow-button

"use client";
 
import { use } from "react";
import { useRouter } from "next/navigation";
import { Group, Button } from "@mantine/core";
import { IconArrowLeft } from "@tabler/icons-react";
import { CollectionForm } from "@/components/ui";
import { WorkflowButton } from "@/components/ui/workflow-button";
import { isNewItem } from "@/lib/buildpad/utils";
 
export default function TaskDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);
  const router = useRouter();
 
  const handleSuccess = (data?: Record<string, unknown>) => {
    if (isNewItem(id) && data?.id) {
      router.push(`/content/tasks/${data.id}`);
    }
  };
 
  return (
    <div>
      <Group mb="md" justify="space-between">
        <Button
          variant="subtle"
          leftSection={<IconArrowLeft size={16} />}
          onClick={() => router.push("/content/tasks")}
        >
          Tasks
        </Button>
        {!isNewItem(id) && (
          <WorkflowButton collection="tasks" itemId={id} />
        )}
      </Group>
 
      <CollectionForm
        collection="tasks"
        id={isNewItem(id) ? undefined : id}
        mode={isNewItem(id) ? "create" : "edit"}
        onSuccess={handleSuccess}
      />
    </div>
  );
}

Workflow State Machine Reference

The workflow lives in daas_wf_definition.workflow_json. Commands (transitions) are nested inside each state, and actions are nested inside each command — there is no top-level transitions or actions array. The collection link lives on a separate daas_wf_assignment row, not in workflow_json.

{
  "initial_state": "Todo",
  "states": [
    {
      "name": "Todo",
      "isEndState": false,
      "commands": [
        {
          "name": "Start",
          "next_state": "In Progress",
          "policies": [],
          "actions": []
        }
      ]
    },
    {
      "name": "In Progress",
      "isEndState": false,
      "commands": [
        {
          "name": "Submit for Review",
          "next_state": "In Review",
          "policies": [],
          "actions": []
        }
      ]
    },
    {
      "name": "In Review",
      "isEndState": false,
      "commands": [
        {
          "name": "Approve",
          "next_state": "Done",
          "policies": [],
          "actions": []
        },
        {
          "name": "Request Changes",
          "next_state": "In Progress",
          "policies": [],
          "actions": []
        }
      ]
    },
    {
      "name": "Done",
      "isEndState": true,
      "commands": []
    }
  ]
}

Field notes:

• initial_state — the state every new instance starts in. Must match a states[].name.
• states[].isEndState — true for terminal states (no outgoing commands).
• commands[].next_state — destination state. The from is implicit (the parent state).
• commands[].policies — array of UUIDs referencing rows in daas_access. Empty means anyone with write access can run the command. Role names are not used here.
• commands[].actions — array of action objects with event_name and optional parameters. The two built-in events that ship with DaaS are xtr.item.promote (promotes a version delta to the main item — only relevant for versioned content) and xtr.event_test.write_log (debug logger). Any other event name must be registered as a custom action handler in DaaS, otherwise it silently no-ops. Actions fire on the transition, not on entering a state.

Going further

Both of these are optional follow-ups — the tutorial above already gives you a working state machine.

Lock down transitions with policies

To restrict a transition to a specific role:

1. In DaaS Studio, create a policy (under Access → Policies) — for example, “Approve Tasks” — and attach it to the role allowed to perform the transition (i.e Manager Role).

2. Edit the workflow definition (DaaS Studio → Workflows → Definitions → Task Workflow) and add the policy’s UUID to the relevant command’s policies array. For example, to make Approve Manager-only:

   {
     "name": "Approve",
     "next_state": "Done",
     "policies": ["<approve-tasks-policy-uuid>"],
     "actions": []
   }

3. Sign in as a Member — the Approve button should no longer appear on tasks in the In Review state. Sign in as a Manager — the button is back.

Trigger an action on transition

Actions are events that fire after a successful transition — useful for audit logging, sending notifications, updating related data, or any side effect you want tied to a state change. They’re attached to a command, not to a state, so they only run when that specific transition is taken.

Actions fire after a successful transition and are attached to a command, so they only run when that specific transition is taken. This walkthrough adds a last_transitioned_at timestamp to tasks — when Submit for Review runs, the field updates automatically. You verify by refreshing the task.

1. Add a timestamp field to tasks. In DaaS Studio go to Data Model → tasks → New Field. Choose the Datetime interface, name it last_transitioned_at, and mark it read-only in the Metadata tab. Save.

2. Register a runtime extension. Go to Extensions → Add Extension and fill in:

   Field	Value
   Name	Stamp transition timestamp
   Event	xtr.task.stamp-transition
   Type	action

   Paste this into the Code field:

   const wf = meta.payload?.[0]?.workflow_instance;
   if (!wf?.item_id) return;
    
   const tasks = await context.services.items('tasks');
   await tasks.updateOne(wf.item_id, {
     last_transitioned_at: new Date().toISOString(),
   });

   Then click Create → Activate

   Runtime extensions are hot-loaded — no server restart needed.

3. Attach the action to Submit for Review. Go to Workflows → Task Workflow and click the Submit for Review transition arrow. In the modal, switch to the Actions tab and click Add Action:

   Field	Value
   Action Name	Stamp transition
   Event Name	xtr.task.stamp-transition
   Parameters (JSON)	leave empty

   Save the modal, then save the workflow definition.

4. Trigger and verify. Open a task in In Progress and click Submit for Review. Refresh the task — last_transitioned_at is now populated.

   If the field is still empty: confirm the extension is Active, that the Event Name on the command exactly matches the extension’s Event (xtr.task.stamp-transition), and that the transition succeeded.

What’s Next

Your tasks now have a controlled lifecycle. In the next tutorial you’ll link tasks to projects (Many-to-One) and add tags (Many-to-Many) with deep filtering support.

Continue to Tutorial 6: Relations & Linked Data →