> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Editor

> Build and configure the visual workflow graph for an automation rule using a node-based canvas editor.

The Workflow Editor at `/fw/automations/:id/workflow` provides a full-screen, node-based visual editor for building the workflow definition associated with an automation rule. It is reached from the automation rule detail view.

## Overview

The Workflow Editor is a full-screen layout (no page chrome) with:

* **Left sidebar** — `NodePalette` (drag-and-drop node types), `VariablePanel` (workflow variable management), and `VariablePreviewPanel` (sample context preview when variables exist).
* **Center canvas** — `WorkflowCanvas` (React Flow-powered graph; supports drag-and-drop from palette, node selection, edge creation).
* **Right sidebar** — `NodePropertiesPanel` for configuring the selected node, including trigger configuration for the start node.
* **Header toolbar** — Rule name, version badge, auto-save indicator, Save, Publish Version, Generate with AI, Notifications, Testing, Validate, and Version History.

Changes to the canvas are debounced (1 second) and auto-saved. Manual save via the "Save" button flushes immediately and runs non-blocking subflow validation. "Publish Version" runs blocking subflow validation before flushing a save and creating a new version.

The editor requires `fw.workflows.edit` permission (checked via `useHasPermission`) to enable the "Generate with AI" button. Trigger configuration updates require write access via `useAutomationRuleMutations`.

## Who it's for

No explicit `RequirePermission` guard on this route in `src/routes/fw.tsx`. The automation rule is loaded by ID; access is controlled at the data layer. The "Generate with AI" button is disabled unless the user has `fw.workflows.edit`.

## Before you start

* An organization must be active. If the current organization is absent or the automation rule is not found, the page shows an error message.
* The automation rule identified by `:id` must exist in `useAutomationRules`.

## Steps

**Opening the editor:**

1. Navigate to `/fw/automations/:id/workflow` from the automation rule detail page.
2. The canvas loads the saved node and edge layout.

**Building the workflow:**

1. Drag node types from the **Node Palette** (left sidebar) onto the canvas.
2. Connect nodes by drawing edges between them.
3. Click a node to open its properties in the **Node Properties Panel** (right sidebar).
4. Configure the start node trigger type and event configuration as needed.

**Managing variables:**

1. Use the **Variable Panel** in the left sidebar to add, update, or remove workflow variables.
2. Use the **Variable Preview Panel** to inspect sample values when testing variable expressions.

**Saving:**

* Changes auto-save after 1 second of inactivity.
* Select **Save** to flush immediately. Non-blocking subflow validation runs on save; warnings are shown if violations exist.

**Publishing a version:**

1. Select **Publish Version**.
2. Blocking subflow validation runs. If violations are found, publish is blocked and a toast lists the issues.
3. On validation success, the current state is saved and a new version record is created.

**Testing:**
Select **Testing** to open the `SandboxPanel` in a side sheet for test execution.

**Viewing version history:**
Select **History** to open the `WorkflowVersionHistory` side sheet.

**Generating with AI:**
Select **Generate with AI** (requires `fw.workflows.edit`) to open `GenerateWorkflowAIDialog` for AI-assisted workflow generation.

## Key concepts

* **Automation rule** — The parent record (identified by `:id`) that owns this workflow definition.
* **Workflow definition** — The serialized graph of nodes, edges, viewport, and variables persisted by `useWorkflowDefinition`.
* **Trigger type** — Determines when the automation fires (e.g., `form_submitted`, date-relative triggers). Configured on the start node.
* **Subflow validation** — `validateSubflowOrchestration` checks that subflow nodes reference valid subflow definitions with compatible input/output schemas.
* **Variables** — Named values managed by `useWorkflowVariables`; available in node configurations and expressions.
* **Auto-save debounce** — 1-second debounce after any canvas or variable change.

## Related

<Columns cols={2}>
  <Card title="Forms & Workflow" icon="diagram-project" href="/fw/overview">
    Forms & Workflow core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/fw\.tsx
  * src/cores/fw/pages/WorkflowEditor.tsx
  * src/cores/fw/hooks/useWorkflowDefinition.ts
  * src/cores/fw/hooks/useAutomationRules.ts
  * src/cores/fw/hooks/useSubflows.ts
  * src/cores/fw/hooks/useWorkflowVariables.ts
  * src/cores/fw/utils/subflowOrchestrationValidator.ts
</Accordion>