OutcomeMap — Full Setup & User Guide

1. Prerequisites

OutcomeMap is an Azure DevOps extension. Before installing, make sure you have the following in place.

• ✓
  An Azure DevOps organisation — free at dev.azure.com
• ✓
  At least one ADO Project with Boards enabled
• ✓
  Project Administrator or Organisation Administrator permission to install extensions
• ✓
  An inherited process template — Agile, Scrum, CMMI, or Basic (inherited copies work best for custom WITs)
• ✓
  Modern browser — Chrome, Edge, or Firefox (latest)

2. ADO Setup

OutcomeMap reads directly from your ADO work items. For the integration to work, your ADO project must have the right work item types and parent/child links configured.

2a. Process template

OutcomeMap works with any ADO process template. The recommended approach is to create an inherited process based on Agile or Scrum, then add custom work item types to it.

1. Go to Organisation Settings → Process

   Navigate to https://dev.azure.com/{your-org}/_settings/process

2. Create an inherited process

   Click the ⋯ next to Agile (or Scrum) → Create inherited process. Name it e.g. "OutcomeMap Process".

3. Apply it to your project

   Go to your project → Project Settings → Overview → change the process to your new inherited process.

2b. Work item types

OutcomeMap maps its hierarchy levels to ADO work item types. You need to create custom WITs for any levels you want to use. Only Outcome (or Objective) is strictly required — all other levels are optional.

Creating a custom WIT (e.g. Outcome)

1. Go to Organisation Settings → Process → [Your process]

   Click your inherited process name.

2. Click "New work item type"

   Enter the name (e.g. Outcome), choose an icon and colour. Click Create.

3. Repeat for each level you need

   Create Key Measure, Initiative — or skip any you don't want in your hierarchy.

2c. Parent/child links

OutcomeMap uses ADO's native parent/child hierarchy links to build the tree. Each level must be configured as a child of the level above in your process template.

1. Go to your process → Backlog levels

   In Organisation Settings → Process → [Your process] → Backlog levels

2. Add each custom WIT to the correct backlog level

   Outcome should be at the Portfolio backlog level (above Epic). Key Measure and Initiative sit between Outcome and Epic. Add each WIT to the appropriate level so ADO creates the parent/child links.

3. Verify links in ADO

   Create a test Outcome work item and try adding a child — you should see your custom types as child options.

2d. Teams & area paths

OutcomeMap assigns work items to teams using ADO area paths. Each team must have at least one area path configured.

1. Go to Project Settings → Teams

   Select a team → Areas tab.

2. Assign an area path to each team

   Make sure each team has at least one area path. Work items in that area will be assigned to that team in OutcomeMap.

3. Set work item area paths

   In ADO, make sure your Outcome, Initiative, Epic and Feature work items have their System.AreaPath set to match a team's area. OutcomeMap uses this to route items to the right team panel.

3. Install OutcomeMap

OutcomeMap installs from the Visual Studio Marketplace in about 2 minutes.

1. Visit the Marketplace

   Go to marketplace.visualstudio.com and search for OutcomeMap, or use the direct link.

2. Click "Get it free"

   Sign in with your Microsoft / Azure DevOps account if prompted.

3. Select your organisation

   Choose which ADO organisation to install into. The extension installs at organisation level — all projects in the org get access.

4. Click "Install"

   Approve the permissions dialog. OutcomeMap needs read/write access to work items and Extension Data.

5. Open OutcomeMap in your project

   Navigate to your ADO project → Boards → OutcomeMap in the left sidebar. Or use the direct hub URL:

   Hub URL

   https://dev.azure.com/{org}/{project}/_apps/hub/outcomemet.outcomemap.outcomemap-hub

4. Settings page

Before syncing work items, configure OutcomeMap's Settings to match your ADO process. Settings are stored per-project in ADO ExtensionData. Access them via the ⚙️ Settings icon inside OutcomeMap.

Hierarchy chain

Choose which levels exist in your hierarchy and their order. This must match the parent/child structure in your ADO process template.

WIT name mapping

Maps each OutcomeMap level to the exact ADO work item type name. Must match the WIT name in your ADO process exactly (case-sensitive).

Framework & terminology

Changes all UI labels throughout the app. Does not affect stored data — only what you see on screen.

ADO sync settings

Milestone source

5. Flexible hierarchy

OutcomeMap's hierarchy is fully configurable. You can remove levels, reorder them, and map them to any ADO work item type name. Only Outcome (or Objective) is required — everything else is optional.

