Lesson 6 - Add Your First High-Leverage Workflow

Taylor wants to build one workflow that removes obvious coordination overhead from the exception process, and demonstrates the viability of Zebric applications.

In the Playground, workflows are traced, not actually executed — triggering one there logs a debug entry and tells you “external side effects are not executed in the browser simulator,” but it will not really change a status or send a real notification.

To see and test the real thing, we’ll run the blueprint locally.

Installing the CLI

You will need Node.js installed (version 22.x or above).

Install the CLI:

npm install -g @zebric/cli

Then go back to the Playground, open the Editor tab, and click Download to save your blueprint as exception-request.toml (or rename it to blueprint.toml). Everything you built in Lessons 2 through 5 is usable as a real application.

Run your blueprint after validating it:

zebric validate --blueprint blueprint.toml
zebric dev --blueprint blueprint.toml

Open http://localhost:3000 and sign in for the first time — this is where the [auth] block and /sign-in page from Lesson 5 can be demonstrated.

From here on, keep editing this local blueprint.toml. This lesson adds a workflow section and wires it into the existing request detail page. Zebric has a hot reload feature in development mode, so saving your changes to the blueprint will refresh the application.

Choosing the First Workflow

For HarborFlow, a strong first workflow is:

• when an exception request is approved, move it forward and notify the right internal owner

Start with one event and one useful outcome:

• a guarded domain command changes status
• a notification is sent
• a follow-up field is updated

This should be enough to demonstrate feasibility.

HarborFlow Example

Taylor might define a workflow like:

• trigger: manual approval action on the request detail page
• step 1: update status from reviewing to approved
• step 2: send a notification to ops

That gives the app:

• visible workflow progression
• a clearer approval path
• less manual follow-up

Here is a concrete first version:

[command.ApproveExceptionRequestState]
entity = "ExceptionRequest"
description = "Apply the guarded approval state transition."
policy = "workflow.__zebric.currentWorkflow == 'ApproveExceptionRequest'"
availableWhen = "record.status in ['submitted', 'reviewing']"
mutations = { status = "approved" }

[notifications]
default = "console"

[[notifications.adapters]]
name = "console"
type = "console"

[[workflows]]
name = "ApproveExceptionRequest"
description = "Approve an exception request and notify operations."

[workflows.trigger]
manual = true

[workflows.precondition]
"variables.data.record.status" = ["submitted", "reviewing"]

[[workflows.steps]]
type = "command"
command = "ApproveExceptionRequestState"
recordId = "{{ variables.data.record.id }}"

[[workflows.steps]]
type = "notify"
adapter = "console"
body = "Exception request approved: {{ variables.data.record.title }}"

A TOML note: [workflows.steps.where] and [workflows.steps.data] attach to whichever [[workflows.steps]] entry was declared immediately above them. If you add a third step later, keep each step’s where/data tables directly under that step’s [[workflows.steps]] line, in order — moving them out of sequence silently reattaches them to the wrong step.

Then expose it from the detail page with an action bar:

[pages.actionBar]
statusField = "status"

[[pages.actionBar.actions]]
label = "Approve Request"
workflow = "ApproveExceptionRequest"
style = "primary"
visibleWhen = { status = ["submitted", "reviewing"] }

Add this action bar block under the existing [[pages]] entry where path = "/requests/:id".

Protect the existing status field so forms, generic API updates, and query steps cannot bypass this command:

fields = [
  # Keep the entity's other fields here.
  { name = "status", type = "Enum", values = ["submitted", "reviewing", "approved", "rejected", "completed"], default = "submitted", write = "command-only", commands = ["ApproveExceptionRequestState"] }
]

Using the console adapter is enough for a first pass because you can verify the workflow wiring locally before you switch to Slack or email. The command owns the state transition; the workflow coordinates that transition with the notification.

visibleWhen hides the workflow action when the record is no longer awaiting approval. The workflow precondition still rejects a stale click before any step runs, and the command repeats the state check during execution. UI visibility is a convenience, not an authorization boundary. Commands rendered directly by Zebric use availableWhen for the same presentation behavior; this example keeps the workflow button because it also coordinates a notification.

Why This Matters

At HarborFlow, the difference is easy to see:

• before: someone approves in Slack and hopes the right person notices
• after: the request status changes in the system and the next owner is notified

We could certainly use other tools to do the same thing, but Zebric keeps you in control.

Lesson Output

By the end of this lesson, you should have:

• the CLI installed and your blueprint running locally instead of in the Playground
• a working sign-in flow you can actually verify, not just a redirect
• one workflow tied to a real business transition, with a real status change and a real console notification
• a stronger case for rolling the tool out to the broader team

Use Workflows & Notifications for more step types and adapter options.

What Changes In blueprint.toml

In this lesson, you are adding automation-related sections:

• add a [notifications] block and at least one adapter
• add a domain command for the guarded approval transition
• mark status as command-only
• add a [[workflows]] definition named ApproveExceptionRequest
• add workflow steps to invoke the command and send a notification
• add an action bar to the detail page so users can trigger the workflow

This is the first lesson where a user action leads to a workflow-backed state change instead of only CRUD behavior.

Checkpoint Blueprint

Use lesson-6-blueprint.toml if you want a complete, working file with auth, access control, the approval workflow, console notifications, and the detail-page action bar.

Validate and run the checkpoint locally:

zebric validate --blueprint lesson-6-blueprint.toml
zebric dev --blueprint lesson-6-blueprint.toml

Zebric Concepts In This Lesson

• CLI: zebric validate and zebric dev run your blueprint for real, outside the browser sandbox
• Workflows: manual triggers and multi-step automation
• Domain Commands: one guarded implementation of the approval state transition
• Notifications: console, Slack, or email adapters for alerts
• Pages: action bars expose workflows in the UI
• Entities: workflow steps update entity state as part of the business process
• Protected Fields: generic writes cannot bypass the approval command

Next Lesson

Continue to Lesson 7 - Polish With Real Feedback.