To avoid redundant third-party notifications, changes to the text editor are delayed by at least five minutes, waiting for five minutes after the most recent change.
Aha! Roadmaps | Integrate with Jira
Work closely with your engineering team in Jira to ensure that everyone is on the same page — and that your product is being developed in the most efficient way possible.
Ready to get started? This article will walk you through the key benefits of the integration, how to get set up, and then how to import your product backlog from Jira.
Note: If you have already set up an integration with Jira and are looking for more details, check out these articles to help you further customize or troubleshoot your configuration.
Click any of the following links to skip ahead:
Key benefits
Get set up fast: Enable your Jira integration in five steps so you can start prioritizing work in Aha! Roadmaps immediately, and send it to Jira for implementation.
Customize your integration: Control which records will be sent from Aha! Roadmaps to Jira and how standard and custom fields will map.
Bring in your backlog: Automatically import features from Jira to Aha! Roadmaps to establish your product backlog — without impacting any of your existing Jira data.
Foster collaboration: Enable bi-directional updates so product management and engineering teams can easily share information, ask questions, and stay informed of updates.
Streamline reporting: Automatic data syncing ensures that your roadmaps and reports are always current — so you can spend less time chasing status updates.
Set up your first integration
Before we dive into the details of integration configuration, let's take a step back to understand how both tools fit in your product development process.
Aha! Roadmaps should come first in the process, as this is where you set your strategy, define the product roadmap, and prioritize what to build and when. Jira is where your engineering team plans and manages how the work will get done.
First we will integrate with Jira. Then in the next section, we will walk through how to import and link to your existing product backlog.
Click any of the following links to skip ahead:
Enable the integration
To configure your first Jira integration in Aha! Roadmaps, you will need your Jira account URL, Email address, and API token. (If you do not have an API token already, you can Generate one).
Any workspace owner in Aha! Roadmaps can enable this integration. To get started, navigate to Settings ⚙️ Workspace, and then click the + icon next to Integrations in the left navigation bar. Choose Jira to open the integration builder!
Start
Name your integration. Give it a unique name, in case you set up more of these later.
Configure account
Server URL: Make sure you enter the URL used to access Jira without a trailing slash, e.g. https://fredwin.atlassian.net.
Username and Password: You need to configure a Jira user for this integration.
If you are using Jira Cloud, you will add a Jira user's email address and that user will need to create an API token in Jira to use as your password. If they do not use an API token, the integration will break with a 403 error.
If you are using an on-premises installation of Jira, we recommend entering a username and generating a personal access token to authenticate. You can also use a username and password.
Password type: Choose the type of password you are adding. Choices are API token, Password, and Personal Access Token (PAT).
If you are using Jira Cloud, you must choose API token.
For Jira on-premises, you can choose Password or Personal Access Token (PAT).
Validate certificate: Check this to validate your server's HTTPS/TLS certificate when you click Save and continue to move to the next step. Leave this box unchecked if you do not have a hostname to verify the HTTPS/TLS certificate against.
Select Jira project
Select a Jira Project to link with your Aha! workspace. The Project you select will populate the field mappings in the next step.
(Optional) Select a Board within your Project. This is useful if want to map to the Jira Sprint field.
(Optional) Configure mappings
In this step of the integration builder, you get to define what record types are equivalent between Aha! Roadmaps and Jira, and what fields on those records should update each other.
But you can also start with the default settings, which map equivalent statuses and fields to each other across the two products. You can map the record types like this:
Epic < Epic
Feature < Story
Requirement < Sub-task
Release < Version
If the default mappings look good to you, move on to the final step of the integration builder.
If you want to configure detailed mappings now, check out our recommendations!
Enable
So far you have successfully configured a one-way integration, from your Aha! account to Jira. The Enable step of the integration helps you make the integration two-way — so your Aha! workspace and Jira project can update each other.
If you just want to send work to Jira, then the previous steps set that up for you already. Click Enable integration to get going!
Bi-directional integrations can be incredibly valuable. Send work to Jira, and get effort estimates, status updates, and comments back — so your product roadmap can accurately reflect progress. To do this, you will need a Jira webhook.
Webhook
Webhook URL: Copy the webhook URL here. Then navigate to Jira:
From the Jira administration section on the System tab, click Webhooks.
Create a new webhook and past in the webhook URL that you copied.
Check the boxes for all Issue link, Issue, Version, Worklog, and Comment events.
Save your webhook.
Back in your Aha! account, click Enable integration.
Each Jira integration's webhook runs as a particular user. That user needs to have permissions in your Atlassian account. You can only access parts of Jira that your integration Run as user has access to.
(Optional) Generate recommended JQL query: You probably want your webhook to pull in only the data that is relevant to your Aha! workspace. If you want help with that query, click Generate recommended JQL query, then paste the result into the Issue related events section of your Jira webhook configuration.
Importing
To specify how updates from Jira are sent to Aha! Roadmaps, select an option in the Importing section:
Approve new records before importing: Records will not be imported until they are approved. Navigate to Settings ⚙️ Integration updates to review those integration changes.
Automatically import new records: Records will be imported automatically to Aha! Roadmaps from Jira. This applies to records which are created as child records of previously linked initiatives, releases, epics, and features.
(Optional) Add a JQL query to filter the records that will be available for import.
Sending
Finally, decide how you want to send and receive data through this integration.
To specify how updates from Aha! Roadmaps are sent to your development system, select an option in the Sending section:
Approve outgoing changes: Allows teams that are new to the integration to validate what is being sent to their development system and prevent unintentional changes from going through. We recommend this option until the team is familiar with how the integration works. Then you can switch to automatic sending.
Automatically send outgoing changes: Automatically sends changes to Jira and does not require manual approval.
Send work to Jira
Congratulations! You can now send records from Aha! to Jira for development (and if you completed the Enable step, you can get updates back, too!). Let's try it.
Navigate to Features Board and open a feature that engineering should work on.
Under the Integrations field, click the Plus [+] icon.
Select your new Jira integration.
Your feature will now be created in a Jira project as a new issue — and you will be able to see a link to the Jira issue from your Aha! Roadmaps feature. Click that link any time to move to Jira and check the issue status or collaborate with engineering.
Next, try to send a release from Aha! Roadmaps to Jira. When you do, you will also send all the features in the release, so engineers can see broader context (and so you do not have to send one feature at a time).
Customize the integration
Your integration uses default record and field mappings — which work for most users, especially users who are trialling Aha! Roadmaps for the first time. But if you choose to, you can customize this integration to exactly match your organization's data structure and engineering workflows.
We have covered this topic in detail in three articles:
Configuration walkthrough: From user permissions to data security, this article walks you through the details of Jira integration customization and management.
Recommended record mappings: Do you think of Aha! Roadmaps features as Jira stories — or epics? Use this article to configure Aha! and Jira record types.
Field mappings: Custom and standard fields help you prioritize work and track business-critical information. Use the Mappings step of your integration configuration to map fields between your Aha! workspace and Jira project, as well as choose which direction you want data to flow.
Import your Jira backlog
Streamline your backlog management. Use parking lots in Aha! Roadmaps for managing your product backlog and prioritizing features for release. Use the engineering backlog in Jira to manage work that has been assigned from product management as well as other technical work.
Now that you have a new Jira integration, you can import any backlog items that need moving from Jira to Aha! Roadmaps.
Some product backlogs are hundreds or thousands of records — and you do not have to import all of them. Use custom JQL filters such as project or issue status to pull in just the records that a product team needs to track, without changing the original Jira records at all. Then, link those records to your strategic plans, and take advantage of your Jira integration's real-time bi-directional updates and custom field mappings.
Note: If you import the wrong records, or too many records, do not worry! You can delete your imported data in your Aha! account and start over until you get it right. The original records in Jira will never be affected.
Click any of the following links to skip ahead:
Confirm user permissions
Since we will be importing a Jira project's backlog to an Aha! Roadmaps workspace, you will need the following user permissions.
Action | User permissions |
Create or edit a Jira integration | |
Use the Jira backlog importer | |
Pull records from Jira | Appropriate Jira user permissions for the integration's Run as user. |
This last Action can catch users unaware, so it is worth highlighting. Each Jira integration's webhook runs as a particular user. That user needs to have permissions in your Atlassian account. You can only import parts of your Jira backlog that your integration Run as user has access to.
Select an integration
First, select a Jira integration.
From the hierarchy dropdown menu, select the Aha! Roadmaps workspace where you want to import the Jira backlog.
Navigate to Settings ⚙️ Workspace Import from Jira, Azure, Rally, and more.
Choose a Jira integration. In this case, we have an existing integration so you will select Existing integration, choose Jira, then click Next.
Choose record types
Next, choose what record types we want to import from Jira to the Aha! workspace. There are several different ways to map Jira records to Aha! Roadmaps records. In this case, we have chosen this structure:
Jira record type | Aha! record type |
Epic | Epic |
User story | Feature |
Sub-task | Requirement |
Version | Release |
Check the box beside the record type(s) you want to import.
Apply an optional JQL filter. You can filter each record type with custom JQL strings. In fact, you can paste any custom JQL you create in your Jira account right into these JQL filter fields.
Click Save and continue to move on.
Review and import
You can preview the first 10 records of each record type that you chose to import. If you see unexpected records in this list, go back a step and adjust your JQL filters.
If everything looks great, then click Import records to complete the backlog import.
After the importer completes, you will see a breakdown of the records imported, plus any errors — records that already exist in your Aha! account, or records that you did not have permission to access in Jira. The backlog importer will pull in any of the records you select that the integration's Run as user has access to — so remember, you might have access to a record in Jira that your integration does not.
When the import completes, you can run it again, or import records from another integration — useful if you want to import a separate Jira project backlog. For now, though, you have successfully imported!
Check your new Aha! records
Now that the import is complete, it is time to review the backlog in your Aha! workspace.
Navigate to Features Board. You can see the newly imported backlog in its various releases.
Open a feature. Under Integrations, you can see a link to the original Jira record. The Aha! and Jira records are now linked bi-directionally, using the integration configuration and field mappings of the integration you used for the original import.
From here, you can add links to product strategy, prioritize the work with the product value score, or start discussions with engineering teams in comments.
The Jira backlog import is a one-time step to help you get started. Now that you have data in Aha! Roadmaps, it is time to refine your product plans based on your overarching strategy — and prioritize what to build next.
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.
