Azure DevOps Integration
To provide users with a seamless data transfer between Roadmunk and Azure DevOps, users are now able to directly integrate their Roadmaps with existing projects in Azure DevOps (ADO) - enabling teams delivering from ADO to automate and elevate their existing roadmapping processes.
Getting Started with Azure DevOps
Linking Roadmunk to your Azure DevOps Instance
In order to connect your Roadmaps to your projects and boards in ADO, an Account Admin on your Roadmunk account will need to establish the connection between Roadmunk and your team's ADO instance. Once this connection is established, users will be able to view and select this integration option from a list of integrated ADO tools in their on-roadmap setup menu and save credentials against that instance for future setup of additional roadmaps.
Generating Credentials for Roadmunk in Azure DevOps
In order to authorize the data transfer between Roadmunk and ADO and ensure that user permissions are respected, Roadmunk relies on a user-generated credential which allows the user to view and pull their data from their projects & boards. In this case, we require a Personal Access Token (PAT) generated in Azure as your credential and during the roadmap setup will allow you to set a Credential Label so you can easily differentiate this particular token from others you may use (in the case of teams working across multiple active ADO deployments).
To generate the Personal Access Token:
In Azure DevOps, click into the User Settings icon in the top right corner (beside your avatar)
From the menu that appears, select the Personal Access Token option.
In the window that appears, select the + New Token button at the top of your PAT list.
At the top of the panel that appears, define the token's name & expiration date.
In the Scopes section, select the Full Access option to prevent roadblocks while synchronizing.
Once ready, click Create to generate the token value.
Make sure to copy the provided value before pressing Close to return to your PAT list.
A more in-depth guide on Personal Access Tokens can be found here in Microsoft's ADO documentation.
Permissions Limitations between Roadmunk & Azure DevOps
Please note that Roadmunk will respect the permissions of your ADO account tied to the user-provided credentials mentioned above and will limit content visibility during the sync setup to match that of ADO. This means that if your provided credentials only allow you to view certain projects, boards, and fields, then these limitations will carry over into Roadmunk.
If you do find that you are unable to access or view certain projects or that your work items are not populating entirely, please connect with your ADO administrator to ensure that you have the appropriate permissions to view and access that particular content.
Connecting your Roadmaps to Azure DevOps
Integrations Setup Walkthrough
It's a quick and easy process to set up an integration between your Azure DevOps projects and your team's roadmaps in Roadmunk. The setup process can be broken down into three stages: triggering the integration, applying synchronization settings, and applying field and filter settings. Once those have been completed, your roadmap will be set to pull data from ADO as needed.
Step 1 - Triggering the Roadmap Integration
Once the integration has been setup and your Azure DevOps instance has been connected to Roadmunk, you will be able to select the Setup ADO Integration option in your Integrations tool on your roadmap. Triggering this integration will not overwrite your existing data; however, once you've linked a roadmap to a project you are unable to remove that link or change the specified project
This option will activate a setup wizard which will walk you through the process of selecting a project in ADO to act as a data source for your roadmap.
Step 2 - Applying Synchronization Settings
Once in the setup wizard, you will be prompted to follow the preset workflow to complete the integration. In the first phase of this workflow, you will have the option to select which ADO server you would like to pull project data from, the synchronization direction (one-way or two-way).
Step 3 - Applying Credentials, Field & Filter Settings
Once your instance has been selected, you'll be prompted to choose your credentials for syncing with ADO. If you haven't previously setup credentials to sync with, please enter the Personal Access Token that was generated above and apply a Credential Label for future reference.
After the details above have been provided, you will be able to select the project you would like to pull data from and filter the pulled data to ensure that only the necessary items are being pulled. As seen below, if the Basic Configuration mode is selected, you will be able to filter work items by both Type and State through easy-to-use drop-down menus.
Once these settings have been applied, you'll be able to choose from a list of available fields to use on your roadmap. While the specified project can't be changed after the setup, the user-defined data filters and fields can be updated later if needed.
Once you've completed this phase of the setup, you'll be taken to a confirmation screen to let you know that the integration has been setup successfully. After completing the setup wizard, you'll be returned to the roadmap view where your data will begin to populate from your specified Azure DevOps project.
What to Expect After Integrating
Once you've integrated your data from Azure DevOps, there will be a few changes to your roadmaps. The following changes may occur after you've setup your integration:
All fields pulled from Azure DevOps are Account-Level by default - Since the properties and values of these synchronized fields are managed in ADO, we automatically promote them to account-level so they can be accessible as common fields in Portfolio roadmaps.
There is a locked ID field that appears in the Items Table view - When synchronizing data from ADO, we pull in the ID of that particular work item for reference on your roadmap. This is clickable and linked out to your team's ADO instance, so you can quickly access the respective work item from either your Table view and Item Card.
Unable to change or add new projects on a single roadmap - As with our Jira synchronization, we limit connections between roadmaps and projects to be a 1:1 connection. This means that you will be unable to sync multiple projects into a single roadmap; however, you will be able to create multiple roadmaps for each project and use those as sources in a Portfolio roadmap.
Additional Date fields will be read-only - Due to a variance in field formatting between Roadmunk and Azure DevOps, any additional Date fields that are selected to display, after Start and End date mapping is specified, will be pulled in as read-only text fields.
Tokens may expire a set number of days after being created - Unlike API tokens generated for credentials in Jira, which have a longer-term expiry, Personal Access Tokens generated in ADO will typically expire anywhere from 7-90 days depending on your default settings, but can be valid for up to 1 year. These can be easily extended further from inside ADO by opening the Edit panel for your Roadmunk token and setting a custom expiry date.
Modifying Azure DevOps Integration Setup
Once the initial integration setup is complete, the roadmap owner will be able to modify the setup at any time. To do so, from the Items Table or in a roadmap visualization, simply click the Azure DevOps button in the top right-hand corner and select "Modify Setup" from the drop-down menu. This will open the integration setup menu and you can alter sync settings, credentials, filter work items, and select fields.
