This article refers to releases and features. Depending on your workspace type, you may see "schedules" and “activities" in your workspace.
Aha! Roadmaps | Integrate with Jira (version 1.0)
We have updated this integration to version 2.0! 2.0 integrations have all the same functionality of a 1.0 integration, plus expanded capabilities and support
Aha! Roadmaps is designed to help you and your team collaborate to define your strategy, connect it to your work, and visualize your roadmap. Think through the process of what goes into prioritization, and how features and requirements map to the work development in Jira. This will help you set up your integration to ensure that your team and the development team stay in sync.
If you are ready to update your integration from 1.0 to 2.0, please follow these steps. You can also learn more about the 2.0 Jira integration.
Click any of the following links to skip ahead:
Features of the integration
Click any of the following links for a quick overview of the integration:
Map record types
Consider how you want to map features and requirements from Aha! Roadmaps to Jira so that the handoff from product to development is seamless. For example, agile teams typically map features to user stories, and requirements to sub-tasks (reference Agile and non-Agile mappings for more help).
Higher level capacity planning
Development team resources are finite. This means that communicating when a customer-facing release will be ready is tough. To increase accuracy and minimize the risk of delays, you can turn on capacity planning. This is a way for you to take a first guess at what it will take to complete a feature. Invite a team lead or manager into Aha! Roadmaps to help with ballpark estimates. Then, let the development team plan the detailed, line-level estimates in Jira. If you turn on capacity planning, estimates get sent to Jira and will be updated automatically by the dev team (from Jira).
Prioritize features
When tradeoffs do need to be made, it's important to know which features should be worked on first. Use the Aha! scorecard to help vet features against your strategy by using metrics to rate each feature. Using a consistent scorecard ensures that each feature is rated against the same objective criteria. Organize the feature cards in Aha! Roadmaps in their preferred rank order to maintain the rank integrity in Jira. To do this, create a custom field in Jira for rank and map Aha! Roadmaps rank to your custom Jira field. This keeps all teams aligned with what matters.
Send records to Jira
After you have captured and prioritized your features, push your releases, features, and requirements from Aha! Roadmaps to Jira by clicking on the Integrations field of a record and selecting Send to Jira. You can do this for a single feature or for all features in a release. You can also bulk send features to Jira. The feature ranking will only be performed when the issue is first created and sent over from Aha! Roadmaps to Jira.
Automatic two-way updates
The sync between Aha! Roadmaps and Jira is deep. If updates are made in Aha! Roadmaps to features and requirements after they have been sent to Jira, those changes are automatically updated in Jira. And when changes are made in Jira (including status changes), these are automatically reflected in Aha! Roadmaps so that your team is kept up to date. This includes new Jira items that are created as part of the release, such as fix version, or feature, such as Jira issue. This ensures that if development splits an item into several tasks, your team can monitor progress.
Top of article | Top of section
Integrate with Jira Cloud and Jira Server
This two-way integration allows you to push your releases, features, and requirements from Aha! Roadmaps to Jira. The Jira integration is our most popular, robust integration, though the 1.0 version is no longer the most current.
This integration works with both the Jira Cloud and Jira Server versions of Jira. Once you have added the Jira integration, you can directly import your feature backlog with the import from Jira functionality.
If you are using the on-premises version of Jira, you will need to create a firewall exception by allow listing IP addresses.
Click any of the following links to skip ahead:
Supported fields
This integration supports sending the following items:
Two Way Integration | One Way (Aha! Roadmaps to Jira) | One Way (Jira to Aha! Roadmaps) |
|
|
|
*Status updates flow from Jira to Aha! Roadmaps but not from Aha! Roadmaps to Jira. This is because once sent to development, the status of the feature should be owned by development, not product management. This ensures that product management won't inadvertently change a feature status while engineers are working on it.
**Comments that exist prior to creating the integration link do not get transferred. Any comments made after the link will be updated on either end.
Configure the integration
You need to be a workspace owner in Aha! Roadmaps and an Administrator in Jira to set up this integration. To authenticate the integration, Jira Cloud customers must use a Jira user's email address. On-premises Jira customers will use a Jira username (which may not be the same as the one you use to log into Jira). You can find this username in the Jira UI on your Profile page (under your photo in the top right corner). You may need to set the password associated with your Jira username on the Profile page, too.
If you are not an Admin in Jira, you will need an Admin to create a custom field on your behalf in order for the integration to work.
Please carefully follow these instructions to ensure that the integration is properly configured.
Step one: Add Jira account and mappings
Choose the workspace you want from the workspace hierarchy dropdown in the upper left of your screen, then navigate to Settings ⚙️ Workspace. Click on the + button next to Integrations.
Select Jira.
You need to configure a Jira user for this integration.
If you are using Jira Cloud, you will add the Jira user's email address and create an API token in Jira to use as your password. Failure to use an API token will result in a 403 error.
If you are using an on-premises installation of Jira, you will use a username and password to authenticate. Note: The Jira API does not support SSO authenticated users. So, if you use SSO to access Jira, you still need to configure a username/password combination.
Click the Test connection button to pull all available projects into Aha! Roadmaps.
Choose the Project that the issues will be created in.
Click Load project data to fetch the configuration for chosen project.
Map how you want features and requirements in Aha! Roadmaps to show up in Jira. Note: We have mapping recommendations for Jira Agile or Jira Standard.
Map how Jira statuses will align with your statuses in Aha! Roadmaps. Note: You can also customize your Aha! Roadmaps statuses
Review the check-boxes carefully to enable or disable functionality. You can always change these later. Note: Changing Send tags to enabled after an integration has mapped features may cause Aha! Roadmaps to remove labels on issues in Jira, if the tags do not already exist in Aha! Roadmaps when enabled.
Enable the integration.
Test the integration by going to one of your features in Aha! Roadmaps and selecting Integrations Send to Jira. You should then look at your project in Jira to make sure that the feature (and any requirements) were properly copied.
Note: You can add the integration multiple times if you want to integrate multiple Jira projects with a single Aha! Roadmaps workspace. Once you have added an integration, you may change the title to specify the project this integration belongs to by clicking on the title at the top of the integration set-up page.
Step two: Add the integration webhook
This will enable changes in Jira to be reflected in Aha! Roadmaps and make the integration two-way.
Copy the Webhook URL at the bottom of the configuration screen.
In the Jira administration section on the System tab, choose Webhooks.
Create a new Webhook in Jira and paste in the Webhook URL that you copied.
Check the boxes for all Worklog and Issue events.
Edit an issue in Jira linked to an item in Aha! Roadmaps to verify that the two-way workflow is working.
Note: Only one webhook should be created per Aha! Roadmaps account. This requires setting up the webhook with a run as user that has owner or contributor permissions to all workspaces in the Aha! Roadmaps account. Some companies will choose to add an integration user to their account for this purpose. All subsequent integrations will be two-way automatically. There are situations where you may want to use multiple webhooks.
Optional: Configure integration as a non-admin Jira user
In larger organizations it's unlikely that product managers and others who are setting up the integration with Jira will also have Jira admin privileges. This section explains how to integrate even if you are not an admin.
The administrator privilege in Jira is required to create a new custom field called Aha! Reference. If a Jira administrator manually creates the field first, then the Aha! Roadmaps user can get by with fewer privileges during the integration installation. Since custom fields are global in Jira, the administrator only needs to create this once.
Your Jira administrator should follow these instructions:
Create a new custom field in your Jira instance.
The custom field must be a URL type and be named exactly Aha! Reference. Aha! Roadmaps will use this field to store the link back to the related feature for each issue.
The field should be added to the default screen.
Now, when a workspace owner creates an integration in Aha! Roadmaps, Aha! Roadmaps will recognize this field when clicking Load project data and won’t try (and fail) to recreate it.
Note: If creation of Jira FixVersions is limited to Jira administrators only, you will also need to ensure your Aha! Roadmaps integration does not try to send releases. In your integration, select Don't send releases in this case.
Common record type mappings
Epics, stories, and sub-tasks
This is the most common configuration for Jira users, as it aligns closest to the Aha! Roadmaps data model. This mapping supports planning work at both the epic and the story level and accommodates for situations where teams have stories that exist by themselves without a relationship to a parent epic. This mapping also allows communicating epics that span across releases.
Aha! Roadmaps | Jira | |
Initiative |
| Epic |
Feature |
| Story |
Requirement |
| Sub-task |
An initiative in Aha! Roadmaps represents a large strategic effort or project that the team is working on. Initiatives can span across releases and contain many features. From this perspective, an initiative is very similar to an agile epic.
You can link features to an initiative in two different ways:
On the initiative detail view, click to the Related tab, then click Add to add features (epics, releases, or other records) directly to the initiative.
On the detail view of a feature, there is an Initiative field that allows users to link the feature to any initiative they have access to within the Aha! Roadmaps account.
The initiative cannot be sent to Jira by itself. Initiatives only send to Jira as part of sending a feature to Jira. When you send a feature to Jira that is linked to an initiative, the initiative will be sent as an epic and the feature will be sent as a story linked to the epic.
Epics and stories
This mapping is the second-most common. It is popular when the product team in Aha! Roadmaps plans all of their work at the epic level. Since Aha! Roadmaps requirements are mapped to the Jira story issue type, teams using this mapping cannot create stories that exist independent of an epic. Requirements in Aha! Roadmaps can only exist as part of an Aha! Roadmaps feature.
Aha! Roadmaps | Jira | |
Feature |
| Epic |
Requirement |
| Story |
Problem: Epic name or description is not updated from Jira to Aha! Roadmaps
The process of sending features to Jira creates a link between Aha! Roadmaps and Jira for the initiative, feature and requirement. The initiative name and description are carried over to Jira, but unlike the features and requirements, the initiative will not be updated by changes in the epic in Jira from that point forward. Similarly, any changes to the initiative you make in Aha! Roadmaps will not be reflected in Jira.
Unfortunately, there is an issue in the Jira API that prevents Aha! Roadmaps from changing the story/epic link after the records are initially created in Jira.
If work has not already begun, you could remove the link to that feature and resend. You'll find the link in the Integrations field midway down the feature's detail view. Click the More options by the Integrations field, then click Delete link to remove it.
Note: The API issue also means that if the feature is mapped to an initiative (different than the mapping above) while we can update the description, the name cannot be updated.
Top of article | Top of section
Map Aha! Roadmaps and Jira fields to each other
When you create an integration between Aha! Roadmaps and Jira, you get to customize how different fields in each product map to each other — including custom fields and Jira components.
Click any of the following links to skip ahead:
Map standard fields
You can map standard Aha! Roadmaps and Jira fields to each other right from the Field mapping sections of your integration settings. Add fields in either Feature field mapping or Requirement field mapping to get started.
Use the dropdowns to select the relevant field pairing, and use the + and - icons to add or remove pairings.
Map custom fields
The Jira integration supports field mappings between feature and requirement level custom fields in Aha! Roadmaps and fields in Jira. Both Jira and Aha! Roadmaps include the ability to create custom fields of various types. The integration supports a two way sync for the following Jira custom field types:
Checkboxes
Date Picker
Labels
Number Field
Radio Buttons
Select List (multiple choices)
Select List (single choices)
Text Field (multi-line)
Text Field (single line)
URL Field
User Picker
The following table is a list of the Jira custom fields supported by the integration and the Aha! Roadmaps custom fields that will support a two way sync.
Jira Field | Aha! Roadmaps Field |
Checkboxes | Pre-defined tags field |
Date Picker | Date field |
Labels Field | Pre-defined tags field, Tags field, Pre-defined choice list, Editable choice list |
Number Field | Number field |
Radio Buttons | Pre-defined choice list |
Select List (multiple choices) | Pre-defined tags field |
Select List (single choice) | Pre-defined tags field, Pre-defined choice list |
Text Field (multi-line) | Note field |
Text Field (single line) | Text field |
URL Field | Text field |
User Picker | Users field |
Note:
For any mapping using a pre-defined type field for Aha! Roadmaps, the defined choices in Aha! Roadmaps and Jira need to be perfect matches in order to work. This is an important item to consider if you're adding a custom field mapping between Aha! Roadmaps and Jira after records have been linked via the integration. Ensure that possible values are perfect matches in each system prior to activating the custom field mapping, to avoid potential overwriting of values in Jira from an integration update.
This only applies for custom fields at the feature or requirement level. Custom fields on initiatives when mapping initiatives to epics are not included as part of the integration.
Map Jira components
Aha! Roadmaps enables you to map custom fields from Aha! Roadmaps to Components and other fields in Jira. In both cases, the integration is one-way from Aha! Roadmaps to Jira. This means that changes will not be reflected back to Aha! Roadmaps from Jira.
Since Jira restricts the values that these fields can take, you must ensure all of the following conditions are met:
Configure the custom field in Aha! Roadmaps to only allow values that are valid for your Jira configuration.
The field can be named anything but its type must be Predefined tags field.
The tag values must exactly correspond to the possible Component values that are configured in Jira.
To map an Aha! Roadmaps custom field to Jira components:
In Aha! Roadmaps, create your custom field(s).
Go to your Integration configuration page in Aha! Roadmaps and click Load project data to trigger a refresh of available Jira fields to which you can map.
Add a field mapping between the custom field you created and the Component field in Jira.
Test by sending a feature with the custom field values selected to Jira. To do this, open a feature and click Integrations Send to Jira.
For each feature or requirement you want to send to Jira, make sure at least one component is chosen. If you do not choose a component that is required in Jira, you may receive an error: Remote error for create_feature: Data not accepted: components: Component/s is required.
Send Aha! Roadmaps feature rank to Jira
Without knowing which features provide the most business value you can quickly build yourself to nowhere. It’s critical to keep everyone on the same page, especially when deciding on what the development team is working on. An Aha! Roadmaps feature's rank helps you do this.
There are several ways to prioritize features within a release. The simplest way is to navigate to Features Board and drag and drop features into a prioritized rank. You can send this rank to Jira, where a Jira custom field can capture it for your development team.
In Jira go to your Settings Issues Custom Fields section and click + Add Custom Field.
Create a new custom field that is the Number Field type. Note: only the Number Field type will work.
Name the field Aha! Rank or Aha! Position. The name needs to be exact and is case sensitive.
Next, go back to Aha! Roadmaps and in your integration configuration for the Jira integration click Load project data. The Load project data action refreshes the fields that are available to integrate with through the API.
The integration will automatically map to the custom field you created in Jira. You are now set up to send the Aha! rank to Jira!
Considerations for Jira sprints
It is common to attempt to map a custom field in Aha! Roadmaps to the Jira sprint field. However, the sprint field is key to the operation of Jira. Changing the sprint affects a number of things. The Jira UI is able to display the sprint in a friendly way, but the API does not support translating the internal representation into a form that is useful to external systems. Unfortunately, this means that Aha! Roadmaps and other external systems cannot integrate.
Top of article | Top of section
Create an integration template
With configuration templates, you can save any Jira integration you create as a template and then apply that template to future Jira integrations. Changes made to the template will update all other integrations using the template, making it easy to administer a large number of integrations.
This is particularly helpful when managing credentials. A Jira admin can create the first integration with the Jira server, username, and password filled out. From that point on, Aha! Roadmaps workspace owners can use the template to avoid the need to request the credentials every time they add a new integration. If the credentials need to be updated in the future, updating the template will update the credentials for all other integrations.
If you are using Jira Cloud, you will need to create an API token in Jira to use as your password.
When a template is applied to a new Jira integration, the user that applied the template has the option to edit any of the configuration options they would like. This allows teams to quickly roll out configuration across multiple integrations while maintaining the flexibility to have unique options configured on a per integration basis.
Click any of the following links to skip ahead:
How it works
You will need to be a workspace owner in Aha! Roadmaps to create a Jira integration through the Settings ⚙️ Workspace area of your account. Once on the integration configuration page, click the More options button.
You will have the option to use an existing template or save the configuration you are working on as a new template.
If you save your current configuration as a template, it will be available to use for future integrations you configure.
If you chose to use an existing template, the configuration options from the template will be applied to your integration. Each configuration option will have a check box next to it allowing you to uncheck each field and apply a unique configuration option on a per field basis. For example, this means you can inherit user credentials and feature mapping from a template, but define custom field mappings unique to your workspace.
Security considerations
Since the templates allow credentials, and thus Jira access, to be used across an Aha! Roadmaps account, only users with access to the Aha! Roadmaps workspace containing the template will be able to apply the template.
In order to use a template defined on another workspace, you need at least viewer access on that workspace. Without full workspace owner access, the user will be able to use the template but will not have access to edit the template. This is particularly important because it allows for templates to be configured without the concern of other users editing the template and impacting integrations across the account.
Remove a template
In order to remove a template or delete an integration serving as a template, you first need to switch any integrations using that template to a different template. When viewing the template, there will be the option to view all integrations that are using the template.
Once all integrations using the template have been removed, the More options menu will allow you to to delete the integration or remove it as a template.
Top of article | Top of section
Import records from Jira
If you have workspace owner permissions, or have already set up a Jira integration, you can import issues directly into Aha! Roadmaps from Jira. There are two good reasons to do this:
To seed your account with features already captured in Jira.
To incrementally add features to Aha! Roadmaps that have been created in Jira after your initial upload.
You can also link features in Aha! Roadmaps directly to an existing issue in Jira. This is separate from the Jira import functionality and is done through the integrations dropdown next to the Integrations field on a feature. Once you import — or link your feature — the connection between the issue and your feature will be active.
Click any of the following links to skip ahead:
Which issues are imported?
The import allows you to enter JQL strings to filter what is imported. The default JQL string for the import is: status in (Open, "In progress," Reopened).
That means that by default it will import every issue matching those statuses. If you want to import only specific issue types or any type of other custom filters, please refer to the end of this section on the easy to way create your own JQL strings.
The handling of Jira Issues that are not included as part of the integration mapping will be dependent upon the integration configuration setting Only auto import mapped issue types. If the checkbox is selected, only issue types that are defined in the integration mapping and match the JQL statuses will be imported into Aha! Roadmaps as features and requirements. If this checkbox is not selected, issue types that match the JQL statuses but are not included as part of the integration mapping will be imported as features.
Which fields are imported?
Any of the integration fields available in the Jira integration to Aha! Roadmaps are supported in the import process. This includes epic, feature name (user stories), requirements (sub-tasks), description, attachments, custom fields for features or requirements, assignee, and estimates (story point or time).
How to avoid duplicate epics
If you have mapped Jira epics to Aha! Roadmaps initiatives, you should import epics before you start creating initiatives. This will avoid the creation of duplicate epics. If you do send the epics to Jira and get duplicates, you should move the existing Jira stories to the new Aha!-Roadmaps-created epic, rather than the other way around. This will correctly maintain the story links between Aha! Roadmaps and Jira.
Import estimates
When importing backlog items to Aha! Roadmaps from Jira, you can also import estimates. Make sure that Aha! Roadmaps and Jira are using the same unit of measure for estimates (time or story points).
If you are using time for your units of measure in the release, then the original estimate and remaining estimate are imported from Jira.
If you are using story points for the release you import into, then the current story points value will be imported into both the original estimate and the remaining estimate.
The feature logged effort will be updated to reflect work that has already been logged for that issue in Jira prior to the import.
You cannot import from Jira until you've configured the Jira integration.
Import features from development tool
Ensure that you are on the correct Aha! Roadmaps workspace by checking your navigation menu. Go to Settings ⚙️ Workspace Import from development tool. If you don't see this option, you either are on a parent line instead of a workspace or you don't have the proper user permissions.
Choose the Jira 1.0 integration that you want to use and click Save and continue. Click Continue in the pop-up message to redirect to the Jira 1.0 import.
Choose the Aha! Roadmaps release (or parking lot) where your Jira issues will be imported. Only issues that have not already been imported will be uploaded into Aha! Roadmaps from Jira.
Choose the Jira project that you wish to import from.
We suggest that you use the default filter to import all open, "in progress," or re-opened issues. You can also specify a JQL string that can be used to further filter the issues that will be imported.
Test the import. If the test is successful, we will return a message that shows the number of matching issues. This number will include issues that have already been imported into Aha! Roadmaps.
If you are not sure if issues have been uploaded before, it is safe to import again — no duplicates will be created.
Complete the import from Jira. Once you import, go to your features board to confirm that all of the issues were imported as Aha! Roadmaps features and requirements.
The import will take place in the background. It may take several minutes or longer depending on how much information must be imported.
Create a JQL string
You can quickly and easily create a JQL query to filter information that you have imported from Jira.
1. Use the Search for issues feature in Jira to add filters that will select just the issues that you want to import. For example, you could search by project, by status, or both. If the syntax is wrong when you type in your search, Smart querying should be activated. It will cause the JQL string to appear in your search bar and prompt you for what you want to search.
2. Click the Basic link next to your search results if you don't already see the Advanced link.
2. Click the Advanced link to the right of the search bar to see the JQL expression that corresponds to these filters:
3. Copy and paste the JQL into the Aha! import window.
Top of article | Top of section
Advanced Jira integration functionality
Click any of the following links to skip ahead:
Enable issues created in Jira to automatically populate Aha! Roadmaps
Customize what issues get created from Jira to Aha! Roadmaps
Enable issues created in Jira to automatically populate Aha! Roadmaps
Aha! Roadmaps' integration with Jira is two-way. This means that once a link is established between Aha! Roadmaps feature/requirement and Jira issues, updates are bi-directional and automatic. Links are established one of two ways:
You send features to Jira from Aha! Roadmaps
You import backlog items from Jira to Aha! Roadmaps
Aha! Roadmaps is where you plan and vet your releases and features. However, once you send features to Jira, they may be split into additional user stories or sub-tasks. It's also possible that they — and existing issues in Jira — may be moved into a version or user story already linked to Aha! Roadmaps records. This is especially common when using sub-tasks in Jira or mapping Aha! Roadmaps features to Jira epics. When this occurs and the issue in Jira gets created in Aha! Roadmaps, the Jira issue will update to include the Aha! Reference ID.
The two-way integration with Jira supports two workflows where items in Jira automatically populate back into Aha! Roadmaps.
If a new issue is created in Jira and linked to an existing Aha!-Roadmaps-linked parent item (mapped to Release or Feature), it will automatically be created in Aha! Roadmaps.
If an existing Jira issue is moved under an existing Aha!-Roadmaps-linked parent item (mapped to Release or Feature), it will also be automatically created in Aha! Roadmaps.
Common parent items are: Fix Version, Epic (if mapped to Features), User Story (if mapped to Features). Any issue in Jira that is mapped to Features in Aha! Roadmaps is potentially a parent item.
Examples:
An existing Jira issue is moved to a Fix Version associated with an Aha! Roadmaps Release, a feature will automatically be created in Aha! Roadmaps under that release.
Aha! Roadmaps Features = Jira User Stories and Aha! Roadmaps Requirements = Jira Sub-tasks; a feature is sent to Jira, then a sub-task is added to the user story in Jira and a requirement is added to the feature in Aha! automatically.
Aha! Roadmaps Features = Jira Epics and Requirements = Jira User Stories; Stories created in Jira and associated with the Epic will populate as a requirement under the feature in Aha! Roadmaps.
Customize what issues get created from Jira to Aha! Roadmaps
In some cases, you may not want all issues to be created in Aha! Roadmaps automatically. You can manage what automatically gets created in Aha! Roadmaps through a couple of different settings in the Jira integration configuration page or by directly editing the webhook in Jira. There are two common scenarios:
Scenario 1: You don't want Aha! Roadmaps to create any features automatically from issues added in Jira.
Check the Don't auto import checkbox in the integration configuration page to prevent Aha! Roadmaps from automatically importing issues that are related to an issue already linked to Aha! Roadmaps.
Alternative solution: Modify your existing webhook and disable the Issue Created event. This will prevent Jira from notifying Aha! Roadmaps about new issues.
Scenario 2: You want to limit which issues are converted to features.
Check the Only auto import mapped issue types checkbox in the integration configuration page to prevent Aha! Roadmaps from automatically importing issue types that are not mapped to features or requirements. Note: if this is not checked, unmapped issue types are automatically imported as features.
If you wish to be able to import issue types beyond the integration mapping for features, uncheck the Only auto import mapped issue types checkbox and edit the webhook instead. Add a JQL query to the webhook that will only allow the issue types that you want to be automatically created in Aha! Roadmaps. For example: issuetype in (Epic, "User Story", Sub-task)
This will cause Jira to only notify Aha! Roadmaps of new issues that match your criteria. For help with JQL see the bottom section in Import features from Jira.
Aha! Roadmaps releases and Jira fix versions
An entire release in Aha! Roadmaps can be sent to Jira. To do this, open a release in Aha! Roadmaps and in the Integrations field, select Send to Jira. Aha! Roadmaps maps a release to a Jira Fix Version. There is an option in the Aha! Roadmaps integration configuration to disable this if you do not want to have Aha! Roadmaps create Jira fix versions or update the FixVersion field. This can be desirable if the development team is referencing multiple FixVersions per feature in Jira, as otherwise Aha! Roadmaps will overwrite the multiple FixVersion references on a feature in Jira and update FixVersion with the feature's Aha! Roadmaps release.
When a release is first sent to Jira, a corresponding fix version record will be created in Jira. The name and date on the fix version will be based on the Aha! release.
Each time the release is sent to Jira again, the name and release date will be updated to match the Aha! Roadmaps release. Changes to the fix version in Jira will not be reflected back in Aha! Roadmaps.
Each feature in the release which has a corresponding issue in Jira will have its version field set to the fix version that was created. When features are moved between releases in Aha! Roadmaps the version field in Jira will be updated to match.
If a fix version already exists in Jira with the same name as the Aha! Roadmaps release, then a new fix version will not be created. A link between the Aha! Roadmaps release and the Jira fix version will be created.
Data deletions
Aha! Roadmaps never deletes issues from Jira. Any feature or requirement that is deleted from Aha! Roadmaps will not cause deletions in Jira. Likewise, deleted issues in Jira will not cause features or requirements in Aha! Roadmaps to be deleted.
This is to protect against inadvertently deleting another team's work.
Sync comments
Collaboration between the product and development team is essential. The Jira integration supports two-way updates of comments where comments added in either application will be reflected back and forth. However, due to API limitations, they will show up as written by the user with which the integration was configured.
Comments on a feature in Aha! Roadmaps are not sent over initially. Once the feature has been sent to Jira, any future comments will be updated on either end.
Sync capacity estimates
The Jira integration supports syncing either story point or time-based estimates between Aha! Roadmaps and Jira. This is a valuable part of the integration for any team looking to create high level estimates in Aha! Roadmaps and then allow the development team to take those estimates and update them with actuals once they start working.
Additionally, when syncing time-based estimates, work logged against the estimate will automatically reflect back into Aha! Roadmaps as logged effort on the Aha! Roadmaps record. This allows your team to track progress as it happens.
How it works
First, navigate to Settings ⚙️ Workspace Configure and enable capacity planning. You will need to be a workspace owner to do this.
Note: If you plan to sync estimates between Aha! Roadmaps and Jira you want to perform this step before importing any records into Aha! Roadmaps from Jira. Failure to do so can result in zeros being sent from Aha! Roadmaps to Jira as Aha! Roadmaps will default to have no value for estimates when this option is initially enabled. Aha! Roadmaps cannot undo this, so you will need to roll back your Jira server or manually fix the estimates by going through your Jira history.
Once you enable capacity planning in Aha! Roadmaps, you can select between having the estimates Associated with features or Associated with requirements. This is particularly important for the integration because of differences between how Aha! Roadmaps and Jira fundamentally handle estimates.
Aha! Roadmaps aggregates estimates from the requirement to the feature. This means if you have two requirements, each with 5 points of effort associated with them, your feature will have a total of 10 points of effort.
Jira does not work this way. In Jira, the story points for the epic and its user stories are added together. An epic can have 20 points of effort while the two stories contained in the epic each have 5 points — the total effort for the epic and its user stories would then be 30 points.
This causes a data mismatch between the two systems. To resolve this, Aha! Roadmaps only syncs feature or requirement estimates based on if you enabled estimates for features or requirements in your account.
If you enable it for features, changes to the Jira user story estimates will have no impact on Aha! Roadmaps.
If you enable it for requirements, changes to the Jira epic estimates will have no impact on Aha! Roadmaps.
With the Aha! Roadmaps configurations set, you can now import your Jira records and you will see any estimates that existed in Jira automatically populated into Aha! Roadmaps.
Problem: inflated estimates
For this integration, Aha! Roadmaps assumes that the default time tracking value of minutes is configured in Jira. If you have a different value configured in Jira you will see inflated estimates synced between the two systems when syncing time based estimates.
To resolve this, you will need to change your Jira configuration.
Assignee mapping
Both Aha! Roadmaps features and reviewers can be assigned to Aha! Roadmaps users. If Jira user is also an Aha! Roadmaps user in your account, you can map assignees between the two.
Assignees are mapped based on their email address. They must be using the same email address in both systems for the mapping to happen. If a user with the same email address is not found in the other system, then no change to the assignee is made (for data flowing in either direction).
When features or requirements are sent to Jira, the Reporter field will be set to the Jira user who has the same email address as the Aha! Roadmaps user who originally created the feature or requirement.
Other
Sometimes, changes are made to fields in Jira that are not mapped to Aha! Roadmaps fields. In this case, a comment will be added in Aha! Roadmaps noting the situation.
Once Aha! Roadmaps records are linked to Jira records, changes in the structure of the records will not be synced (e.g. changing a feature to be a requirement or changing a requirement to be a feature).
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.
