This support article refers to the historical 1.0 version of the Aha! integration with Jira.
- If you are using the new 2.0 version of our Jira integration, reference this article.
- If you are looking for details about how to setup the Jira 2.0 integration, reference this article.
This two-way integration allows you to push your releases, features, and requirements from Aha! to Jira. The Jira integration is our most popular, robust integration.
This integration works with both the Jira Cloud and Jira Server versions of Jira. If you are using the on-premise version of Jira, you will need to create a firewall exception: see the IP Whitelist doc article for help.
Once you have added the Jira integration, you can directly import your feature backlog with the import from Jira functionality.
This integration supports sending the following items:
|Two Way Integration||One Way (Aha! to Jira)||One Way (Jira to Aha!)|
*Status updates flow from Jira to Aha! but not from Aha! 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.
Since Jira is our most robust integration, there is also a set of advanced functionality explained here: Advanced Jira functionality
You need to be a Product Owner in Aha! 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-premise 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. There are two steps to this integration and both must be completed.
Step one: Add Jira account and mappings
- Navigate to the product you want to integrate using your drop down menu next to your home icon.
- Click on your name in the top right corner of Aha! and choose Settings -> Product. 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-premise 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!
- 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! to show up in Jira.
- Map how Jira statuses will align with your statuses in Aha!
- Note: You can also customize your Aha! statuses
- Review the check-boxes carefully to enable or disable functionality. You can always change these later, but note that changing the "Send Tags" to enabled after an integration has mapped features may cause Aha! to remove labels on issues in Jira, if the tags do not already exist in Aha! when enabled.
- Enable the integration.
- Test the integration by going to one of your features in Aha! and using the Send to Jira item in the Actions menu on the features page. 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! product. 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! 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! to verify that the two-way workflow is working.
Note: Only one webhook should be created per Aha! account. This requires setting up the webhook with a run as user that has product owner or contributor permissions to all products in the Aha! account. Some companies will choose to add an integration user to their account for this purpose. All subsequent integrations will be two-way automatically. Reference this article to understand common use cases for when multiple webhooks are needed.
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! 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.
The 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! 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 product owner creates an integration in Aha!, Aha! will recognize this field when clicking "Load project data" and won’t try (and fail) to recreate it.