It’s very simple to enable an integration with Azure DevOps. Firstly, select a story map from the dashboard page that you would like to sync. Then click the “Integrations” button in the sidebar:
Then click “enable” under the Azure DevOps logo:
You should then be prompted to authorise your Azure DevOps account with Avion. This is a one-time authorisation per story map. Please bear in mind that you will require administrator rights to your Azure DevOps team to complete the integration. You can read more here.
Once we have the permissions we need, you may be prompted to select the correct account and project — this will depend on whether you have multiple accounts and/or projects.
You will then be asked to select an import strategy, described by three options:
Wipe the current story map and import everything from Azure DevOps
Keep the current story map and import everything from Azure DevOps
Keep the current story map and don't import anything from Azure DevOps
The options are fairly self-explanatory, but here are some recommendations:
Select option 1 if you have a lot of content already in Azure DevOps, but have a fairly empty story map, with just a few test journeys.
Select option 2 if you have lots of content already in Azure DevOps but have also created a complex story map.
Select option 3 if you have a small amount of content in Azure DevOps but have created a complex story map.
When the popup window closes, your story map will be successfully in sync with Azure DevOps. At this point:
Your backbone will be synced
Any content that you imported from Azure DevOps will be in sync (stories included)
Stories created in Avion (either before or after setting up the integration) will not be automatically synced
You can push a release by using the context menu, to the left of the release name:
All stories in the release will be pushed to Azure DevOps and will remain in sync. You can tell when a story is in sync by the sync icon in the bottom right corner of the story:
You can also get a link to the card in Azure DevOps in the story details panel:
Title changes will stay in sync
Parent/child relationships will stay in sync. For example, moving a step to a different parent journey in Avion will result in the feature having a different parent epic in Azure DevOps.
Size changes will stay in sync
Description changes will stay in sync
Status changes will stay in sync
We recommend that after your initial sync, you create all future cards in Avion. If you create a journey or step in Avion, it will be immediately synced with Azure DevOps.
If you create a story in Avion, it will only be synced when it is part of a release that gets pushed to Azure DevOps, see “How To Sync Stories”.
If you create a work item in Azure DevOps, this will not automatically be created in Avion. This is by design, as it goes against our recommended workflow. It also adds complications down the line if work items get created without parents.
If you want to delete a card (and any associated children), we recommend that you do this from Avion, and allow us to sync that operation with Azure DevOps. All cards that are deleted from Avion will be deleted in Azure DevOps.
However — if you decide to delete a work item from Azure DevOps first, here is what will happen:
If you delete a User Story/Requirement/Product Backlog Item, Avion will unlink the integration for that particular story, but the data will still remain in Avion.
If you delete a Feature or an Epic — due to how Azure DevOps handles this — things get a little more complex. Any child work items will become “un-parented”. This goes against Avion’s design principle, as we use a more strict data model than Azure DevOps. So, Avion will unlink the integration for that particular step or journey, but will also unlink all the child cards. All the data will remain in Avion, but will not be synced with Azure DevOps.
If you wish to re-sync this data, you will need to disable (not remove) and re-enable the integration. It might be a good idea to remove the leftover un-parented work items in Azure DevOps, to save your team any confusion.
It's because of the above complications that we recommend you try to do all creation and deletions from Avion and allow your data to flow one way.