Coming soon: We are introducing a fresh new look for record drawer and details pages on September 30, 2020. This article describes the current experience. Preview the upcoming improvements in your account now so you can get familiar with the new way of working in Aha!
Aha! is a tool that helps teams set their strategy and link it to their planned work. Jira is a tool that helps you track projects and get work done. They pair perfectly. By integrating Aha! and Jira, you can link your work to your strategic vision, share context with development teams, and track your progress in roadmaps and reports.
Click any of the following links to skip ahead:
- How to think about the integration
- Configure the integration
- Configure mappings
- Enable the integration
- Add additional security
- Test the integration
- Manage your integration
|Required user permissions:
|Required user permissions:
|Associated record types||
How to think about the integration
The Aha! Jira integration is two-way, which means information can be updated in either tool. Send your planned work to Jira, get notified when the Jira issue's status updates, and use comments to keep each team up to date.
Before configuring any integration for the first time, it is important to fully understand how to think about integrating Aha! with your development tool. Aha! should come first in the process —build out or import your records in Aha!, then send them to Jira. You can customize the ways that fields map to each other between the two tools, and even customize whether you want integrated records to update automatically, or only after your review.
This integration supports sending the following Aha! records to Jira:
- Releases / Schedules
- Features / Activities
Configure the Jira integration
- If you need to connect to multiple Jira servers, please reach out to the Customer Success team at email@example.com. We need to toggle a back-end setting to enable this to work smoothly. If you create a Jira integration that connects to multiple Jira servers without this setting enabled, you may see data mis-matched (e.g. a comment on a linked record appearing on another linked record in a different workspace).
- This integration works for Jira Next-Gen and Jira Portfolio projects, though there are some limitations.
- 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).
To set up an integration with Jira, you need to be a workspace owner in Aha! for the workspace 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 ⚙️ > Workspace, 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! workspace.
- 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.
- If you have configured required fields in Jira, we recommend setting the Required flag on those fields in the custom layout associated with your workspace. This will ensure that any required fields are populated when records are created on the Aha! record creation form.
- You can map the Jira issue resolution field to Aha! as a one-way field mapping. This allows you to show an issue's status (e.g. Closed) as well as its resolution (e.g. Won't Fix).
- 2.0 integrations with Jira can also map record relationships. Read this article to find out how.
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 ⚙️icon.
- 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 to save your mappings.
Enable the integration
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 child records of previously linked initiatives, releases, epics, and features.
Add additional security
2.0 integrations with on-premises tools have the option to include a client certificate for added integration security.
To set a client certificate, open your integration settings and click the More options icon in the upper right, then click Set client certificate. From here, enter the private key and certificate — we recommend creating a private key and client certificate specifically for this purpose — and click Save to save your changes.
Note: This feature will only provide additional security when the server that Aha! is communicating with validates the certificate. This is usually only possible with customer-configured on-premises integrations. Client certificate authentication is in addition to the standard username and password/token authentication and is not a replacement.
Test the integration
Congratulations! You're ready to test your new integration. To do this, send a feature to Jira by 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.
Note: You also have the ability of manually bulk sending a subset of features to Jira.
Manage your integration
If you have multiple Jira integrations that you need to manage, use the Manage integrations report, located in:
- Settings ⚙️ > Account > Integrations for account-level integrations.
- Settings ⚙️ > Workspace > Integrations for workspace-level integrations.
If you run into difficulties with your Jira integration, you can find answers to common problems in the Jira section of the knowledge base.