Full hierarchy (all levels)

Built-in presets

OutcomeMap includes common hierarchy presets you can apply in Settings with one click:

Configuring a custom chain

To set up Outcome → Initiative → Epic → Feature (skipping Key Measure):

1. In ADO — verify your WIT parent/child links

   Make sure Initiative is configured as a child of Outcome (not Key Measure) in your ADO process backlog levels. OutcomeMap reads ADO's Hierarchy-Reverse relations — if ADO doesn't link them, OutcomeMap can't either.

2. Open OutcomeMap → Settings (⚙️)

   Click the settings icon in the top-right of the app.

3. Under Hierarchy — click × next to "Key Measure"

   This removes it from the active chain. The chain should now show: Outcome → Initiative → Epic → Feature.

4. Verify WIT names match your ADO types

   In the WIT mapping section, make sure "Initiative" matches your exact ADO work item type name.

5. Save settings and refresh the plan

   Click Save. OutcomeMap will re-sync using the new chain — querying only for Outcome, Initiative, Epic, Feature, and Milestone work items.

6. Creating your first plan

A Plan is OutcomeMap's top-level container — it holds your outcomes, initiatives, milestones, and roadmap for a given period or programme.

1. Click "+ New plan" on the Plans screen

   You'll see this when you first open OutcomeMap.

2. Enter a plan name

   e.g. "Q3 2026 Programme Roadmap" or "Capital Delivery Programme 2026".

3. Set RAG status

   Choose Auto (computed from milestones), or set a manual override.

4. Configure ADO sync

   Enable or disable ADO sync. Set sync mode (Auto or Manual). For POL-only plans, disable ADO sync.

5. Add teams (optional at this stage)

   Select an ADO project and team, then click Add team. You can add multiple teams from different projects. Teams can also be added later by editing the plan.

6. Click "Create plan"

   OutcomeMap creates the plan and, if ADO sync is enabled, immediately pulls work items from ADO for the selected teams.

7. Adding teams

Teams in OutcomeMap map to ADO teams. Each team's work items appear in a separate section of the roadmap panel, colour-coded for clarity.

How team assignment works

When OutcomeMap syncs, it fetches all work items matching your hierarchy chain types. It then assigns each work item to a team by matching the work item's Area Path against each team's configured area paths in ADO.

Adding a team to a plan

1. Edit the plan

   Click the plan's ⋯ menu → Edit plan.

2. Select ADO project and team

   Use the dropdowns to select the project and team.

3. Click "Add team"

   The team appears in the Teams in this plan list. You can add multiple teams from different projects.

4. Save the plan

   Click Save. OutcomeMap re-syncs and pulls work items for all selected teams.

Team colours

Each team gets a colour assigned automatically. Gantt bars and tree rows are colour-coded by team so you can tell at a glance which team owns each item. Colours can be customised in the team settings.

8. Outcomes / OKRs & Milestones

Once your plan is set up and teams are added, OutcomeMap pulls your strategic hierarchy from ADO automatically. Items in the tree reflect the parent/child structure in ADO.

Understanding the tree panel

The left panel shows your hierarchy as a tree — Outcomes at the top, with Key Measures, Initiatives, Epics and Features nested below. Each row shows:

• →
  RAG status — Green/Amber/Red dot, computed from milestones or set manually
• →
  Progress bar — % complete based on child work item states
• →
  Gantt bar — on the timeline, derived from Start Date and Target Date fields
• →
  Team colour — left edge coloured by owning team

Creating outcomes in ADO

OutcomeMap reads from ADO — so create your Outcome (or Objective) work items in ADO first, then sync. You can also create them directly from within OutcomeMap using the + Add button in the tree panel — OutcomeMap will create the ADO work item for you.

Linking the hierarchy

In ADO, set parent/child links between your work items:

1. Open an Initiative work item in ADO

   Go to the work item → Links tab → Add link → Parent.

2. Link to its parent Outcome (or Key Measure)

   Search for and select the parent work item. ADO creates the Hierarchy-Forward/Reverse links.

3. Repeat down the chain

   Epic → parent Initiative, Feature → parent Epic.

4. Refresh in OutcomeMap

   Click the refresh icon. The tree will update to show the linked hierarchy.

Drag to reorder

Drag any row in the tree panel to reorder it within its parent. Order is preserved across sessions and reflected on the Gantt timeline — your most important outcomes always appear first.

9. Milestones

Milestones mark key dates — launches, regulatory submissions, reviews, external deadlines. They appear as diamond markers on the Gantt timeline.

