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

# The Workflow Editor

> A walkthrough of the document catalog, the visual and form views, adding states and transitions, locked system steps, and reset-to-default.

The workflow editor is where you design a document's **path** — the states it can be
in and the transitions (arrows) between them. This page walks through everything on the
screen. For the sign-off rules that hang off an approval step, see
[Approval Policies](/workflows/user/approval-policies).

**Route:** `/settings/erp/organization/workflows`

> 📷 *Screenshots to be added. For now the on-screen buttons and labels are named
> verbatim.*

***

## 1. The catalog — pick a document type

When you open Workflows & Approvals you land on **Workflow Definitions**: a searchable
grid of cards, one per **document type** (Expense, Invoice, Leave Request, Advance,
Purchase Requisition, and so on).

* **Search** with the box at the top ("Search document types…") — it matches the
  document's name or its internal type.
* A card shows a small **"Customized"** badge if you've already changed that document
  type's path from the factory default. No badge means it's still on defaults.
* Click a card to open its editor.

> The full list of document types, and what each one's path looks like out of the box,
> is in the [Document Types Reference](/workflows/user/document-types-reference).

***

## 2. The editor header

Once you pick a document type you're in its editor. Along the top:

* **Back** (arrow) — returns to the catalog.
* **Editing {name}** with a **"Customized"** badge if it's been changed.
* A **Visual ⇄ Form** toggle (see below) — two ways to look at the *same* definition.
  Switching views never changes anything.
* **Add State** — add a new named state to the path.
* **Add Transition** — add a new arrow between two states.
* **More actions** (⋯) → **Reset to default** — throw away your customisations and
  return this document type to its shipped path.

> There is **no separate Save button.** Adding a state or transition saves immediately
> when you confirm the dialog, and dragging nodes around the canvas auto-saves the
> layout. You'll get a toast confirming each change.

***

## 3. Visual view (the canvas)

The **Visual** view draws the workflow as a diagram you can read at a glance and drag
to tidy up.

* **State nodes** are rounded pills. A small coloured dot shows the state's category:
  **blue = open**, **green = approved**, **red = rejected**, **grey = terminal**
  (end-of-life). Terminal states get a double outline. The **starting** state carries a
  **"Start"** badge.
* **Action nodes** are the small chips *on* each arrow, labelled with the action
  (Submit, Approve, Reject…). They come in three looks:
  * **Approval gate** — tinted with a **shield** icon and *clickable*. This is where an
    approval policy attaches. It shows a count badge — **"N rule(s)"** if approvers are
    configured, or **"set up"** if none are yet. Click it to open the
    [Approval Policy panel](/workflows/user/approval-policies).
  * **System** — a dashed, muted chip with a **lock** icon. These are driven by the
    system (e.g. the automatic Approve that fires when the last approver signs off) and
    **cannot be edited or deleted**.
  * **Normal** — a solid chip for an ordinary role-gated action.
* **Edges (arrows)** carry a **role pill** (with a people icon) naming who is allowed to
  pull that arrow — e.g. *Requester*, *Finance* — with a "+N" if several roles qualify.

Around the canvas:

* A **legend** (top-left) reminds you of the colour meanings.
* A hint (top-right): **"Drag states to rearrange · layout auto-saved"** — move nodes to
  lay the diagram out how you like; the arrangement is saved for you.
* **Zoom in / Zoom out / Fit** controls (bottom-left).

> If a layout save ever fails you'll see **"Could not save layout — your changes may be
> lost on refresh"**; just drag again once connectivity is back.

***

## 4. Form view

Prefer a list to a diagram? The **Form** view shows the same definition as two plain
lists — handy for fast edits and for reading on a small screen.

* **States** — each row shows the category dot, the state name and its category, with a
  **"Start"** badge on the initial state and a **"Terminal"** badge on end states.
* **Transitions** — each row reads *from → action → to*. Rows tagged **"system"** are
  the locked, system-driven ones. An approval-gate row shows a **"Set up approvers"** /
  **"N rule(s)"** button that opens the same [Approval Policy panel](/workflows/user/approval-policies).
  Ordinary rows list the roles allowed to act.

Both views have their own **Add State** and **Add Transition** buttons.

***

## 5. Adding a state

**Add State** opens a small dialog:

| Field                           | What it means                                                                                               |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **State Name**                  | The name of the state, e.g. `PendingReview`.                                                                |
| **Category**                    | One of **open**, **approved**, **rejected**, **terminal** — this only drives the colour/behaviour grouping. |
| **Terminal (end-of-lifecycle)** | Tick this if the document should be considered finished once it reaches this state.                         |

Confirm with **Add State**; you'll see `State "…" added`.

***

## 6. Adding a transition

**Add Transition** opens a dialog:

| Field                         | What it means                                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Action Name**               | The verb on the arrow, e.g. `Approve`, `Submit`.                                                           |
| **From State** / **To State** | The states the arrow connects (chosen from the states you already have).                                   |
| **Allowed Roles**             | One or more roles allowed to pull this arrow. *"Users in any of the selected roles will see this action."* |
| **Label** (optional)          | A friendlier caption for the arrow, e.g. "Approve Request".                                                |

**Add Transition** is enabled once you've named the action, chosen both states and
picked at least one role. You'll see `Transition "…" added`.

> **Why can't I edit or delete a state/transition inline?** The visual and form views
> are read-only *over* the saved definition — you build the path by **adding** states
> and transitions, and if you want to start over you use **Reset to default**. The
> system-driven (locked) transitions are never removed by an edit, so you can't
> accidentally break a document type's core sign-off contract.

***

## 7. Reset to default

**More actions (⋯) → Reset to default** discards every customisation for this document
type and restores its shipped path (and re-seeds its default approval chain). You'll
see **"Reset to defaults"**. Use it whenever a custom path has drifted somewhere you
don't want.

> Reset applies immediately. There's no separate confirm dialog, so be deliberate — but
> remember the shipped defaults are always exactly one reset away, so nothing here is
> ever permanent.

***

## What you *can't* do here (by design)

* **Edit or delete a locked (system) transition** — these carry backend contracts.
* **Write conditional logic or automatic field changes** — advanced "only when…" rules
  and automatic field updates are managed in code, not exposed in the builder, so a
  mistyped rule can never corrupt a document on transition.

Everything you *can* safely change — states, ordinary transitions, who's allowed to act,
and (per business) who approves — is available on this screen.

***

## Related

* [Approval Policies — who signs off](/workflows/user/approval-policies)
* [Role Bindings — point a role at specific people](/workflows/user/role-bindings)
* [Document Types Reference](/workflows/user/document-types-reference)
* [How Approvals Work Day to Day](/workflows/user/how-approvals-work)