This support article refers to the 2.0 version of the Aha! integration with Jira. For the 1.0 version, please reference this document.
Aha! provides a two-way integration with Jira that allows product teams to send their planned work from Aha! to their development team working in Jira. Before configuring any integration for the first time, it is important to fully understand how to think about integrating Aha! with your development tool.
This integration supports sending the following Aha! records to Jira:
- Master features
The above Aha! records can be mapped to any issue in Jira, including both standard and sub-task types.
To set up an integration with Jira, you need to be a Product Owner in Aha! for the product you wish to integrate. You will also need to have a Jira account that has proper access to create and edit records in Jira for the project you plan to integrate with.
1. Navigate to "Settings > Product" and press the "+" next to "Integrations" on the left side navigation bar. Choose Jira from the integrations 2.0 grouping.
2. This will launch the integration configuration wizard. The first step is to name your integration and, optionally, select a template if you have already created one. Click "Save and continue."
3. Next, you will be prompted to authenticate, which will require you to enter your Jira username and password. Please note that if you utilize SSO to access Jira, you will need to configure a Jira username/password authenticated user for this. The Jira API does not support SSO authenticated users.
4. After authenticating, you will be prompted to choose which project in Jira you wish to integrate with. The list presents the projects that the username used in step #3 has access to.
5. Next comes record mappings. This step allows you to configure how Aha! records are mapped to your Jira records. The default mappings are based on what is most widely used across our customers. However, you are free to remove the default mappings and add your own in order to map records together based on what makes sense for your team and how you work.
6. For each record mapping, you also have the option to specify your field mappings. This allows you to completely configure how each field within the record is mapped between Aha! and Jira — as well as what relationship links exist for those records.
The relationship links are important to understand because they establish the ability for records created in your development system to be automatically imported into Aha! in certain use cases. You can learn more about them here.
7. While not every user will need to customize their field mapping, you do need to define the way statuses are mapped. Within the field mapping section for each Aha! record, there is a line for "Status" with a configure gear icon at the far right. Click the gear icon to open up the status mapping window.
8. When mapping statuses, you will be presented with your Aha! status workflow for the record type on the left and your integrated system status workflow on the right. You can drag-and-drop the statuses to create groupings and mappings. In the above screenshot, you can see that multiple statuses have been grouped together where the Jira statuses of "Resolved" and "Closed" are mapped to the Aha! statuses of "Ready to ship" and "Shipped."
9. With your records, optional field mappings, and statuses defined, you can click "Save and continue" to move onto the last step in the workflow. The "Enable" step allows you to specify how updates from Aha! are sent to your development system. The default is for the user to approve outgoing changes. We recommend this option until the team is familiar with how the integration works, at which point you can switch to the automatic sending of changes. The approval option allows teams that are new to the integration to validate what is being sent to their development system, which can help prevent unintentional changes from going through.
10. This last step contains the webhook. This is a critical step in the integration configuration as it allows the integration to function in a two-way capacity. You will need an admin user in Jira to log in and add the webhook in the Jira account's system settings. While every integration you configure contains a unique webhook, only one webhook is needed for most configurations. This is because the Jira webhook exists at a system level and, as such, a single webhook can communicate account-wide changes back to Aha! You can read the full details around adding the webhook to Jira here.
11. Finally, test the integration by opening one of your features in Aha! and use the "Actions" menu option for "Send to Jira" You should see a link to the created Jira record appear on the Aha! feature after a few seconds. This will let you easily click into Jira to verify that everything was sent through correctly.