When you integrate another tool with Aha! Roadmaps, you can use the mappings step to customize which Aha! Roadmaps record types the integration should affect, how they should relate to each other, and how they should relate to records and fields in the integrated tool.
To do this, open your integration of choice by navigating to Settings ⚙️ → Account → Integrations or Settings ⚙️ → Workspace → Integrations and clicking on the Mappings step. There, you will find a set of instructions in a grey box, and two columns showing how Aha! Roadmaps records (and their associated fields) will relate to and affect records in your tool of choice.
Click any of the following links to skip ahead:
Establish parent-child record links
The order of records in the Aha! Roadmaps side of the record mappings table matters, because it establishes how Aha! Roadmaps record types relate to each other in the integration. For the second record type and following, you will see a Linked to field. This associates Aha! Roadmaps record types with each other. For example, if releases are your top record type, and features are the second, you could link features to a release's Fix versions. As a release in Aha! Roadmaps updates, it will update the features associated with it as well.
Requirements cannot exist in your Aha! account without parent features. If you move a requirement to a new parent feature, and that feature is not yet imported into your Aha! account, the integration will import both the feature and the requirement.
There are six different Aha! Roadmaps parent-child relationships to consider when setting up your mappings:
Initiative → Epic
Initiative → Feature
Release → Epic
Release → Feature
Epic → Feature
Feature → Requirement
Without the Links to values mapped, records sending from Aha! Roadmaps to an integrated system will never be properly linked to related parent records. Similarly, records being imported from an integrated system into Aha! Roadmaps will also not be related to parent records.
Aha! Roadmaps automatically populates the Linked to mappings as part of our recommended defaults for every integration. If you chose to customize your integration and redo the record mappings, the Linked to values will automatically be set as long as you map the parent records before the child records.
This means that if you add the record mappings for releases first and the record mapping for features second, the features will automatically have a Linked to mapping established. This associates the feature to the release.
However, if you do this in the opposite order, and create a mapping for features before releases, the Linked to mapping will not be automatically added. So you will need to manually add it if you want the integration to communicate the relationship between features and releases.
To set the Links to mapping manually, click Field mapping link beneath an Aha! Roadmaps record. The top of the menu that expands will let you establish Links to relationships yourself (The bottom of the menu deals with field mapping, which we cover in the next section.). Click Add link to add a new record link.
Map record fields
After you have linked Aha! Roadmaps record types to each other, it is time to map the fields on those records to their equivalents in the integrated tool. Click the Field mapping link beneath any record type to get started, and read this article for details on mapping fields.
Sync record relationships between Aha! and development tools
If you are configuring an integration with Jira or Azure DevOps, you can also sync record relationships between Aha! Roadmaps and your development tool. Both Aha! Roadmaps and these tools allow you to establish relationships between records (such as Depends on or Relates to) to provide context into how one unit of work will affect others. You can sync the record relationships between Aha! Roadmaps and Jira or Aha! Roadmaps and Azure DevOps for the following record types:
Initiatives
Releases / Schedules
Epic
Features / Activities
To map record relationships between Aha! Roadmaps and your development tool:
Click the Field mapping dropdown under your record type of choice.
Link Aha! Roadmaps Record links to Jira Issue links or Azure DevOps Related work.
If you do not see these options, click ⚙️ Reload configuration at the bottom of the page. This will update the list of available mappings, and will not affect your current mappings.
Click the Configure button.
In the Configure modal, you can match like record relationships with each other or associate a given record relationship with multiple others.
Click Done to save your changes.
Click Save and continue when you are done adjusting mappings. This will take you to the Enable step of the integration wizard.
If this is your first time establishing field mappings, you will need to set up a webhook in Jira or Azure DevOps to ensure that Aha! Roadmaps can receive updates from your development tool. Follow the instructions on this page to set up the webhook, and be sure to check the box for Issue link in Jira or Related work in Azure DevOps. Click Save and continue to enable the integration.
Note: If you map multiple record relationship types to each other, the order in which you do so matters. This is because the integration automatically uses the first option. In the example below, we mapped Relates to and Contains in Aha! Roadmaps to Relates in Jira. If a Relates issue link is added to a record in Jira, this relationship will show in Aha! Roadmaps as Relates to.
It is often useful for both product and engineering teams to update and add to these record dependencies, keeping each other informed of developments. If this is true for your team, we recommend establishing this field mapping as bidirectional.
Do you want to chart this data or visualize it in a custom roadmap? Use the [Record type] record links and Linked [record type] tables to visualize and analyze linked records.