Workflow Mapping — the one setup step that matters
Workflow Mapping is the bridge between your Azure DevOps states and the analytics engine. Every cycle-time, flow-efficiency, aging, WIP and forecast number is computed from it. Get this right once and every dashboard becomes accurate for your team — without changing how you work.
The big idea
Every team runs Azure DevOps a little differently — out-of-the-box Scrum, the Agile template, or a rich custom board with states like Ready To Test and Ready To Accept. Agile Analytics does not force you onto a fixed process.
Instead it defines six canonical stages that describe the universal shape of delivery work. You tell it which of yourstates belong in each stage. From then on, the engine speaks your language — it knows when work “starts,” when it’s “waiting,” and when it’s “done,” whatever you call those states.
- Newbacklog
- Queuedcommitted, not started
- In Progressactive work
- Testin QA
- Reviewin review / acceptance
- Complete / Donedelivered / closed
You can map your states two ways — let the tool auto-detect them, or map them by hand— and any stage your team doesn’t use can be marked N/A.
The six stages, defined
Three of these — In Progress, Test and Review— are the “active work” stages. New and Queued are pre-work; Done is post-work.
On the backlog, not yet committed to a sprint. Excluded from all delivery metrics.
Typical states: New, Approved, Proposed, To Do
Committed to the sprint / ready to start, but work has not begun.
Typical states: Committed, Ready, Approved
Active development — someone is working on it. This is where the cycle-time clock starts.
Typical states: In Progress, Active, Doing
Development is done; the item is in QA / testing (e.g. PR merged, awaiting test).
Typical states: Ready To Test, Testing, In QA
Passed test; awaiting review or product acceptance.
Typical states: Ready To Review, Ready To Accept, Resolved
Delivered, accepted, or closed. This is where the cycle-time clock stops.
Typical states: Done, Ready To Release, Closed, Resolved
How your states become metrics
This is the part worth understanding — it determines what every number on your dashboards means.
first In Progress → first DoneThe clock starts the moment an item first enters any state you mapped to In Progress, Test or Review (an "active" stage) and stops when it first reaches a Done state. Time in New or Queued is excluded — it counts as pre-work. Cycle time measures active delivery time, from first touch to done.
created → first DoneThe full elapsed time from when the work item was created in Azure DevOps to when it reached Done. It includes all waiting (backlog + queue), so it is always greater than or equal to cycle time. Use it to answer "how long from request to delivery?"
active time ÷ total cycle timeTime in active stages (In Progress + Test + Review) divided by total cycle time (active + waiting). A low number means work is sitting idle between stages. Items in Queued count as waiting; New and Done are excluded.
items currently in an active stageCounts items currently in In Progress, Test or Review. Items still in Queued are not counted as WIP — they are committed but not started.
lane-entry → todayOn the Aging board, each item shows how long it has sat in its current stage. This is how you spot work that is stuck.
reaches a Done stateThroughput, commitment reliability, carryover and scope churn are sprint-scope metrics. The only workflow-mapping dependency is the Done stage: an item counts as completed when it reaches a state you mapped to Done.
- Newstates are backlog — excluded from cycle time, lead time, flow efficiency, WIP and throughput. They shouldn’t move your delivery numbers.
- Cancelled work (the ADO
Removedstate) is treated as out-of-flow and left unmapped, so it doesn’t inflate throughput — unless you deliberately map it to Done.
Two ways to set it up
Let the tool detect it
On first open, Agile Analytics auto-detects a mapping by reading your project’s real states and state categories. It recognises hundreds of common patterns across Scrum, Agile, CMMI and Basic — including custom and non-English state names — maps the coarse shape automatically, and surfaces anything it couldn’t place. It only ever seeds an empty mapping; it will never overwritea mapping you’ve edited yourself.
Map your states by hand
In Configuration → Workflow Mapping, each stage has a state dropdown, an “Add custom state…” box, “Use Suggested” (sensible defaults) and “Clear.” Mix both: start from “Use Suggested,” then adjust to match your board exactly.
If you don’t track Test or Review separately, choose “— N/A (this stage is not used) —.” N/A stages read 0 on the dashboards and don’t raise warnings. Every stage must contain at least one state or be explicitly N/A. A live preview shows exactly which states start and stop the cycle-time clock before you save.
Recommended mappings by process
Starting points for the four standard Azure DevOps processes and a rich custom board. In Progressis where the cycle-time clock starts; anything in New/Queued is pre-work. Adjust to your team’s reality — these are starting points, not rules.
Scrum
New, Approved, Committed, Done, Removed
| Stage | Map these states |
|---|---|
| New | New, ApprovedBacklog — not counted. |
| Queued | CommittedOnly if work does not start immediately on commit. |
| In Progress | (none by default)See note below. |
| Test | N/A |
| Review | N/A |
| Complete / Done | Done |
| (cancelled) | Removed → leave unmappedTreated as cancelled. |
Out-of-the-box Scrum has no "in progress" state; work goes straight from Committed to Done. To get a meaningful cycle time you have two choices: (1) add a board state like "In Progress" and map it to In Progress (recommended for richer flow metrics); or (2) if Committed effectively means "work has started," map Committed → In Progress instead of Queued. Cycle time then runs committed → done, which is usually what Scrum teams expect.
Agile
New, Active, Resolved, Closed, Removed
| Stage | Map these states |
|---|---|
| New | New |
| Queued | N/A (or a custom "Ready/Committed" state) |
| In Progress | Active |
| Test | N/A (or a custom test state) |
| Review | Resolved |
| Complete / Done | Closed |
| (cancelled) | Removed → leave unmapped |
CMMI
Proposed, Active, Resolved, Closed, Removed
| Stage | Map these states |
|---|---|
| New | Proposed |
| Queued | N/A (or a custom committed state) |
| In Progress | Active |
| Test | N/A |
| Review | Resolved |
| Complete / Done | Closed |
| (cancelled) | Removed → leave unmapped |
Basic
To Do, Doing, Done
| Stage | Map these states |
|---|---|
| New | To DoOr split backlog vs committed into New / Queued if you distinguish them. |
| Queued | N/A |
| In Progress | Doing |
| Test | N/A |
| Review | N/A |
| Complete / Done | Done |
Rich custom board
The reference mapping we recommend for a full SDLC flow.
| Stage | Map these states |
|---|---|
| New | New, Approved |
| Queued | Committed |
| In Progress | In Progress, Active |
| Test | Ready To TestDev done, PR merged, awaiting QA. |
| Review | Ready To Review, Ready To Accept, ResolvedQA done, awaiting product acceptance. |
| Complete / Done | Done, Ready To Release, Closed |
| (cancelled) | Removed → leave unmapped |
Don’t have all these states? That’s exactly what N/A is for. Map the states you do have, mark the rest N/A, and the dashboards adapt. You can also create these states on your board and adopt them over time — the mapping makes either path work.
Special cases
Type them into the "Add custom state…" box on the relevant stage. Anything goes; the engine matches on your exact state names.
Auto-detection recognises common state names in nine languages: English, Spanish, Portuguese, Italian, German, French, Polish, Dutch and Swedish. (The extension interface itself is available in six languages; workflow-mapping detection covers the wider set so it can read state names however your ADO is configured.)
Mappings are stored per project. Auto-detection seeds your first project; add the others from the same screen ("Add a project mapping").
You can give different item types (e.g. Bug vs User Story) their own mapping if their workflows differ. A general mapping applies to anything you have not given a specific one.
Auto-detection treats the Removed state as cancelled and leaves it unmapped, so it does not inflate throughput. Only map it to Done if you genuinely consider removed items "done."
The mapping is saved at the organisation level; an Azure DevOps organisation admin confirms and saves it. Once saved, it applies for everyone on your team.
Step-by-step setup
- 1Open Workflow Mapping
In the extension, go to Configuration → Workflow Mapping.
- 2Review the auto-detected mapping
Each of the six stages shows the states currently mapped to it. You can start from this or start fresh.
- 3Match your board
For each stage, use the dropdown, "Use Suggested," or "Add custom state…" to match your board. Mark unused stages N/A.
- 4Check the live preview
Watch the "Your cycle time is calculated from these states" preview — confirm the start states (In Progress / Test / Review) and end states (Done) are what you expect.
- 5Resolve unmapped states
Clear any unmapped states flagged in the banner — states the tool found on your items but you have not placed yet.
- 6Save
Click Save. Your dashboards repopulate immediately.
Verifying it worked
- The Cycle Time card shows a Data Quality chip (High / Medium / Low) based on how many completed items backed the numbers. Low usually means the mapping needs adjusting or there is not enough completed history yet.
- If a chart is empty, the tool tells you why: "Workflow Mapping isn’t set yet," "We couldn’t find any completed items" (mapping likely needs adjusting), or "You’re all set — waiting for completed work" (mapping is good, just no completed items yet).
- Spot-check a few recently completed items: their cycle time should match first-active → done on your board.
FAQ
No. Map the states you already have. The tool adapts to your process, not the other way around.
Re-open Workflow Mapping, add or adjust the states, and save. New unmapped states are flagged automatically.
Because time in Queued (committed-but-not-started) is excluded. If you want that time included, map your committed/working state to In Progress (see the Scrum note above).
Mappings are per project (and optionally per work-item type), so different projects can map differently.
Need help?
Our support team is available Monday through Friday, 9 AM to 5 PM Pacific Time.