This article refers to releases and features. Depending on your workspace type, you may see "schedules" and “activities" in your workspace.
Aha! Roadmaps | Recommended Jira mappings
The integration between Aha! Roadmaps and Jira 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. Jira 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 Jira record types. In this article, we will discuss some of the most common ways to link the two tools.
Click any of the following links to skip ahead:
How to think about mappings
This integration is intentionally flexible – you can map Aha! Roadmaps and Jira record types together in a variety of equally valid ways. It's important, then, to think intentionally about how you want Aha! Roadmaps and Jira to work together.
To get started, consider these questions:
How are you organizing work in Jira 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 Jira when you are ready for your engineering team to begin executing on it.
Note: If your team uses Jira Advanced Roadmaps (formerly known as Jira Portfolio), you can include Jira initiatives in your integration mappings as well.
In this article, we will walk through three common ways to connect Aha! Roadmaps and Jira. To model your integration after any of these options, navigate to Settings ⚙️ Workspace Integrations, select or create a Jira 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 Jira 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 Jira 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 Jira project, and that the appropriate fields are mapped to each other between the two tools.
When you change your integration configuration in your Aha! Roadmaps workspace, you will break the existing links between Aha! Roadmaps and Jira records. To re-link existing records, you have two options:
Use Jira as the source of truth and re-import
Create a list report of all the Aha! Roadmaps records that are linked through your current integration mapping to your Jira project. Be sure to include the record ID and any other important fields — especially fields that might not be mapped to Jira.
You may have to create separate list reports for each record type — feature, epic, and release — that you need to export.
Export your list report(s) as a CSV file (.csv). If you delete records from Aha! Roadmaps and want to reference them later, this .csv file will contain the deleted data.
Bulk delete all of the Aha! Roadmaps records that are linked through your current integration mapping to your Jira project.
Deleting records in Aha! Roadmaps will never delete records in your development tool.
Reconfigure your Jira integration to your preferred mappings.
Use the import from development tool functionality to re-import all your records from the Jira project. This import will use your new configuration to create new links between the integrated records.
Use list reports, bulk edits, and CSV imports to add in information, such as links to strategic records, that you could not import from Jira.
Manually re-link each record
Reconfigure your Jira integration to your preferred mappings. This will break existing links between Aha! Roadmaps and Jira records.
Open each affected record in Aha! Roadmaps and under the Integrations field select Link with existing record. Select the appropriate Jira 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.
Option 1: Features to epics
Aha! Roadmaps | Jira |
Feature | Epic |
Requirement | Story |
Choose this option if:
Your work in Jira is organized into epics and stories, and in Aha! Roadmaps you need visibility into the stories.
All Jira stories have associated epics.
Jira epics and their associated stories are completed in the same release.
You do not need to see detail beyond the story level in Aha! Roadmaps, even if Jira stories have been broken down further.
Option 2: Aha! Roadmaps epics to Jira epics
Aha! Roadmaps | Jira |
Epic | Epic |
Feature | Story |
Requirement | Sub-task |
Note: 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.
Choose this option if:
Your work in Jira is organized into epic, story and sub-task and in Aha! Roadmaps you need visibility to that level.
Your team in Aha! Roadmaps is in charge of breaking down stories into smaller units of work.
Jira epics are completed iteratively, with associated stories delivered over multiple releases.
You want to include sub-tasks in your Aha! Roadmaps roadmaps.
Option 3: Features to stories/tasks
Aha! Roadmaps | Jira |
Epic | Epic |
Feature | Story/Task |
Note: 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.
Choose this option if:
Your work in Jira is organized into epics and stories, and in Aha! Roadmaps you need visibility into the stories.
Some Jira stories are not associated with an epic.
Jira epics are completed iteratively, with associated stories delivered over multiple releases.
You may also define work in Jira using Tasks. In that case, this option works well if in Aha! Roadmaps you need visibility into Jira tasks, and some tasks are not associated with an epic.
Map sub-tasks
Mapping Jira sub-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 Jira are responsible for breaking down stories into further sub-tasks, then generally you can leave sub-tasks unmapped in the integration. Jira sub-tasks in this situation are usually development-related records that you do not need Aha! Roadmaps visibility into.
You want to include sub-tasks in your Aha! Roadmaps roadmaps.
Map releases
Aha! Roadmaps releases are generally mapped to Jira versions. 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 Jira versions.
For example, a product management team in Aha! Roadmaps may organize work into releases by thematic update, while an engineering team in Jira may organize work into versions around actual product versions. In that situation, it would not make sense to map Aha! Roadmaps releases to Jira versions.
If you do not choose to map releases to versions, you can still include the Jira fix version field in your field mappings. Map the Jira field to a custom field added to the Aha! Roadmaps feature layout to include that level of context in your features.
Map initiatives (Jira Advanced Roadmaps)
If you use Jira Advanced Roadmaps, you have access to Jira initiatives. Initiatives in Jira are parent record types of multiple epics, and can span multiple releases as your development team works to implement them.
There are several ways you can map Jira initiatives to Aha! record types, depending how your team thinks of them.
Jira initiatives Aha! initiatives: Aha! initiatives represent large efforts that help you deliver against your strategic goals. You should craft product strategy in Aha! Roadmaps, and use integrations to share that strategic context with development teams. You can map Aha! initiatives to Jira initiatives so that development teams can use Jira initiatives to see strategic context for all their child epics.
Jira | Aha! |
Initiatives | Initiatives |
Epics | Epics |
Stories, Tasks | Features |
Subtasks | Requirements |
Jira initiatives Aha! epics: Aha! epics are ways to group features by theme of work. Like Jira initiatives, they span multiple releases. If you map Jira initiatives to Aha! epics, your record type mappings would look like this. Note that you would not be able to map subtasks in the integration:
Jira | Aha! |
Initiatives | Epics |
Epics | Features |
Stories, Tasks | Requirements |
Subtasks | n/a |
Map multiple Jira versions to one Aha! Roadmaps release
In Aha! Roadmaps, releases are containers for work organized around release dates, when you deliver a Complete Product Experience to your users. But in Jira, you may need to split your release into multiple versions, tracking increments or developer releases, or sprints.
Thanks to custom fields, you can map multiple Jira versions to one Aha! Roadmaps release. The Jira records will have two related fields: one to track the Aha! Roadmaps release (such as a go-to-market version) and one to track the Jira increment (such as a code deployment version).
Note: In this example, we will use a custom field to track Aha! Roadmaps go-to-market versions, and the existing Jira FixVersion field to track code deploys, but you can of course track these fields the other way around.
Go-to-market version:
Create a custom field in Jira using a version field type (Version picker (single version), for example).
Map the Jira fix version to an Aha! Roadmaps custom field on the epic/feature.
Code deployment version:
Continue using Jira FixVersions to represent the code deployment versions.
In the integration configuration, use the custom version field for go-to-market version in the Links to relationship.
There are a few things to consider with this approach:
Each Jira record would require both a fix version and a go-to-market version.
The Jira Releases screen may cause confusion because the go-to-market release using the custom Version field will not include any issues.
If you import releases to Aha! Roadmaps from Jira, then the field you use to track Jira code deployments may be included — and you may want to exclude it.
Aha! Roadmaps users will need to ignore certain release records importing from Jira. For example, when a new FixVersion is created in Jira, it will be an import candidate for Aha! Roadmaps, but those Jira issues might already exist in your Aha! Roadmaps release.
Record relationships 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 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.
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.
Note: Specifically for Aha! Roadmaps initiatives, only add the initiative links to relationship to records where the initiative field is displayed in Jira. It is possible to add the links to relationship to other records, but the information will not be visible in Jira.
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.
You can map a record's status in Aha! Roadmaps to its corresponding Jira Status and Resolution fields — so you can close an issue in Jira without leaving Aha! Roadmaps.
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.
