> For the complete documentation index, see [llms.txt](https://portavi.gitbook.io/portavi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://portavi.gitbook.io/portavi-docs/tracking-delivery/custom-flags.md).
# Custom flags
Custom flags let you decide what else counts as a flagged item, on top of the [built-in rules](/portavi-docs/tracking-delivery/flagged-items.md). Each has a name, a colour and an icon of your choosing, and one condition. A flag such as **QA rejection** catches a task that moves from QA back to To do; **Blocked** catches a task labelled `blocked`.
Custom flags appear wherever flagged items do: as a badge in the project's flagged list, in the Flagged items card's breakdown, in the Pulse's Signals view and in My Focus. They count towards the flag-count [health threshold](/portavi-docs/tracking-delivery/health-statuses.md) the same way built-in flags do.
## Workspace flags and project flags
There are two kinds, and they differ only in where they apply.
* **Workspace flags** run on every project. PMO managers manage them in **Settings → Flagged items**.
* **Project flags** run on one project. The project's manager, or a PMO manager, manages them in the project's **Edit project** dialog.
Each workspace flag shows how many projects it is on in. Open its **⋯** menu and choose **See where it's off** to list the projects that have switched it off.
## Creating a flag
Select **Add flag**, give it a name, choose a colour and an icon, and pick what raises it. The badge preview shows how it will look.
The colours are a fixed set chosen to stay readable in both light and dark mode, so a flag never ends up as pale text on a pale badge.
### Status changes
Flags a task when it moves from one status to another. **From** and **To** each take as many statuses as you like.
* **Status groups** come first: To do, In progress and Done. A group covers every status in it, whatever your boards call them, which is what makes one workspace flag work across tools and teams.
* **Statuses** come next: the project's own, or for a workspace flag, every project's, with how many projects use each.
* **A status that hasn't synced yet** can be typed in the search and added with **Use "…" as a status**.
* Leave **From** empty to flag a move from any status.
* **To** never offers Done. A flag clears when its task is done, so a move into Done would clear itself straight away.
Portavi notices a move by comparing each sync with the one before. If a task goes QA → In progress → To do between two syncs, it is seen as QA → To do.
### Tags or labels contain
Flags a task whose tags contain a keyword. The field takes your tool's own name: **Labels** on Jira, GitHub and Microsoft Planner, **Tags** on Asana, ClickUp, Azure DevOps and Monday. Wrike has no tags, so this condition is not offered on Wrike projects, and a workspace tag flag says how many projects it can't run on.
### Title contains
Flags a task whose title contains a keyword, such as `hotfix` or `urgent`.
### Task type contains
Flags a task whose type contains a keyword: `bug` catches every Bug, `sub-task` every Sub-task. The type is your tool's own: the issue type on Jira and GitHub, the work item type on Azure DevOps, the task type on ClickUp, the custom item type on Wrike. Asana, Monday and Microsoft Planner have no task types, so this condition is not offered on their projects, and a workspace type flag says how many projects it can't run on.
### Keywords and matching
The three keyword conditions work the same way:
* Type a keyword and press **Enter**. Any one keyword is enough, and case is ignored.
* **Whole word** matches the keyword on its own: `fix` matches "Fix login" but not "hotfix", and `blocked` matches the tag `blocked-by-vendor` but not `unblocked`.
* **Anywhere** matches it inside a longer word too: `fix` also matches "hotfix".
**Matches now** shows how many open tasks the condition would flag today, before you save. A status-change flag has no such count, because it only sees moves from the moment it is saved.
## When a flag clears
A custom flag records that something happened, so it stays until one of three things:
1. **The task is done.**
2. **You edit the flag's condition.** Everything it has raised clears and it starts again. Portavi asks first, and says how many tasks that is. Renaming a flag or changing its colour or icon clears nothing.
3. **The flag is deleted**, or switched off for that project.
Removing the label, or rewording the title, does not clear it. That is deliberate: a task that was blocked last week is still worth a look until it is finished.
## On a project
In **Edit project**, the **Flagged items** section starts with the [built-in rules](/portavi-docs/tracking-delivery/flagged-items.md), marked **Built-in**: High priority to do and Past due on every project, and Cycle time exceeded on Kanban projects. They always run, so they have no switch. Below them come the workspace flags with a switch for each, then the project's own flags. Changes here save as you make them, separately from the dialog's **Save changes**.
* **Switch a workspace flag off** if it doesn't suit the project. Its items on the project clear.
* **Add flag** creates a flag for this project only.
* A PMO manager can open a project flag's **⋯** menu and choose **Make it a workspace flag**, so a flag that works well on one project runs on all of them.
On the project's Overview tab, custom flags sit beside the built-in reasons, each in its own colour:
