When you integrate another tool with Aha!, you can use the mappings step to customize which Aha! 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 yellow box, and two columns showing how Aha! 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
- Map record fields
- Sync record relationships between Aha! and Jira
Establish parent-child record links
The order of records in the Aha! side of the record mappings table matters, because it establishes how Aha! 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! 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! updates, it will update the features associated with it as well.
There are six different Aha! parent-child relationships to consider when setting up your mappings:
- Initiative > Master feature
- Initiative > Feature
- Release > Master feature
- Release > Feature
- Master feature > Feature
- Feature > Requirement
Without the Links to values mapped, records sending from Aha! to an integrated system will never be properly linked to related parent records. Similarly, records being imported from an integrated system into Aha! will also not be related to parent records.
Aha! 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.
Map record fields
After you have linked Aha! 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 Jira
If you are configuring a 2.0 integration with Jira, you can also sync record relationships between Aha! and Jira. Both Aha! and Jira 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! and Jira for the following record types:
- Master features
To map record relationships between Aha! and Jira:
- Click the Field mapping dropdown under your record type of choice.
- Link Aha! Record links to Jira Issue links.
Note: If you do not see the Jira Issue links as an option, 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 to ensure that Aha! can receive updates from Jira. Follow the instructions on this page to set up the webhook, and be sure to check the box for Issue link in Jira. 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! to Relates in Jira. If a Relates issue link is added to a record in Jira, this relationship will show in Aha! 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.