Contents:
StoriesOnBoard & Azure DevOps integration overview
Connect your story map to an Azure DevOps project to plan on the story map and deliver in Azure DevOps. Cards you push become work items, and changes to names, descriptions, estimates, statuses and releases are synchronized in both directions, so the story map and the backlog stay up to date.
Who can set up the Azure DevOps integration
Story map Admins can set up the integration, change its settings, re-authorize the shared connection, unlink the project and disconnect.
Admins and Editors can sign in to Azure DevOps with their own account when the story map uses per-user sign-in (impersonation).
Viewers see the synchronized cards, but cannot change the integration.
Your subscription needs the integration add-on. Per-user sign-in needs the impersonation add-on.
On the Azure DevOps side, you must hold Admin rights on the project as well: the integration creates service hooks there to keep your story map up to date.
How to set up Azure DevOps integration on your story map
Quick summary:
Open "Settings" → "Integration settings".
Select "Azure DevOps" and click "Connect".
Enter your organization address and click "Sign in to Azure DevOps".
Sign in with your Microsoft account in the window that opens.
Select the Azure DevOps project and click "Connect project".
Go through the six setup steps and click "Finish".
Step-by-step guide:
Open your story map. In this example, the "Agency project hub" story map is not connected to an issue tracker yet.
Click "Settings" in the top right corner and select "Integration settings".
Select "Azure DevOps" and click "Connect".
Enter the address of your Azure DevOps organization, in the form https://dev.azure.com/{organization} or https://{organization}.visualstudio.com. Please do not include the project name in the address. Click "Sign in to Azure DevOps".
A sign-in window opens. Sign in with your Microsoft account there. StoriesOnBoard checks how your organization signs in and uses Microsoft Entra ID automatically when your organization is connected to it. The setup waits until you finish:
After signing in, select the Azure DevOps project you want to connect to the story map.
Click "Connect project". If you created the project only now, click the refresh icon next to the list.
The project is connected. Click "Next" to configure the integration.
Step 1 – Integration mode: choose which levels of your story map are linked to Azure DevOps work items: only the story level cards, the second and the story level, or all levels of the board hierarchy. You can change this later, see Azure DevOps hierarchy synchronization.
Step 2 – Card synchronization: select which card properties are synchronized in both directions: name, description and estimation (as Story points or Effort).
Step 3 – Export settings: select the work item type used when you push story level cards to Azure DevOps, and decide whether the StoriesOnBoard card link is added to the work item.
Select the area where the new work items are created:
Step 4 – Import settings: select the work item types you want to import and synchronize, and map their Azure DevOps statuses to your story map's statuses.
To import work items with a stored Azure DevOps query instead, open the advanced import filter and select a query. Only "Flat list of work items" queries are supported. See How to import issues from Azure DevOps using a query.
Step 5 – Release synchronization: turn on "Synchronize releases as Azure DevOps iterations" to keep your releases and Azure DevOps iterations in sync, then select the parent iteration for the releases you export.
Step 6 – Per-user sign-in: decide whether changes are synchronized with each collaborator's own Azure DevOps account (impersonation). See How to use per-user sign-in. Click "Finish".
The integration is set up. Click "Got it" to return to your story map.
How to push cards to Azure DevOps
Once the story map is connected, hover over a card, click its "⋯" button and select "Push to Azure DevOps". The card becomes a work item, and its number appears on the card. To push several cards or a whole release, see How to push cards to Azure DevOps from your story map.
How to access integration settings
Open "Settings" → "Integration settings" on the story map. The settings are organized into three tabs: "General settings", "Export" and "Import", with the same options as the setup steps above. Click "Save changes" after changing anything. For a description of every option, see Customize your Azure DevOps integration.
💡 Tip - Story maps set up earlier in Classic open with their saved settings here, so you don't need to switch to Classic for Azure DevOps anymore.
How to use per-user sign-in (impersonation)
With per-user sign-in, the changes you make on the story map are synchronized to Azure DevOps on behalf of your own Azure DevOps account. Collaborators who have not signed in can only view the story map.
Turn it on (Admins):
Open "Settings" → "Integration settings" → "General settings".
Select "Enable impersonation" and click "Save changes".
Manage your own sign-in (Admins and Editors):
Open "Settings" and select "Azure DevOps sign-in".
Click "Re-authorize" to sign in again, or "Log me out" to remove your own sign-in from this story map.
When you log out, StoriesOnBoard asks you to confirm. Your colleagues' sign-ins and the shared connection are not affected.
If you haven't signed in yet:
When you open a story map that uses per-user sign-in, StoriesOnBoard asks you to authenticate. Click "Authenticate in Azure DevOps Services" to sign in now, "Later" to do it later, or "Don't remind me" to stop the reminder. Until you sign in, the story map is read-only for you.
While the story map is read-only for you, the Azure DevOps icon next to "Roadmaps" lets you sign in at any time. Admins can also re-authorize the shared connection from here.
After signing in, you can edit the story map again, without reloading the page.
How to re-authorize the shared connection
If the shared Azure DevOps connection stops working (for example, the person who set it up left the company), an Admin can replace it without re-linking the project or redoing the settings.
Open "Settings" → "Integration settings".
Click "Re-authorize the shared connection" and sign in with the Microsoft account the integration should use.
How to disable, change the hierarchy, unlink or disconnect
Disable or enable the integration: click "Disable integration" to pause the synchronization. Your settings and card links are kept. Click "Enable integration" to continue.
Change the hierarchy: when you link more levels of the story map, choose the direction of the first synchronization: from StoriesOnBoard to Azure DevOps (your upper level cards are created as Epics and Features), or from Azure DevOps to StoriesOnBoard.
StoriesOnBoard tells you how many cards were pushed:
When you link fewer levels, StoriesOnBoard asks for confirmation before it unlinks the upper level cards from their work items.
Unlink the project: click "Unlink project" to connect the story map to another project of the same organization. Your sign-in is kept.
Disconnect: click "Disconnect Azure DevOps" to remove the connection and the personal sign-ins. Your cards and the Azure DevOps work items are kept.
Troubleshooting
Connecting fails because of permissions in Azure DevOps
If you can't connect the project or enable the integration, check these in Azure DevOps:
You are a project administrator of the Azure DevOps project.
The project administrators have the "Edit project-level information" and "View project-level information" permissions. To set them, open Project Settings > Permissions, select Project Administrators and allow both.
The sign-in is refused (organizations not connected to Microsoft Entra ID)
Organizations that are not connected to Microsoft Entra ID use the Azure DevOps sign-in. For this sign-in, third-party applications must be allowed: open your Azure DevOps Organization Settings, go to Security > Policies and turn on Third-party application access via OAuth.
The sign-in window was closed before the sign-in finished
Nothing changes. Click the button again and finish the sign-in in the new window. If no window opens, allow pop-ups for StoriesOnBoard in your browser.
"Enter the address of your Azure DevOps organization"
The address you entered is not an Azure DevOps organization address. Use https://dev.azure.com/{organization} or https://{organization}.visualstudio.com, without the project name.
"An earlier change could not be confirmed"
The connection was lost before StoriesOnBoard got an answer, so the change may or may not have been saved. Click "Check the current state" to load the current settings.
Check the settings, then click "Continue anyway" to work with them.
I want to connect a Team Foundation Server (TFS)
TFS integration is set up in the Classic view. Follow the steps shown, then switch back to NextGen. See Setting up integration with Microsoft Team Foundation Server (TFS).
