Before you begin
OutcomeMap is an Azure DevOps extension. You'll need an ADO project before anything else. Here's the quick checklist:
- An Azure DevOps organisation (free at dev.azure.com)
- At least one ADO Project with Boards enabled
- Project Administrator permission (or higher) to install extensions
- A process template that supports custom work item types — Agile, Scrum, or CMMI all work. Inherited processes are recommended.
- Modern browser — Chrome, Edge, or Firefox (latest)
Work Item Types you need in ADO
OutcomeMap uses your standard ADO work item hierarchy. Here's how the app's concepts map to ADO work item types — and which ones are required vs. optional.
OutcomeMap hierarchy at a glance
Recommended custom fields to add to Epics & Features
These are optional but significantly improve OutcomeMap's reporting quality. Add them via ADO → Organisation Settings → Process → [Your process] → Work item types.
| Field name | Type | Apply to | Why add it |
|---|---|---|---|
| Target Date | Date/Time | Epic, Feature | Recommended Drives Gantt bars on the roadmap view |
| Start Date | Date/Time | Epic, Feature | Recommended Sets the left edge of timeline bars |
| OKR Score | Integer (1–10) | Feature | Optional Enables confidence scoring on Key Results |
| Priority | Picklist (1–4) | Epic, Feature | Optional Used in Portfolio sorting and filtering |
Install OutcomeMap
-
Go to the Visual Studio Marketplace
Visit marketplace.visualstudio.com and search for OutcomeMap, or use the direct link below.
-
Click "Get it free"
You'll be prompted to sign in with your Microsoft / Azure DevOps account if you haven't already.
-
Select your Organisation
Choose which ADO organisation to install OutcomeMap into. You can add it to more organisations later from the Marketplace.
-
Click "Install"
The extension is installed at the organisation level. All projects in the org can now use OutcomeMap — no per-project installation needed.
-
Navigate to your project → Boards
In your ADO project, look for the OutcomeMap entry in the left sidebar under Boards, or use the direct hub link:
Hub URL patternhttps://dev.azure.com/{your-org}/{your-project}/_apps/hub/outcomemet.outcomemap.outcomemap-hub -
Grant permissions if prompted
OutcomeMap needs read/write access to your project's work items and Extension Data. Click Accept on the permissions dialog — this is how it saves plans and settings.
Create your first Plan
A Plan in OutcomeMap maps to an Epic in Azure DevOps. Think of it as a roadmap container — it holds your objectives, key results, milestones, and timeline in one place.
-
Open OutcomeMap in your project
Click the OutcomeMap icon in the Boards sidebar. You'll land on the Plans screen.
-
Click "+ New Plan"
A dialog will appear. Enter a descriptive name — e.g. "Q3 2026 Product Roadmap" or "Platform Modernisation".
-
Set the Plan timeframe
Pick a Start Date and End Date for the plan. This sets the default time window for the Gantt roadmap view. You can always extend it later.
-
Choose an Area Path (optional)
If your ADO project uses Area Paths to separate teams, select the relevant area. OutcomeMap will only show work items from that area by default.
-
Click "Create Plan"
OutcomeMap creates an Epic in ADO and saves the plan metadata. You'll be taken directly into the plan editor.
Plan settings you can configure
| Setting | What it does |
|---|---|
| Plan name | Display name — also updates the linked Epic title in ADO |
| Date range | Controls the default zoom level on the Gantt roadmap |
| Terminology | Switch between "Plan/Outcome" or "Roadmap/Epic" labelling across the UI |
| Area Path filter | Scope the plan to a specific team area — great for multi-team orgs |
| Iteration filter | Optionally restrict to a specific sprint or iteration path |
| Theme | Light or dark — per-user preference, saved to your browser |
Setting up Outcomes / OKRs & Milestones
OutcomeMap structures strategy into a clear hierarchy: Outcomes (the strategic goal), Key Measures (how you'll know it's working), Initiatives (the bodies of work), and Epics → Features (the delivery). Here's how to build it out.
Adding Outcomes
-
Open your Plan and go to the Outcomes tab
Click your Plan name to open it, then select the Outcomes tab in the plan navigation bar.
-
Click "+ Add Outcome"
Give it a clear strategic goal name. e.g. "Grow enterprise revenue" or "Delight users in the first 30 days".
-
Add Key Measures under each Outcome
Click + next to an Outcome to add Key Measures. Each Key Measure should be specific and measurable: e.g. "ARR increases from £2M to £3M by Q4".
-
Add Initiatives under each Key Measure
Initiatives are the programmes of work that move the measure. e.g. "Enterprise onboarding overhaul". Click + under a Key Measure to add one.
-
Link Epics and Features to Initiatives
Inside each Initiative, click "Link work items" to attach existing ADO Epics or Features. Their completion rolls up automatically to Initiative and Key Measure progress.
Setting up Milestones
Milestones mark key dates on your roadmap — launches, reviews, external deadlines. They appear as diamond markers on the Gantt view.
-
Open the Milestones tab
Click Milestones in the plan navigation.
-
Click "+ New Milestone"
Enter a name, target date, and optional description. e.g. "Beta launch — 1 May 2026".
-
Set milestone status
Mark milestones as On Track, At Risk, or Delayed. These statuses appear as colour-coded markers on the roadmap and in the portfolio dashboard.
-
Add comments to milestones
Use milestone comments to log progress notes or blockers — great for stakeholder updates. Comments are visible to all plan members.
Using the Roadmap (Gantt) view
The Roadmap view shows your plan as an interactive Gantt chart. Each row is a Feature or Story; bars represent start-to-target-date spans. Milestones appear as diamonds.
Navigating the Roadmap
- Zoom: Use the timeline zoom controls (Day / Week / Month / Quarter) in the top-right to change the time scale
- Drag bars: Drag a Gantt bar left or right to update the work item's start or target date — it saves back to ADO instantly
- Resize bars: Drag the right edge of a bar to extend or shorten the end date
- Expand/collapse: Click the arrow next to a Feature to toggle its child Stories on the timeline
- Today line: A vertical line marks today's date — use it to see what's on track vs. slipping
- Colour coding: Bars are coloured by status — grey (not started), blue (in progress), green (done), red (overdue)
Getting dates on your items
Gantt bars only appear when a work item has both a Start Date and a Target Date. You can set these in three ways:
-
Set dates directly in OutcomeMap
Click on any Feature or Story in the roadmap list on the left to open a side panel. Set dates there without leaving the app.
-
Use iteration/sprint mapping
If your stories are assigned to ADO iterations (sprints), OutcomeMap can derive their dates from the sprint start and end dates automatically. Enable this in Plan Settings → Date source → Use iteration dates.
-
Set dates in ADO
You can also set the
Start DateandTarget Datefields directly in the ADO work item form — OutcomeMap will pick them up on the next refresh.
Portfolio Dashboard
The Portfolio Dashboard gives leadership a single view across every plan in the project. It shows milestone status, OKR health, plan progress, and cross-plan dependencies without needing to drill into each plan individually.
Milestone status roll-up
See all milestones across all plans, colour-coded by on track / at risk / delayed status.
Plan progress bars
Each plan shows a % complete bar based on the ratio of done vs total work items.
Dependency warnings
Cross-plan dependencies that are at risk surface automatically as warnings on the dashboard.
OKR confidence scores
If you've set OKR Scores on Key Results, the portfolio shows aggregate confidence across all objectives.
Accessing the Portfolio
-
Click "Portfolio" in the OutcomeMap top navigation
The portfolio view is available from any plan — it's always a click away at the top of the app.
-
All plans appear automatically
Every plan you've created in the project appears as a card. No configuration needed.
-
Click any plan card to drill in
Clicking a card takes you straight to that plan's roadmap view.
F11) and use the plan cards as talking points.
Tips, tricks & best practices
Name plans consistently
Use a format like Q3 2026 — [Team] so the portfolio view is easy to scan at a glance.
Sync frequently
OutcomeMap reads live from ADO. Keep your ADO work items updated (state, dates) and the roadmap stays accurate automatically.
Use Area Paths per team
For multi-team orgs, give each team their own Area Path and filter plans to that area — keeps roadmaps focused.
Export to image
Use your browser's print-to-PDF or screenshot tool to export roadmap views for presentations or email updates.
Review milestones weekly
Build a habit of updating milestone status each week. Even a quick "on track" check keeps the portfolio accurate.
Archive completed plans
Done with a quarter's plan? Close the linked Epic in ADO to remove it from active views — you can still find it in ADO history.
Clearing the session cache
If the app seems to be showing stale licence or plan data, clear the session cache from your browser console:
sessionStorage.removeItem('outcomemap_licence_cache')
location.reload()
Checking the running version
window.__outcomemap_version
window.__outcomemap_UI_ERRORS__ for recent error logs. Include these when contacting support — it speeds up diagnosis significantly.