This support article refers to the 2.0 version of the Aha! integration with Jira. For the 1.0 version, see Integrate with Jira cloud & on-premise (integrations 1.0).
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
Configure the Jira integration
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 with proper access to create and edit records in Jira for the project you plan to integrate with.
- Navigate to Settings > Product, and then click the + icon next to Integrations in the left navigation bar.
- Choose Jira in the Integrations 2.0 grouping.
- Enter a name in the Integration name field, and then click Save and continue.
Note: You should name your integration with a unique identifier based on the configuration settings you make — especially if you plan to have multiple Jira integrations for a single Aha! product.
- On the Configure Account tab, enter the following information, and then click Save and continue.
- 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 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.
- In the Select Jira project tab, choose the project where issues will be created and synced with Aha! records. The project selection determines the mapping options that will appear on the next page. You will also be presented with the option to select a board within that project. This is used for sprint creation if you chose to map to the Jira sprint field. Click Save and continue once done.
- In the Mappings tab, you can configure how records are mapped in Aha! to records in your Jira project. The default mappings are based on what is most widely used by our customers. You can remove the default mappings and add your own based on what makes sense for your team and how you work.
- For each record mapping, you can also 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.
- Tip: If you have configured required fields in Jira, we recommend setting the Required flag on those fields in the custom layout associated to your product. This will ensure that any required fields are populated when records are created on the Aha! record creation form.
- The relationship links are important to understand because they determine the ability to communicate relationships between records to and from Jira. Without these links, records sent between systems will not have an appropriate association with one another. These links are automatically applied by default and should only be a concern if you replace record mappings altogether.
- While not every organization needs to customize their field mapping, you do need to define the way statuses are mapped.
- For each record, click the Field mapping link below the first field.
- Locate the Status field at the bottom of the section, and then click the Configure link.
- In the Configure modal, matching values are automatically mapped initially, and then you can manually rearrange statuses to your preferred mappings as needed. Values may map one-to-one or one-to-many.
- Click Save and continue.
- In the Enable tab, copy the webhook URL from the Webhook URL field.
Note: This is a critical step in the integration configuration as it allows the integration to function in a two-way capacity. A Jira administrator user is required to log into Jira. 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! To learn more about webhooks, see "How Aha! webhooks work for Jira Integrations (1.0 and 2.0)."
- Open Jira, navigate to the administration section on the System tab, and then choose Webhooks.
- Create a new webhook in Jira, and then paste in the webhook URL that you copied from Aha!
- Select all of the following checkboxes: Issue, Version, Worklog, and Comment events.
- Save the webhook.
- To specify how updates from Aha! are sent to your development system, select an option in the Automatic 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, at which point, you can switch to automatic sending.
- Automatically send outgoing changes: Automatically sends changes to Jira and does not require manual approval.
- To specify how updates from Jira are sent to Aha!, select an option in the Automatic import section:
- Approve new records before importing: Records will not be imported until they are approved. An orange dot will appear on the Settings icon in the header when new records are ready for approval.
- Automatically import new records: Records will be imported automatically to Aha! from Jira. This applies to records which are created as children of previously linked initiatives, releases, master features, and features.
Test the integration
Now, you can test the integration by sending a feature to Jira following these steps:
- Navigate to Features > Board.
- Click on a feature card, and select Send > Send to Jira in the Integrations section. A link to the Jira record should display in the Aha! feature after a few seconds. You can click on it to make sure that everything was sent to Jira correctly.