diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index d8d2d33b..ad440acd 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -399,6 +399,7 @@ if(n<200&&document.readyState==="loading")requestAnimationFrame(function(){bar(n }, ], }, + { text: "Workspace Governance", link: "/workspace-administration/workspace-governance" }, { text: "Authentication", collapsed: true, diff --git a/docs/automations/custom-automations.md b/docs/automations/custom-automations.md index 70a554ee..03587380 100644 --- a/docs/automations/custom-automations.md +++ b/docs/automations/custom-automations.md @@ -17,6 +17,26 @@ Every custom automation has three components. When [trigger] happens, if [condit - **Conditions** are optional filters that must be satisfied for the automation to proceed. If you add multiple conditions, all of them must be met (AND logic). - **Actions** are what the automation does when fired. Multiple actions execute in sequence. +## Where automations live depends on your plan + +Every plan builds automations the same way, with the same triggers, conditions, and actions. What differs is **where** they are configured, **which projects** they can act on, and **which actions** are available. Find your setup below. + +| Plan / setup | Where you configure automations | What you get | +| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Business** | Inside each project, under **Project Settings → Automations** | Custom automations scoped to one project, with the **Change property** and **Add comment** actions. | +| **Enterprise Grid** (project-managed) | Project settings, plus **Workspace Settings → Automations** | Everything above, plus **workspace automations** that span all projects or a chosen subset, the **Send webhook** and **Run script** actions, and **scheduled** triggers. | +| **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** | Once for the whole workspace, under **Settings → Automations** | Automations are managed centrally by a workspace admin and applied to projects. Project admins no longer create or edit automations inside a project. | + +**In short** + +- On **Business**, automations live in **project settings** and act on that one project. +- On **Enterprise Grid without governance**, you keep project automations and can also create **workspace automations** and use the webhook and script actions. +- On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)**, automation management moves to the **workspace level**. Project admins can no longer edit automations inside a project. See [Automations under workspace g`overnance](#automations-under-workspace-governance). + +:::warning Turning on governance moves automations to the workspace +Enabling Workspace Governance is a one-way change that relocates automation management from individual projects to the workspace. Existing project automations are migrated up and keep running. Read [Workspace Governance](/workspace-administration/workspace-governance) before enabling it. +::: + ## Create a custom project automation Project automations apply to work items within a single project. @@ -291,6 +311,18 @@ Conditions are what make an automation surgical. They let you say "only run this One thing worth knowing: when a work item is first created, some fields like assignees and labels can take a moment to register, even if someone filled them in during creation. Plane handles this - it checks the latest state of those fields before evaluating your conditions, so a filter like "assignee is X" on a creation trigger will work as expected. +## Automations under workspace governance + +On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** enabled, automations are managed once for the entire workspace instead of project by project. A workspace admin owns all automation configuration, and project admins can no longer create or edit automations inside a project. + +You build these automations exactly as described above. This section covers only what's different when governance is on: + +- **Project-level automation editing is locked.** Project admins can no longer create or edit automations inside a project. Opening an automation in a project shows it as read-only, with a message that automations are managed at the workspace level. +- **Existing project automations are preserved.** When governance is enabled, each project's automations are migrated up to the workspace level and scoped back to their original project, so they keep running exactly as before. +- **All automations are managed centrally.** A workspace admin creates and edits every automation under **Settings → Automations**, choosing whether each one applies to all projects or a specific subset. + +See [Workspace governance](/workspace-administration/workspace-governance) for the full picture of what centralizes and what changes for projects. + ## Common use cases Some common things people use automations for. diff --git a/docs/core-concepts/issues/states.md b/docs/core-concepts/issues/states.md index 77bc921c..ec81337a 100644 --- a/docs/core-concepts/issues/states.md +++ b/docs/core-concepts/issues/states.md @@ -1,5 +1,5 @@ --- -title: Workflow States +title: Work Item States description: Manage work item progress with customizable states in Plane. Organize tasks through backlog, unstarted, started, completed, and cancelled state groups. --- @@ -7,8 +7,19 @@ description: Manage work item progress with customizable states in Plane. Organi Managing work items effectively is at the heart of every project, and Plane provides a robust system for organizing them into states that represent the stages of a work item's lifecycle. As work items transition through these states—from backlog to completion—they reflect the progression of work in your project, forming a clear and efficient workflow for your team. +## Where to configure states + +Each project defines its own states, managed by a **project admin** under **Settings → (project) → States**. This is the default. + +**Enterprise Grid - workspace level** +With [workspace governance](/workspace-administration/workspace-governance) enabled, states become a single shared set for the whole workspace, managed by a **workspace admin** under **Workspace Settings → States**, then applied to every project. Project admins use the shared set but can't edit it. See [Under Enterprise Grid governance](#under-enterprise-grid-governance). + +The concept and most mechanics are identical either way; only where you configure them, who can, and a few behaviors differ. + ## State groups +Every state belongs to one of five groups. The group is the meaning Plane attaches to the state; the name is your label for it. + ![Work item states](https://media.docs.plane.so/projects/issue-states.webp#hero) Plane organizes work item states into five primary groups, each serving a distinct purpose in your project’s workflow: @@ -27,27 +38,86 @@ Plane organizes work item states into five primary groups, each serving a distin - **Cancelled**: Use this group for work items that are no longer relevant or actionable. Plane provides a default state called **Cancelled** for this purpose. -## Customize states +### What groups drive + +The group, not the state name, determines behavior across Plane: + +- **Completion and progress** - only work items in the **Completed** group count as done. Cycle and module progress, burndown, and analytics bucket work items by group. +- **Archiving** - only work items in **Completed** or **Cancelled** states are eligible for automatic archiving. +- **Ordering** - states sort by group first, then by position within the group. + +Because of this, **changing a state's group changes how its work items are counted**. Moving a state into Completed, for example, makes its work items count as done in every chart and progress bar. + +## The default state + +Exactly one state is the **default** - the state new work items get when none is chosen. New projects start with Backlog as the default. + +To change it, open a state and choose **Mark as default**. The previous default is cleared automatically; there is always exactly one. + +::: info **Enterprise Grid** +The default is not a flag on the state and there is no "Mark as default." The default is the **starting state of the workflow**, set on the [Workflows](/workflows-and-approvals/workflows) page. A governed workspace's default workflow starts at **Todo**. +::: + +## Triage state -You can customize each state group to match your project's workflow by adding, editing, or removing states. +Triage is a special, system-managed state used as the holding area for [intake](#) submissions - items land in Triage before being accepted into the project's normal flow. -Navigate to the **States** tab under **Project > Settings**. +- There is **one triage state per project**, or **one per workspace** under governance. +- **"Triage" is a reserved name** - you cannot name a state Triage. +- You **cannot create** a state in the Triage group, and you **cannot delete** the triage state. +- Triage is kept out of normal state lists and excluded from analytics. -![Modify states](https://media.docs.plane.so/projects/project-new-state.webp#hero) +## Manage states -### Add state +States are shown grouped. Use the **+** on a group to add a state to it. + +**Create** - set a **name**, a **color**, and an optional **description**. The group is determined by which group you add the state under. A duplicate name is rejected. + +::: info **Enterprise Grid:** +State names must be unique across the **whole workspace**, and the check is **case-insensitive** - "Todo" and "todo" are treated as the same. (When governance is first enabled, same-named states from different projects are merged into one.) +::: + +**Edit** - change the name, color, or description at any time. To change a state's group, drag it into another group. + +**Reorder and regroup** - drag a state to reorder it within its group, or drag it into a different group to reassign it. You **cannot drag away the last state in a group** - every group must keep at least one state. + +**Delete** - remove a state, subject to these rules: + +- The **default state cannot be deleted**. Set a different default first. +- A state with **work items cannot be deleted** - there is no automatic reassignment. Move its work items to another state first, then delete it. +- The **triage state cannot be deleted**. +- A group's **last remaining state cannot be deleted**. + +Deleting a state is permanent. + +:::info **Enterprise Grid** +A state also **cannot be deleted while a workflow uses it** - the error names the workflows. Remove the state from those workflows first. Project admins cannot create, edit, or delete states at all; state management happens at the workspace level. +::: + +## Restricting work item creation in a state + +Whether work items can be created directly in a given state is a **workflow** setting, not a property of the state itself. In a workflow, each state has an **allow work item creation** toggle; turn it off for states that should only be reached by moving an existing work item (like "Done"). See [Workflows](/workflows-and-approvals/workflows). + +--- -1. Click the "+" button next to the group where you want the new state. -2. Rearrange states within the group to reflect your preferred workflow. +## Under workspace governance -You can also designate a state as the default for the project. New work items without an assigned state will automatically fall into this default state. +When governance is on, states are a single **shared catalog** for the whole workspace: -### Edit state +- One shared set that every governed project draws from. A project's visible states are the ones used by the workflows its work item types resolve to. +- Names are unique across the workspace, case-insensitive. +- One workspace triage state. +- The default concept moves to the workflow's starting state. +- Project admins cannot edit states; deleting a catalog state is blocked while a workflow references it. -1. Hover over the state you want to edit. -2. Click the pencil icon and change the name and description. -3. Click **Update** to save changes. +See [Workspace governance](/workspace-administration/workspace-governance) for how governance works overall. -### Delete state +## Warnings and limitations -Before removing a state, ensure no work items are currently assigned to it. Once it's clear, you can delete the state by clicking the **x** icon on the state. +- **The default state cannot be deleted** - reassign the default first. +- **A state with work items cannot be deleted** - move those work items first; there is no automatic reassignment. +- **Every group must keep at least one state.** +- **"Triage" is reserved** and cannot be created as a group or deleted. +- **State names must be unique** - within the project, or across the workspace (case-insensitive) under governance. +- **Changing a state's group re-buckets its work items** for progress, analytics, and archiving. +- **Under governance**, a catalog state can't be deleted while a workflow references it, and project admins can no longer edit states. diff --git a/docs/work-items/workspace-work-item-types.md b/docs/work-items/workspace-work-item-types.md index 86669e68..6b9908e9 100644 --- a/docs/work-items/workspace-work-item-types.md +++ b/docs/work-items/workspace-work-item-types.md @@ -53,6 +53,23 @@ Once enabled, you'll see the **Work item Types** and **Properties** tabs. The de The new type appears in the list. Use the toggle next to it to control whether project members can select it when creating work items. +The type name must be **unique across the workspace**. A newly created type starts **inactive** until you turn it on with the toggle. + +## How a type reaches projects + +Creating a type at the workspace level makes it available in the workspace library, but it does not put the type into every project by itself. How a type reaches a project depends on its rollout setting: + +| Rollout | Behavior | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Import** (default) | The type is added to a project only when a Project Admin imports it from the workspace library. See [Import types into a project](#import-types-into-a-project). | +| **Mandatory** | The type is present in **every** project and cannot be removed by a Project Admin. Marking a type Mandatory adds it to all existing projects immediately. | + +:::warning +Marking a type **Mandatory** adds it to every project right away, and a mandatory type cannot be deactivated or removed at the project level. Changing it back to Import later does **not** remove it from projects that already have it. +::: + +The default **Task** type behaves like a workspace-wide type: it is present in every project and cannot be deleted or made inactive. + ## Create workspace custom properties > **Role**: Workspace Admin @@ -83,6 +100,36 @@ The property is now available to attach to any work item type. If the modal shows "No properties available," either all existing properties are already linked to that type, or no custom properties have been created at the workspace level yet. Create new properties from the **Properties** tab first. +## Property settings + +Every property, regardless of its type, shares a common set of settings. + +**Title** (required) +The label members see on the work item. It must be unique within the type, and cannot reuse one of the reserved field names **state**, **due date**, **cycle**, or **modules**. Plane derives an internal name from the title automatically, which is what [formulas](#formula) and the API use to reference the field. + +**Description** +Optional helper text explaining what the property is for. + +**Icon** +An icon shown next to the property. Each property type has a sensible default. + +**Mandatory** +When on, the value cannot be left empty and the work item cannot be created or saved without it. Marking a property mandatory **clears any default value**. Boolean, Formula, and read-only Text properties cannot be made mandatory. + +**Active** +Properties are active by default. Turn a property off to hide it without deleting it, and without losing values already entered on existing work items. + +**Default value** +A value pre-filled on new work items. Most property types support a default; Formula properties do not, and a mandatory property cannot carry a default. + +**Single or multi select** +For Dropdown, Member picker, and Release picker properties, whether members can select one value or several. + +**Display order** +New properties are added to the end of the type and can be reordered. The order set here is the order members see on the work item. + +Several of these settings can be **overridden per context**, so the same property can be mandatory in one project or type and optional in another. See [Scope properties with contexts](#scope-properties-with-contexts). + ## Property types ### Text @@ -93,15 +140,17 @@ A freeform text field. When you add a text property, you choose one of three for - **Paragraph:** A multi-line input for longer freeform content. - **Read-only:** A fixed text display. You enter the text when setting up the property, and members see it on every work item but cannot edit it. Read-only text properties cannot be marked as mandatory. +The format is chosen when the property is created and cannot be changed afterward. + ### Number A numeric field that accepts decimal values. You can optionally set a default value that pre-fills when a work item is created. ### Dropdown -A selection field backed by a list of options you define. When setting up the property, add your options under **Add options**. Each option can have a name and an icon. +A selection field backed by a list of options you define. When setting up the property, add your options under **Add options**. Each option can have a name and an icon, and options can be nested under a parent option. At least one option is required. -Choose **Single select** to let members pick one option at a time, or **Multi select** to allow multiple selections. +Choose **Single select** to let members pick one option at a time, or **Multi select** to allow multiple selections. You can mark one or more options as the default (a single-select property can have only one default, and a mandatory property cannot carry a default). ### Boolean @@ -116,21 +165,21 @@ A date picker field. You choose a display format for dates across this property: - `01/15/2025` - `2025/01/15` -The format you pick applies consistently to all work items using this property. +The format you pick applies consistently to all work items using this property, and can be changed at any time. ### Member picker -A people-selection field that lists all members of the project. Choose **Single select** to allow one member, or **Multi select** to allow several. +A people-selection field that lists the **members of the workspace**. Choose **Single select** to allow one member, or **Multi select** to allow several. Members selected through a member picker property are automatically added as subscribers to that work item, so they receive notifications for updates, comments, and status changes. ### Release picker -A field for linking a work item to one or more [releases](https://docs.plane.so/releases) in the project. Supports multi-select. +A field for linking a work item to one or more [releases](/releases) in the project. Supports multi-select. ### Rich text -A full document editor field. Unlike a plain text property, rich text supports formatting: headings, lists, code blocks, inline code, bold, italic, and embedded images. Each work item stores its own content for the field, and that content is versioned and searchable. +A full document editor field. Unlike a plain text property, rich text supports formatting: headings, lists, code blocks, inline code, bold, italic, and embedded images. Each work item stores its own content for the field, and that content is versioned and searchable. Content is sanitized on save, so scripts and unsafe HTML are removed. Rich text properties cannot be used to filter or group work items. ### URL @@ -140,15 +189,75 @@ A field for a single URL. Members enter a link to an external resource, like a d A computed, read-only field. You write an expression when setting up the property, and Plane evaluates it automatically for each work item. Members cannot edit the value directly; it always reflects the formula result. -Formulas can reference other properties on the work item and use conditional logic to produce a result. A few examples: +**Referencing fields.** Reference another property with double curly braces: `\{\{field_name\}\}`. Field names are matched case-insensitively and ignore spaces versus underscores, so `\{\{start_date\}\}`, `\{\{Start Date\}\}`, and `\{\{START_DATE\}\}` all resolve to the same field. A formula can reference Text, Number, Date, and Boolean properties on the same work item type, and cannot reference itself. + +**Result types.** A formula evaluates to a Number, Text, Date, or Boolean. + +**Operators.** + +- Arithmetic on numbers: `+ - * /` +- Dates: `\{\{end\}\} - \{\{start\}\}` gives the number of days; `\{\{date\}\} + 30` and `\{\{date\}\} - 7` shift a date. +- Text concatenation: `&` (numbers, dates, and booleans are converted to text automatically). +- Comparisons: `= != < <= > >=` (these return a Boolean). + +**Functions.** `IF(condition, true_value, false_value)`, `ROUND`, `ABS`, `UPPER`, `LOWER`, `LEN`, `CONCAT`, `TODAY()`, `NOW()`. + +**Examples.** Categorize by estimate size: -`{estimate_point} > 5 ? "Large" : "Small"` + +``` +IF(\{\{estimate_point\}\} > 5, "Large", "Small") +``` Flag high-priority items: -`{priority} == "HIGH" ? "Urgent: " + {name} : {name}` -Because the value is always derived, formula properties cannot be marked as mandatory. +``` +IF(\{\{priority\}\} = "HIGH", "Urgent: " & \{\{name\}\}, \{\{name\}\}) +``` + +Days remaining until a deadline: + +``` +IF((\{\{due_date\}\} - TODAY()) < 0, "OVERDUE", (\{\{due_date\}\} - TODAY()) & " days remaining") +``` + +**Behavior.** If any referenced value is empty, the result is empty (an `IF()` branch that is not taken can still reference an empty field safely). A runtime error, such as dividing by zero, shows an error state rather than a value. Because the value is always derived, formula properties cannot be marked as mandatory. + +## Scope properties with contexts + +By default, a property applies everywhere it is attached. **Contexts** let you narrow a property to specific projects and work item types, each with its own configuration, so the same property can behave differently depending on where it is used. + +When you first create a property, Plane creates a **default context** covering all projects and all types, so the property is visible everywhere it's attached. You then add more specific contexts as needed. + +With contexts you can, for example, make a "Severity" dropdown **mandatory** on the Bug type in one project but **optional** on the same type in another. For any work item, Plane resolves the effective setting from the **most specific matching context**, falling back to the property's own base setting when no context matches. + +Manage these from the property's **Manage contexts** option on the **Properties** tab. + +## Edit and delete a property + +### Edit a property + +> **Role**: Workspace Admin + +You can change a property's title, description, icon, mandatory state, active state, and default value at any time. + +:::warning Some changes lock once values exist +Once any work item has a value for the property, you **cannot change its property type, its single/multi-select setting, or its type-specific settings** (such as a dropdown's options). Those are only editable while no work item has used the property yet. Attempting to change them afterward is rejected. +::: + +Making a property mandatory later is allowed (except for the types that can't be mandatory). Existing work items that are missing the value will need it filled in the next time they are edited. + +### Delete a property + +> **Role**: Workspace Admin + +Deleting a property that already has values gives you a choice: + +- **Save values to work item descriptions** (recommended) — each affected work item keeps its value by appending it to the work item's description, with an activity entry recording the change, before the property is removed. +- **Delete the property and all its values** — removes the values along with the definition. This cannot be undone. + +The delete dialog shows how many work items, work item types, and projects across the workspace are affected. If you only want to stop using a property temporarily, turn it **inactive** instead of deleting it. ## Import types into a project diff --git a/docs/workflows-and-approvals/workflows.md b/docs/workflows-and-approvals/workflows.md index a15cead9..838a0629 100644 --- a/docs/workflows-and-approvals/workflows.md +++ b/docs/workflows-and-approvals/workflows.md @@ -30,7 +30,30 @@ If you already had a workflow configured before, it's now your project's default --> -## Turn on workflows +## Where workflows live depends on your plan + +Every plan builds workflows the same way, with the same states, flows, and conditions. What differs is **where** they are configured and **who** manages them. Find your setup below. + +| Plan / setup | Where you configure workflows | What you get | +| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Business** | Inside each project, under **Project Settings → Workflows** | One **default workflow** per project that governs all work items in it. | +| **Enterprise Grid** (project-managed) | Inside each project, under **Project Settings → Workflows** | Everything above, plus **approval flows**, **transition conditions**, and **multiple custom workflows** scoped to specific work item types. | +| **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** | Once for the whole workspace, under **Workspace Settings → Workflows** | Workflows are defined centrally by a workspace admin and applied to every project. Project admins no longer edit workflows inside a project; they choose from the workflows the workspace allows. | + +**In short** + +- If you're on **Business** or **Enterprise Grid without governance**, workflows live in **project settings**. Everything in [Set up workflows](#set-up-workflows) below is where you work. +- If your workspace has turned on **[Workspace Governance](/workspace-administration/workspace-governance)**, workflow management moves to the **workspace level**. You still build workflows the same way, but in workspace settings, and projects consume them within the limits you set. See [Workspace level workflows](#workspace-level-workflows). + +:::warning Turning on governance moves workflows to the workspace +Enabling workspace governance is a one-way change that relocates workflow management from individual projects to the workspace. Existing project workflows are migrated up and preserved. Read [Workspace Governance](/workspace-administration/workspace-governance) before enabling it. +::: + +## Set up workflows + +The rest of this section describes how to build and run a workflow. It applies whether you manage workflows in **project settings** or in **workspace settings** (Enterprise Grid with governance) - the builder is identical. Where a step differs at the workspace level, it's called out inline. + +### Turn on workflows Head over to your [Project Settings](https://docs.plane.so/core-concepts/projects/overview#configure-project-settings) and select **Workflows** from the sidebar. Toggle **Enable workflows** on at the top of the page. @@ -40,29 +63,37 @@ Once enabled, you'll see your project's default workflow listed with **Default** The workflows list includes a search bar to find workflows by name. You can also filter the list by status (Active or Inactive) and by work item type, and sort it by name, date created, or date modified in ascending or descending order. -## Define a workflow +::: warning **Enterprise Grid with governance** +There is no per-project **Enable workflows** toggle. Workflows are managed centrally under **Settings → Workflows** at the workspace level, and the workspace always has one default workflow. The list additionally shows how many **projects** and **work item types** use each workflow. +::: + +### Define a workflow Whether you're editing the default workflow or a type-specific one, the workflow detail page works the same way. It lists all the states included in the workflow and lets you add flows that control how work items move between them. -### Add states +#### Add states The default workflow includes all states configured in your project. When you create a new workflow, it starts empty. You choose which states to include by clicking **Add states** in the top-right corner of the "Define workflow" section. A panel lists all available project states grouped by category. Select the ones you need and click **Add selected**. ![Select states](https://media.docs.plane.so/workflows/select-states.webp#hero) -### Allow new work items +::: warning **Enterprise Grid with governance** +The states you add come from the workspace's shared [states](/core-concepts/issues/states#where-to-configure-states) catalog, not a project-specific list. +::: + +#### Allow new work items Each state has an **Allow new work items** toggle on the right side. When this is on, team members can create work items directly in that state. Turn it off for states that should only be reached through progression. ![Workflow states with allow new work items](https://media.docs.plane.so/workflows/allow-new-work-items.webp#hero) -### Add flows +#### Add flows Flows define the rules for moving a work item from one state to another. To add a flow, expand a state by clicking its arrow, then click **+ Add flow**. A panel appears on the right where you choose the flow type - **Transition** or **Approval** - then click **Next** to configure it. You can add multiple flows to a single state, but they must all be the same type - either all transitions or all approvals. -#### Transition flows +##### Transition flows A transition flow defines a permitted state change. When you add one, you configure three fields: @@ -75,7 +106,7 @@ A transition flow defines a permitted state change. When you add one, you config Click **Save** to confirm the flow, or **Discard** to cancel it. -#### Approval flows +##### Approval flows An approval flow adds a gate: the work item won't move forward until designated approvers accept or reject it. When you add one, you configure: @@ -83,40 +114,44 @@ An approval flow adds a gate: the work item won't move forward until designated - **on approve, move to** - the state the item moves to when approved. - **on reject, move to** - the state the item falls back to when rejected. - **by** - who can approve or reject. Defaults to **All**, but you can restrict it to specific members. -- **with** — optional conditions that run before or after the approval decision. See [Transition conditions](#transition-conditions) below. +- **with** - optional conditions that run before or after the approval decision. See [Transition conditions](#transition-conditions) below. + +::: warning **Enterprise Grid with governance** +The members you pick under **by** are **workspace** members. At the project level they are the project's members. +::: ![Approval flow](https://media.docs.plane.so/workflows/approval-flow.webp#hero) For example, you might add an approval flow on "Testing" so that moving to "Ready for Release" requires sign-off from a QA lead. If rejected, the item moves back to "In Development" for further work. -## Transition conditions +### Transition conditions Transition conditions let you attach custom logic to any transition or approval flow. They use [Plane Runner](/automations/plane-runner) scripts to validate whether a transition should proceed and to perform follow-up actions after it completes. -When you click the **Conditions** option in the "with" column of a flow, a panel opens on the right with two sections: +When you click the **Conditions** option in the "with" column of a flow, a panel opens on the right with two sections: **Pre validation** and **Post actions**. -### Pre-validation +#### Pre-validation -Pre-validation scripts run **before** a transition happens. They verify that the work item is ready to move — for example, checking that all required fields are filled, that an estimate exists, or that a linked document has been approved. +Pre-validation scripts run **before** a transition happens. They verify that the work item is ready to move - for example, checking that all required fields are filled, that an estimate exists, or that a linked document has been approved. If a pre-validation script returns `{ success: false }` or throws an error, the transition is blocked and the user sees an error message explaining why. If all pre-validation scripts return `{ success: true }`, the transition proceeds. -You can chain multiple pre-validation scripts — they run in the numbered order shown (#1, #2, etc.). All must pass for the transition to proceed. +You can chain multiple pre-validation scripts - they run in the numbered order shown (#1, #2, etc.). All must pass for the transition to proceed. **To add a pre-validation script:** 1. In the Conditions panel, under **Pre validation**, click **+ Select script**. 2. Choose an existing Runner script of type "Workflow Transition" from the list. -3. Or click **New Script** to create one inline — the script editor opens with the type pre-set to "Workflow Transition" and a template showing the return rules: - - `return { success: true }` — allow the transition. - - `return { success: false }` — block the transition. - - `throw new Error("reason")` — block the transition with a specific message shown to the user. +3. Or click **New Script** to create one inline - the script editor opens with the type pre-set to "Workflow Transition" and a template showing the return rules: + - `return { success: true }` - allow the transition. + - `return { success: false }` - block the transition. + - `throw new Error("reason")` - block the transition with a specific message shown to the user. 4. Click **Save and use** to save the script and attach it to the condition in one step. 5. Click **+ Add more** to chain additional pre-validation scripts. -### Post actions +#### Post actions -Post-action scripts run **after** a transition completes successfully. They handle follow-up work — posting a Slack notification, creating a linked work item in another project, adding a comment, updating a custom property, or calling an external API. +Post-action scripts run **after** a transition completes successfully. They handle follow-up work - posting a Slack notification, creating a linked work item in another project, adding a comment, updating a custom property, or calling an external API. Post-action scripts don't block the transition (it has already happened). If a post-action script fails, the transition still stands, but the error is logged in the script's execution history. @@ -126,7 +161,7 @@ Post-action scripts don't block the transition (it has already happened). If a p 2. Choose an existing Runner script or create one inline. 3. Click **+ Add more** to chain additional post-action scripts. -### Example: enforcing quality gates +#### Example: enforcing quality gates A common pattern is combining pre-validation and post-actions on a single transition: @@ -176,6 +211,10 @@ To create one: You'll land on the workflow detail page, where you can [define its states and flows](#define-a-workflow). +::: warning **Enterprise Grid with governance** +The workflow name must be unique across the workspace, and you attach workflows to work item types through **governance modes** rather than a simple type assignment. See [Workspace level workflows](#workspace-level-workflows). +::: + ## How workflows work Once a workflow is active, work items in the project follow its rules: @@ -195,3 +234,48 @@ When a work item reaches a state with an approval flow, it enters a pending stat **Workflow precedence** If a work item's type matches a type-specific workflow, that workflow's rules apply instead of the default. For example, if you have a type-specific workflow for bugs, any bug in the project follows that workflow's transition and approval rules. All other work item types continue to follow the default workflow. + +## Workspace level workflows + +On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** enabled, workflows are managed once for the entire workspace instead of project by project. A workspace admin builds a shared catalog of workflows under **Settings → Workflows**, and every project uses workflows from that catalog. Project admins no longer create or edit workflows inside a project; they choose from what the workspace allows. + +You build these workspace workflows exactly as described in [Set up workflows](#set-up-workflows) above. This section covers only what's different at the workspace level: the shared catalog, the default workflow, and how projects consume workflows. + +### The shared catalog and default workflow + +- All workflows live in one workspace-level catalog. Each is listed with its status (Active or Disabled), its states, and how many projects and work item types use it. +- The workspace has exactly **one default workflow**. It is the fallback for any project and work item type not bound to a more specific workflow, and it **cannot be deleted**. +- Workflow names must be **unique across the workspace**. + +### How projects use a shared workflow + +You control how much freedom each project has to pick its own workflow, set **per work item type** using a **governance mode**: + +| Mode | What a project admin can do | +| --------------- | ------------------------------------------------------------------------- | +| **Any** | Choose any active workspace workflow for that work item type. | +| **Constrained** | Choose only from an **allowlist** of workflows you approve for that type. | +| **Required** | No choice. One workflow is mandated, and every project uses it. | + +**Pins** - in **Any** or **Constrained** mode, you can **pin** a specific project to a specific workflow. This forces that one project's choice while leaving other projects free. Pins are unavailable in Required mode, and are removed automatically if a type is later switched to Required. + +**Effective workflow resolution** - for any project and work item type, the workflow that actually applies resolves in this order: + +1. The **required** workflow, if the type's mode is Required. +2. The project's **pin**, if one exists. +3. The project's own **choice**, if set. +4. Otherwise, the **workspace default workflow**. + +The effective workflow determines the starting states, which states allow creation, and the allowed transitions for work items of that type in that project. + +:::warning Switching a workflow can move work items +When a project's effective workflow changes - for example, because a type is set to Required - work items whose current state is not part of the new workflow are moved to a fallback state. Always review the preview before confirming a workflow change. +::: + +These controls are configured on the work item type. For the full details, see [Work item types](/work-items/workspace-work-item-types) and [Workspace governance](/workspace-administration/workspace-governance#how-projects-use-shared-workflows). + +### What project admins see + +From a project's work item type settings, a project admin sees, per type: whether the type is free to choose, **constrained** to an allowlist, **mandated** (required), or **pinned**; the current effective workflow and any workflows they may pick; and a **preview** of how existing work items would be remapped if they switch, before applying the change. + +If a project admin tries to change a workflow they are not allowed to change, they get an error explaining that the workflow is mandated by the workspace, assigned by the workspace (pinned), or outside the allowed list. diff --git a/docs/workspace-administration/workspace-governance.md b/docs/workspace-administration/workspace-governance.md new file mode 100644 index 00000000..b1707d05 --- /dev/null +++ b/docs/workspace-administration/workspace-governance.md @@ -0,0 +1,101 @@ +--- +title: Workspace Governance +sidebar_label: Workspace Governance +description: Centralize and standardize how projects are configured by managing states, workflows, work item types, and custom properties at the workspace level. +--- + +# Workspace Governance + +Workspace governance lets workspace admins define shared configuration once, at the workspace level, and have every project use it. Instead of each project defining its own states, workflows, and work item types, governance centralizes these so your projects stay consistent and comply with a standard you control. + +When governance is on, workspace admins own the shared building blocks. Project admins can use those building blocks, but cannot create or modify them independently. + +:::danger Enabling governance is permanent +Turning on workspace governance is a **one-way** change. It cannot be disabled or undone. Once enabled, project admins permanently lose the ability to create or edit states, workflows, work item types, templates, automations, and recurring work items inside their projects. Read this page in full before enabling. +::: + +## What governance centralizes + +Enabling governance lifts all of the following from the project level to the workspace level. Each has its own detailed page: + +- [**States**](/core-concepts/issues/states) - the shared set of states for the whole workspace, including a single workspace triage state. +- [**Workflows and approvals**](/workflows-and-approvals/workflows) - shared workflows that define how work items move between states. +- [**Work item types and custom properties**](/work-items/workspace-work-item-types) - defined once and rolled out to projects. +- [**Automations**](/automations/custom-automations#create-a-workspace-automation) - workspace-level automations. + +After governance is on, all of these are **workspace-managed**. Projects import and use them. + +## How governance works + +Governance is a **binding layer**, not a copy and not a blanket override. This is the single most important thing to understand: + +- Workspace configuration is **not duplicated** into each project. Projects **reference** the shared workspace resources. +- Governance does **not** force every project to look identical. It standardizes where you require it, and allows per-project flexibility where you permit it. +- For workflows specifically, each project resolves an **effective workflow** for each work item type. The workspace controls how much freedom a project has over that choice. See [How projects use shared workflows](#how-projects-use-shared-workflows). + +## Enable governance + +Governance moves through three states: **Disabled → Migration in progress → Enabled**. + +1. Go to **Settings → Workspace Governance**. +2. Click **Enable governance**. +3. Step through the migration wizard. It has one step for each kind of configuration being centralized: **states, work item types, workflows, templates, automations, and recurring work items**. Each step shows a preview of what will be migrated so you can review before committing. +4. Confirm to start the migration. + +### During migration + +While the migration runs, the workspace is temporarily **frozen for writes** so configuration can be moved safely and consistently. Requests to change configuration during this window are rejected until the migration completes. Do not plan configuration changes during the migration. + +### After migration + +When the migration finishes, the governance page shows a summary: **Status** (Enabled), **Enabled on** (date), **Enabled by** (the admin), and **Entities migrated** (counts). + +:::warning +The migration freeze makes the affected configuration temporarily read-only, and enabling cannot be reversed once it completes. Enable governance during a low-activity window. +::: + +## What changes for projects after governance is on + +- Project admins can no longer **create or edit** states, workflows, work item types, templates, automations, or recurring work items inside a project. Editing one returns a "managed at the workspace level" error. +- Projects **use** the workspace's shared configuration instead. +- **New projects** created after governance is on automatically use the workspace's shared configuration, resolving to the workspace **default workflow** for each work item type unless the workspace mandates or pins a different one. +- Work item types are enabled workspace-wide as part of governance. + +## How projects use shared workflows + +You control how much choice a project has over which workflow applies to each work item type. This is set **per work item type**, using a **governance mode**: + +| Mode | What a project admin can do | +| --------------- | -------------------------------------------------------------------------- | +| **Any** | Choose any active workspace workflow for that work item type. | +| **Constrained** | Choose only from an **allowlist** of workflows you define for that type. | +| **Required** | No choice. The workspace mandates one workflow, and every project uses it. | + +### Pins + +In **Any** or **Constrained** mode, you can **pin** a specific project to a specific workflow. This forces that one project's choice while leaving other projects free to choose. Pins are removed automatically if the type is later switched to Required. + +:::warning Setting a type to Required overrides all projects +Switching a work item type to **Required** locks every project to the single mandated workflow. Any project currently using a different workflow is moved to the mandated one, and existing per-project pins for that type are removed. Preview the impact before switching. +::: + +### Effective workflow resolution + +For any project and work item type, the workflow that actually applies (the **effective workflow**) is resolved in this order: + +1. The project's **required** workflow, if the type is Required. +2. The project's **pin**, if one exists. +3. The project's **chosen** workflow (its pick), if set. +4. Otherwise, the **workspace default workflow**. + +The effective workflow determines the starting state, which states allow creation, and the allowed transitions for work items of that type in that project. + +### The project admin's view + +From a project's work item type settings, a project admin sees, per type: a label showing whether the type is free to choose, **constrained** to an allowlist, **mandated** (required), or **pinned**; the current effective workflow and any workflows they may pick; and a **preview** of how existing work items would be remapped if they switch workflow, before applying the change. + +If a project admin tries to change a workflow they are not allowed to change, they get an error: the workflow is mandated by the workspace, assigned by the workspace (pinned), or outside the allowed list. + +:::warning Switching a workflow can move work items +When a project's effective workflow changes, work items whose current state is not part of the new workflow are moved to a fallback state. Always review the preview before confirming a workflow change. +:::