Workflow mapping is the step that tells Agile Analytics which of your board states mean "queued", "active", "blocked", and "done". Get it right and cycle time, throughput, aging, and sprint completion all line up with reality. It used to be the one thing you had to configure before the numbers could be trusted. Now the extension does the first pass for you — automatically — the moment you open the hub.
What automatic mapping does
When Agile Analytics loads a project that has never been configured, it reads the states your teams actually use and proposes a sensible mapping in the background. It leans on the state category Azure DevOps already assigns to every workflow state — Proposed, In Progress, Resolved, Completed, Removed — so the result reflects how work flows, not how a label happens to be spelled.
- It discovers every state in use across the project, including custom ones like Ready for Dev, In Test, or Waiting for Review.
- It places each state into the right stage using the underlying Azure DevOps state category as the starting point.
- It saves that mapping automatically, so the dashboard is meaningful the first time you open it — no blank screens, no "configure me first" wall.
It never overwrites a mapping you saved
Automatic mapping is a helping hand, not a hijack. If you (or another admin) have already saved a workflow mapping for a project, the extension leaves it exactly as you set it. Auto-discovery only fills in the gap when no mapping exists yet, so a deliberate configuration is always safe.
How to review and fine-tune it
Automatic mapping gets most teams to accurate numbers immediately, but you stay in control. Open Workflow Mapping in the extension settings to see exactly how each state was placed, and adjust anything that does not match how your team really works.
- Open Settings, then Workflow Mapping, to see every state and the stage it was assigned.
- Move any state that the automatic pass placed differently from how your team treats it — for example, if "Ready for Test" should not count as done.
- Save, reload the dashboard, and sanity-check one recent sprint against an outcome you already know.
A quick health check for admins
Because mapping quality drives every flow metric, admins get a mapping-health summary that flags states which still need a human decision — typically unusual custom states the automatic pass could not categorise with confidence. It is the fastest way to confirm a new project is reporting on a solid foundation before you share the dashboard more widely.
When you should still map by hand
Automatic mapping handles the common cases well. The times to step in are when a team uses a custom state in a non-obvious way — a "Done" state that really means "code complete, not yet verified", or a late-stage state that the team treats as still active. In those cases the manual workflow-mapping guide walks through the five-stage model and the mistakes to avoid.
Related: Workflow mapping for accurate Azure DevOps analytics · Azure DevOps reporting solution overview
The short version: you no longer have to configure mapping before you can trust a single chart. Open the hub, get accurate cycle time and throughput straight away, and refine the mapping only where your workflow is genuinely unusual. Automatic workflow mapping is live now — install or update Agile Analytics from the Visual Studio Marketplace to use it.