Building Workflows
Orquestra workflows are deterministic state machines. Every application submission follows a strict path through states you define — no hidden logic, no runtime surprises. This guide walks through every part of the Workflow Canvas and explains what each feature does.
What is a Workflow?
A workflow is a named, versioned JSON state machine that governs the lifecycle of an application. For example, an Undergraduate Admissions workflow might have states like submitted → under_review → approved or submitted → under_review → rejected.
Workflows in Orquestra are immutable once deployed. Any change to an existing workflow creates a new version. Active applications continue to run on the version they started on, so nothing breaks mid-flight.
↘ rejected
Accessing the Canvas
From the Console, go to Workflows in the left navigation. You will see two buttons at the top right:
- Quick Create — A slide-in panel for fast AI generation or raw JSON entry. Good for simple workflows.
- Canvas Builder — The full visual editor described in this guide. Best for complex, multi-path workflows.
Click Canvas Builder to open the workflow canvas at /console/workflows/new.
Canvas Layout
The canvas is divided into four areas:
Top Bar
Contains the workflow name input (editable inline), the AI Generate button, a Save Draft button, and the primary Deploy & Continuebutton. Saving a draft creates the workflow record without deploying it — it won't be available via the Runtime API yet. Deploying marks it active and redirects you to the Architect page.
Left Palette
Three draggable state type tiles: Initial, State, and Terminal. Drag any tile onto the canvas to place a new state node. The state list below the tiles shows all current nodes and lets you click to select them.
Center Canvas
The main editing area. Drag nodes to position them. Connect two nodes by dragging from the right-side handle of one node to the left-side handle of another — this creates a transition. Click a node to select it; click an edge (arrow) to open the transition editor. Press Delete or Backspace to remove a selected node or edge.
Right Detail Panel
Context-sensitive. Shows the Node Editor when a state is selected, the Transition Editor when an edge is selected, or the Schema Fields Editor when nothing is selected. Each is explained in detail below.
Bottom Bar
Automatically collects all emit events and roles from your canvas (including those added by AI generation). This gives you a live overview of the events your workflow will publish and the roles that will interact with it.
State Node Types
Every state in a workflow has one of three types. The type is both visual (color-coded) and semantic — the workflow engine uses it to determine routing behaviour.
Initial State (blue, pill-shaped)
The entry point of the workflow. Every workflow must have exactly one initial state. When an application is submitted through the Runtime API, execution begins here. Typically named submitted or received.
State (purple, rounded rectangle)
Intermediate processing states. The workflow engine evaluates outgoing transitions from each intermediate state one by one. The first transition whose condition evaluates to true is taken. If no transition matches, the application halts with status waiting_manual_action until a manual trigger moves it forward.
Terminal State (gray, double-bordered rectangle)
End states with no outgoing transitions. Reaching a terminal state marks the application as completed. A workflow must have at least one terminal state — the Deploy button is disabled until one exists. Common names: approved, rejected, withdrawn, archived.
Creating Transitions
Transitions are the arrows between states. To create one, hover over a state node until the handles (small circles) appear on its edges, then drag from the right handle to the left handle of the destination node.
Once created, click the transition arrow to open the Transition Editor in the right panel. Here you set two things:
Condition
A boolean expression evaluated against the application's submitted data. The workflow engine checks each outgoing transition in order and takes the first one whose condition is true. Leave blank for an unconditional (always-taken) transition.
Examples:
Field names in conditions must match the field names defined in the Schema Fields editor. Do not prefix with application_data. — use bare field names only.
Emit Event
The event published to the Orquestra event backbone whenever this transition fires. Events follow a domain.action naming convention. These are surfaced in the Console event stream and can trigger webhooks once your architecture is compiled.
Editing a State Node
Click any node on the canvas to open its editor in the right panel. Two fields are available:
- State Name — The identifier used internally and in transition conditions. Use lowercase with underscores:
under_review,awaiting_documents. The canvas slugifies your label automatically when converting to JSON. - State Type — Change between Initial, State, and Terminal. Only one Initial state should exist in a valid workflow.
- Delete button — Removes the node and all its connected transitions from the canvas.
Schema Fields
Schema fields define what data an applicant must (or may) submit when creating an application through the Runtime API. When nothing is selected on the canvas, the right panel shows the Schema Fields editor.
Fields are validated by the workflow engine at execution time. If a required field is missing or fails its constraints, the application is rejected with a 422 error before the workflow even starts.
Field Properties
string, number, or boolean.number fields. Validates the submitted value is within range.AI Workflow Generation
Click AI Generate in the top bar to open the prompt overlay. Describe the workflow you need in plain language. The AI uses a four-stage validation pipeline to ensure the generated blueprint is structurally sound before it is placed on the canvas.
What the AI Generates
- All state nodes with correct types (initial, intermediate, terminal)
- Transitions with conditions inferred from your description
- Emit event names following
domain.actionconvention - Schema fields with appropriate types, required flags, and validation rules
- Roles and compliance tags (visible in the bottom bar and used at Architect stage)
After generation, the canvas is fully populated. You can edit any node, adjust transition conditions, rename states, or add/remove schema fields before deploying.
AI Provider Cascade
Orquestra tries providers in this order until one succeeds:
- Gemini 2.5 Flash — Primary provider. Fast, high quality JSON output.
- Groq Llama 3.1 — Fallback if Gemini is unavailable or over quota.
- Mock Blueprint — Deterministic fallback when no API keys are set. Passes all four validation stages.
Blueprints are cached in Redis for 24 hours by prompt hash. Regenerating the same prompt within that window returns the cached result instantly.
Four-Stage Validation
Every generated blueprint passes through four automated checks before it can be deployed. The validation result is shown in the Quick Create slide-in panel's Validation tab.
Stage 1 — Schema
Validates the JSON structure of the blueprint matches the expected shape: workflow, roles, events, compliance_tags all present and correctly typed.
Stage 2 — Graph Integrity
Ensures every transition target references a state that actually exists. Checks that an initial state is defined and at least one terminal state exists with no outgoing transitions.
Stage 3 — Permission Analysis
Verifies that roles reference real permission strings and that at least one role has read and one has write-level access. Warns on overly broad wildcard permissions.
Stage 4 — Compliance
Checks compliance tags are recognised identifiers (FERPA, GDPR, HIPAA, SOC2, etc.) and that the blueprint includes appropriate event coverage for the declared compliance regime.
Saving and Deploying
Save Draft
Creates the workflow record in the database but leaves it in draft status. Draft workflows appear in the Workflows table, can be viewed, but are not accessible through the Runtime API. Use this to share a work-in-progress with a colleague before going live.
Deploy & Continue
Creates and immediately deploys the workflow. The button is disabled unless at least one terminal state exists. After successful deployment, you are automatically redirected to the Architect page — the next step where you compose these workflows into your full ERP domain structure.
Best Practices
- Keep workflow names lowercase with underscores — they become the API identifier:
undergraduate_admissions. - Always define at least two terminal states: one for success (
approved) and one for rejection (rejected). Many real processes also needwithdrawnandarchived. - Make transition conditions mutually exclusive where possible. If two conditions are both true, only the first matching one fires.
- Use emit events consistently —
application.approvednotapp_approved. These events drive webhooks and the real-time event stream. - Define schema fields for every field referenced in a condition. Missing fields cause runtime validation failures.
- You can create multiple workflows per project — one for each distinct institutional process (admissions, financial aid, HR onboarding, etc.).