Creating a milestone

1. Click the Milestones tab

   In the plan navigation bar.

2. Click "+ New milestone"

   Enter a name, target date, and optional description. e.g. "Beta launch — 1 May 2026".

3. Link to a parent node

   Attach the milestone to an Outcome, Key Measure, or Initiative. It will appear on the Gantt at the correct position.

4. Set milestone status

   On Track, At Risk, or Delayed. Status drives the RAG colour on the roadmap and portfolio dashboard.

Milestone levels

Milestones support L0–L3 levels for governance reporting:

Milestone comments

Add threaded comments to milestones for progress notes and blockers. Comments are visible to all plan members and appear in the milestone detail panel. Milestone comments require Professional tier.

10. Roadmap (Gantt view)

The Roadmap view shows your plan as an interactive Gantt chart. Each row is a hierarchy node; bars represent start-to-target date spans; milestones appear as diamonds.

Navigating the roadmap

• →
  Zoom: Use Day / Week / Month / Quarter controls (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 — saves to ADO instantly
• →
  Resize bars: Drag the right edge to extend or shorten end dates
• →
  Expand / collapse: Click the arrow next to any node to toggle children on the timeline
• →
  Today line: Vertical line marks today — see what's on track vs slipping
• →
  Fit: Click the Fit button to auto-zoom to show all items

Getting dates on items

Gantt bars only appear when a work item has both a Start Date and a Target Date. Set these in ADO directly, or click any item in the tree panel to open a side editor and set dates without leaving OutcomeMap.

Exporting the roadmap

Click Export roadmap (top-right) to export as PDF or PNG — ready for steering committee packs and regulatory submissions. Export requires Professional tier.

Dependencies

Drag the ● handle on any node to draw a dependency link to another node. Dependencies appear as dashed connectors on the Gantt and as a full dependency map view. Cross-plan dependencies (linking items in different plans) are supported in Professional tier.

11. Portfolio dashboard

The Portfolio dashboard gives leadership a single view across every plan. Programme health, milestone status, cascade risk, and OKR confidence — all in one screen. Portfolio dashboard requires Enterprise tier.

What the portfolio shows

• →
  Health strip per plan — RAG status, % complete, milestone count
• →
  Aggregate RAG — overall portfolio health across all plans
• →
  Cascade risk detection — flags when a delayed milestone in one plan risks another plan's delivery
• →
  Executive summary — auto-updated from live delivery data, no manual aggregation

Accessing the portfolio

Click Portfolio in the OutcomeMap top navigation. All plans in the project appear automatically — no configuration needed. Click any plan card to drill into that plan's roadmap.

12. POL migration & import

Microsoft Project Online retires 30 September 2026. OutcomeMap can import your existing POL milestones via XML export — no data migration, no new platform, live in days.

Step 1 — Export from Project Online

1. Open your project in Project Online

   Navigate to your Project Web App (PWA).

2. Export as XML

   Go to File → Save As → XML format (.xml). Save the file locally.

3. Repeat for each project

   Export each POL project you want to import into OutcomeMap.

Step 2 — Import into OutcomeMap

1. Create a new plan in OutcomeMap

   Click + New plan. You can create a POL-only plan (disable ADO sync) or a hybrid plan (enable ADO sync for work items, add POL milestones on top).

2. Choose "Start from Project Online import"

   In the Create plan dialog, select the POL import path.

3. Upload your XML file

   OutcomeMap parses the XML and extracts tasks, milestones, and dates.

4. Review and confirm

   OutcomeMap shows a preview of what will be imported. Confirm to create the plan with milestones pre-populated.

5. Set milestone statuses

   Review each imported milestone and set On Track / At Risk / Delayed status as appropriate.

Hybrid approach — POL milestones + ADO work items

Many organisations want to preserve POL milestone structure while connecting it to live ADO delivery work. OutcomeMap supports this:

• ✓
  Create a plan with ADO sync enabled and add your delivery teams
• ✓
  Import POL milestones via XML — they appear on the same Gantt as your ADO work items
• ✓
  Link ADO Epics and Features to the imported milestones as evidence of delivery
• ✓
  Portfolio dashboard shows combined RAG across both ADO and POL milestones

What happens after September 2026

Once POL is retired, your imported milestones live entirely in OutcomeMap — no dependency on POL remaining. All data is stored in ADO ExtensionData (UK-hosted) and you retain full access. OutcomeMap becomes your system of record for portfolio milestone tracking going forward.