--- title: "Workflow" slug: admin/workflow url: https://projectri.com/docs/admin/workflow section: admin audience: admin app_route: "/[slug]/admin/workflow" permissions: [settings.view, settings.workflow, pipeline.configure, client.manage] mobile: false updated: 2026-09-08 source: Projectri documentation --- # Workflow The stages work moves through, the levels of the work-item hierarchy, the approval chains that sign work off, and the sales pipeline stages. ![Workflow](https://projectri.com/docs-shots/admin-workflow.png) ## What it is How work moves through this workspace — the columns on every board, the layers of the work-item hierarchy, and the ordered chains of people who sign work off. The sales pipeline's own stages sit here too, under their own permission. ## How to get there **Work → Workflow** in the admin console rail, at `//admin/workflow`. Reading the page needs `settings.view`. Changing stages, the hierarchy and approval chains needs `settings.workflow`. Editing the portfolio ladder needs `client.manage`. The **Pipeline** tab only appears at all for holders of `pipeline.configure` — naming the columns work moves through and naming the columns *deals* move through are different authorities, and the second reveals the shape of the sales process. ## How to use it ### Rename, recolour and reorder stages 1. On the **Stages** tab, drag a row by its handle to reorder it. 2. The switch on each row enables or disables the stage. Backlog and Completed cannot be switched off. 3. Press the pencil to change a stage's **label** and **colour**. 4. Each row shows the stored key next to the label. It never changes — renaming "In Review" to "QA" relabels every board without rewriting a single task. 5. Nothing on this tab is saved until the save bar at the bottom is used. ### Add a stage of your own 1. Press **Add stage**. At the cap the button stays visible and explains itself rather than disappearing; a workspace may have at most **15** stages. 2. Give it a name, then set **Counts as** — which of the five built-ins it behaves as. This is the field nobody thinks to look for and the only one here that is not cosmetic: reports, burndown and "is it finished" read it rather than the name. A stage that means finished must count as Completed. 3. Pick a colour and an icon from the offered set, and optionally one line saying what being in this stage means. 4. A custom stage writes immediately rather than waiting for the save bar, because it adds a column to every board and an option to every status picker. ### Re-categorise or delete a custom stage 1. Changing a custom stage's **Counts as** rewrites the status of every task in it. The editor says how many tasks that is, before you apply it. 2. Only a custom stage can be deleted. A built-in has no row to delete. 3. Deleting a stage that holds work asks where the work goes, and defaults to the built-in the stage already counts as — so the tasks keep the status they have and only lose the finer label. The confirmation afterwards says how many actually moved. ### Choose the hierarchy 1. The **Hierarchy** tab switches work-item levels on and off — task, subtask, phase, epic, feature, story, sub-story, sprint, module and so on. **TASK** cannot be removed; every work item is ultimately a task. 2. Portfolio levels are the groupings above the project — client, programme, portfolio. 3. The rows those switches are about are edited in the ladder underneath, which writes through its own endpoint rather than the save bar. ### Build an approval chain 1. On the **Approvals** tab, press **New workflow**. 2. Give it a name and an optional description saying when it should be used. 3. Choose a project, or leave it on **All projects**. 4. Add approvers. They sign off in the order they are added — the first approves first — and can be removed with the cross. 5. Editing an existing chain loads its approvers before the form is usable, so an empty list is never mistaken for a chain nobody is on. ### Configure pipeline stages The **Pipeline** tab is the same kind of configuration one domain over — the labels are yours, the semantics are ours. It saves through its own endpoint inside the tab. ## What it affects - **Every board, filter, status picker and report** reads the stage list. A rename here is a rename everywhere, and the shared cache is cleared the moment this page writes, so the change reaches the sidebar without a reload. - **The canonical mapping is what reporting reads.** Burndown, "is this finished" and every completion percentage read a stage's canonical, never its label. That is what lets a workspace call a stage "Client Review" without teaching four reports that it exists. - **Automation rules name the five canonical statuses**, not your labels. A rename never breaks a rule, and a rule cannot be pointed at a custom stage. - **Customer-facing wording is separate.** What a client sees for each internal status is set on [Customer status](/docs/admin/status), not here. - **Deleting a stage moves task rows.** That is the one action on the Stages tab that is not purely presentational, along with re-categorising a custom stage. - **An approval workflow with recorded decisions cannot be deleted.** ## On mobile This screen is web only. ## Limits and gotchas - A stage label is capped at 40 characters and its one-line description at 160. - The icons a custom stage may use are a fixed set. Free text would render as a blank tile with nothing to warn you. - A built-in stage's key is a stored status and never changes. Do not expect a rename to be a data migration in either direction. - The reset button on the colour picker restores the stage's current colour, not a product default — the code default is a theme token rather than a hex, so it has no swatch. - Approval chains and agent approvals are different systems. See [Agent approvals](/docs/admin/agents-approvals) for the second. ## Related - [Automation](/docs/admin/automation) — rules that move work between these stages. - [Settings](/docs/admin/settings) — the working week and locale everything else reads. - [Workspaces](/docs/admin/workspaces) — the container these stages apply within. - [Approvals](/docs/features/approvals) — how sign-off works across the product. ## Related - [Automation](https://projectri.com/docs/admin/automation.md): Rules that react to what happens in this workspace — a trigger, optional conditions, and an ordered flow of actions, waits and branches. - [Settings](https://projectri.com/docs/admin/settings.md): Branding, region, locale, the working week and storage policy — the tenant preferences that every other screen in Projectri reads. - [Workspaces](https://projectri.com/docs/admin/workspaces.md): The containers projects live in, and what kind of place each one is — the type sets what a new project inherits and whether customers may be let in at all. - [Approvals](https://projectri.com/docs/features/approvals.md): The two things in Projectri that wait for a person to say yes — an approval chain on a task, and an AI agent asking permission before it changes anything.