The integration between Aha! Roadmaps and Azure DevOps (ADO) is one of our most popular, for good reason.
Aha! Roadmaps handles the "why" and "what" — your strategic goals and the work you need to accomplish to reach those goals. Azure DevOps handles the "how," as the platform engineering teams use to complete the work you've defined. With a robust two-way integration between the two tools, the work you send to engineering teams comes with full strategic context, and the updates you get back inform how you are progressing.
When you first configure the integration, though, you may have questions about which Aha! Roadmaps record types should link to which Azure DevOps record types. In this article, we will discuss some of the most common ways to link the two tools.
In addition to mapping records between Aha! Roadmaps and Azure DevOps, did you know that you can also map record links?
Click any of the following links to skip ahead:
Introduction
Recommended mappings
Record-specific mappings
How to think about mappings
This integration is intentionally flexible – you can map Aha! Roadmaps and Azure DevOps record types together in a variety of equally valid ways. It's important, then, to think intentionally about how you want Aha! Roadmaps and Azure DevOps to work together.
To get started, consider these questions:
How are you organizing work in Azure DevOps today?
In Aha! Roadmaps, what level of that work do you need visibility into?
As a best practice, we recommend that you define work in Aha! Roadmaps first — typically in releases, features, and requirements — and send it to Azure DevOps when you are ready for your engineering team to begin executing on it.
In this article, we will walk through three common ways to connect Aha! Roadmaps and Azure DevOps. To model your integration after any of these options, navigate to Settings ⚙️ → Workspace → Integrations, select or create an Azure DevOps integration, and move to the Mappings step. You will need to be a workspace owner to do this.
Best practices for changing your integration mappings
If you read this article and want to change your Azure DevOps integration mappings, great! We are glad you are inspired. Before you adjust your integration configuration though, you need a plan to link existing records between Aha! Roadmaps and Azure DevOps according to your new mappings. Follow these steps, and please do reach out to our Customer Success team if you have any questions. Then, enjoy your new configuration!
First, test your new integration configuration in a demo workspace or trial Aha! Roadmaps account. Make sure you like how records flow between your Aha! Roadmaps workspace and Azure DevOps project, and that the appropriate fields are mapped to each other between the two tools.
Some changes to your integration configurations, such as fundamental changes to the structure of your configurations, will break the existing links between Aha! Roadmaps and Azure DevOps records. To re-link existing records, you can:
-
Use Azure DevOps as the source of truth and reimport
Start with a bulk delete of all of the Aha! Roadmaps records that are linked through your current integration mapping to your Azure DevOps project.
Note: Deleting records in Aha! Roadmaps will never delete records in your development tool.Reconfigure your Azure DevOps integration to your preferred mappings.
Use the import from development tool functionality to re-import all your records from the Azure DevOps project. This import will use your new configuration to create new links between the integrated records.
-
Manually relink each record
Reconfigure your Azure DevOps integration to your preferred mappings. This will break existing links between Aha! Roadmaps and Azure DevOps records.
Open each affected record in Aha! Roadmaps and under the Integrations field select Link with existing record. Select the appropriate Azure DevOps record to re-establish the link.
Congratulations! After following either of these options, your integration will be configured with your new mappings, and existing records will be linked between the two tools.
Reporting-only fields
In the Mappings step of your Aha! integration configuration, you can see every Aha! and Azure DevOps field which can be mapped to each other. While the majority of these fields allow for bidirectional, customizable mappings between the two tools, some fields are intended only to help you report on Azure DevOps information in your Aha! account, and will not update from Aha! into Azure DevOps as you might assume.
Records in Azure DevOps can exist at different hierarchical depths and contain properties which might not be well represented in how Aha! records link to each other, but which are still material to understanding the record. In Aha! Roadmaps, for example, a feature will belong only to one release. In Azure DevOps, it's possible for a work item to belong to multiple iterations at the same time. To allow Aha! Roadmaps to report on these extra properties, you can map to those Azure DevOps fields and then populate your Aha! account with their information. These mappings have no impact on behavior and are purely for informational/reporting purposes.
As best practices:
Hierarchical mappings for fields such as Area level and Iteration depth are reporting-only fields.
If you want to map to one of these fields, map the Azure DevOps field to a text-based Aha! custom field like a notes field. Interactive custom fields like predefined choice lists will not respond well to reporting-only Azure DevOps fields.
Azure DevOps project types
The default Azure DevOps work item types change slightly depending on which project type your team uses. Depending on your project type, for example, the work items in the Requirement category may be called User stories, Issues, Product backlog items, or Requirements.
In this article, we will follow the terminology of an Agile project in Azure Devops, which includes the following default work items:
Hierarchy level |
Category |
Work item type |
Portfolio backlog |
|
|
Backlog |
|
|
Issue & bug tracking |
|
|
Option 1: Aha! Roadmaps features to ADO epics
Aha! Roadmaps |
Azure DevOps |
Feature |
Epic |
Requirement |
Feature |
Choose this option if:
Your work in Azure DevOps is organized into epics and features, and in Aha! Roadmaps you need visibility into the features.
All Azure DevOps features have associated epics.
User stories, issues, product backlog items, requirements, and tasks are excluded.
Option 2: Aha! Roadmaps epics to ADO epics (detailed)
Aha! Roadmaps |
Azure DevOps |
Epic |
Epic |
Feature |
Feature |
Requirement |
User story |
Aha! Roadmaps epics provide another layer of organization above features. They are disabled by default when you first create an Aha! Roadmaps account. To enable them, navigate to Settings ⚙️→ Workspace → Configure → Epics. You will need to be a workspace owner to do this.
Choose this option if:
Your work in Azure DevOps is organized into epics, features, and user stories, and in Aha! Roadmaps you need visibility to that level.
Your team in Aha! Roadmaps is in charge of breaking down features into smaller units of work.
Aha! Roadmaps epics are delivered iteratively, where associated features may be delivered over multiple releases.
Option 3: Aha! Roadmaps epics to ADO epics (summary)
Aha! Roadmaps |
Azure DevOps |
Epic |
Epic |
Feature |
Feature |
Note: Aha! Roadmaps epics provide another layer of organization above features. They are disabled by default when you first create an Aha! Roadmaps account. To enable them, navigate to to Settings ⚙️→ Workspace → Configure → Epics. You will need to be a workspace owner to do this.
Choose this option if:
Your work in Azure DevOps is organized into epics and features, and in Aha! Roadmaps you need visibility into the features.
Some Azure DevOps features are not associated with an epic.
Aha! Roadmaps epics are delivered iteratively, where associated features may be delivered over multiple releases.
Option 4: Aha! Roadmaps epics to ADO features
Aha! Roadmaps |
Azure DevOps |
Epic |
Feature |
Feature |
User story |
Requirement |
Task |
Choose this option if:
Your work in Azure DevOps is organized into features and user stories, and in Aha! Roadmaps you need visibility into the user stories.
Some Azure DevOps user stories are not associated with a parent feature.
Aha! Roadmaps features are delivered iteratively, where associated Azure DevOps user stories may be delivered over multiple releases.
You may also define work in Azure DevOps using tasks. In that case, this mappings option works well if in Aha! Roadmaps you need visibility into Azure DevOps tasks.
Mapping tasks
Mapping Azure DevOps tasks to an Aha! Roadmaps record type is an optional step. It makes the most sense if:
Your team in Aha! Roadmaps is in charge of breaking down stories into smaller units of work.
Note: If the engineers working in Azure DevOps are responsible for breaking down user stories into further tasks, then generally you can leave tasks unmapped in the integration. Azure DevOps tasks in this situation are usually development-related records that you do not need Aha! Roadmaps visibility into.You want to include tasks in your Aha! Roadmaps roadmaps.
Mapping releases
Aha! Roadmaps releases are generally mapped to Azure DevOps iterations — most commonly to iteration level two. Mapping them is an optional step that comes down to whether your use of an Aha! Roadmaps release matches with the engineering team's use of Azure DevOps iterations.
Note: If you want to link iteration paths beneath level two, you will need to type in the full iteration path. E.g. when connecting to iteration level three, you need to use Layer 2/Layer 3.
For example, a product management team in Aha! Roadmaps may organize work into releases by thematic update, while an engineering team in Azure DevOps may organize work into iterations around actual product versions. In that situation, it would not make sense to map Aha! Roadmaps releases to Azure DevOps iterations.
If your releases in Azure DevOps are below level two, you will need to:
Create the release in Aha! Roadmaps
Create the iteration in Azure DevOps
Open the Aha! Roadmaps release and click Link with Existing to connect the two records.
Note: This should be done before sending any child records between the two tools.
If you do not choose to map releases to iterations, you can still include the Azure DevOps iteration field in your field mappings. Map the Azure DevOps field to a custom field added to the Aha! Roadmaps feature layout to include that level of context in your features.
You can track the progress of your Aha! Roadmaps features and epics at the sprint level by creating a custom field in Aha! Roadmaps and mapping it to the appropriate iteration level in Azure DevOps.
Record relationship links
While setting up your integration, you can define a Links to relationship in the Mappings step. This associates Aha! Roadmaps record types with each other. For example, if epics are your top record type, and features are the second, you could link features to an Aha! Roadmaps epic's Azure DevOps epic. As an epic in Aha! Roadmaps updates, it will update the features associated with it as well.
The order in which you map record types to each other matters, because it establishes fields are available to you in these Links to relationships.
Status mappings
When you map two record types to each other, their statuses will also be mapped to each other. You can review and adjust these status mappings by clicking Configure by a record type in the Mappings step of the integration setup.