Aha! Roadmaps | Integrate with Jira (integrations 2.0)

Successful products do not happen by accident. They are often the result of seamless collaboration between product and development teams. Developers need strategic context for their work. Product managers need progress updates to inform their roadmap.

But all too often, product managers have to use developer tools just to provide context and track updates — then manually update their own product plans elsewhere. They spend their days in multiple tools, trying to bring strategic vision and successful go-to-markets together.

The integration between Aha! Roadmaps and Jira keeps product and development teams in their tools of choice — without sacrificing context or collaboration. Two-way updates mean that strategic and progress updates flow back and forth in real time. And you can customize the integration to match your team's workflow and terminology.

Join our next live tutorial to see the integration in action

In this article, we will walk through how to configure and customize an integration with Jira.

Click any of the following links to skip ahead:

• Prerequisites

• How to think about the integration

• Configure the integration

• Configure mappings

• Enable the integration

• Add additional security

• Test the integration

• Data deletion

• Manage your integration

Prerequisites

Top

How to think about the integration

The Aha! Roadmaps 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! Roadmaps with your development tool. Aha! Roadmaps should come first in the process —build out or import your records in Aha! Roadmaps, 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! Roadmaps records to Jira:

• Initiatives

• Releases / Schedules

• Epics

• Features / Activities

• Requirements

Top

Configure the integration

Note:

• If you need to connect to multiple Jira servers or Jira Cloud accounts, please reach out to the Product Success team at [email protected]. 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 or accounts 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 team-managed and Jira Advanced Roadmaps projects, though there are some limitations.

• This support article refers to the 2.0 version of the Aha! Roadmaps 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! Roadmaps 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.

1. Navigate to Settings ⚙️ Workspace, and then click the + icon next to Integrations in the left navigation bar.

2. Choose Jira in the Integrations 2.0 grouping.

3. 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! Roadmaps workspace.

4. 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 the person configuring the integration will need to 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-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.

5. In the Select Jira project tab, choose the project where issues will be created and synced with Aha! Roadmaps 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.
   
   Note: Once you select a project, you should not rename your project key in Jira. The integration may continue to work, but certain functionality such as the ability to Reload configuration on the Mappings step of the integration will break.

Top

Configure mappings

In the Mappings tab, you can configure how records are mapped in Aha! Roadmaps 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! Roadmaps and Jira — as well as what relationship links exist for those records.

Note:

• 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! Roadmaps record creation form.

• You can map the Jira issue resolution field to Aha! Roadmaps 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.

Top

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! Roadmaps.To learn more about webhooks, see How Aha! Roadmaps 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! Roadmaps.

• Select all of the following checkboxes: Issue, Version, Worklog, and Comment events.

• Save the webhook.

To specify how updates from Aha! Roadmaps 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! Roadmaps, select an option in the Automatic import 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.

Note: If a feature's parent release is not linked with Aha! Roadmaps, or if releases are not mapped with the development system at all, then the feature will be imported into the first parking lot release. This is by design, since the parking lots are repositories for unscheduled work.

Top

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.

If you use an integration template to manage multiple integrations in the same workspace, set the client certificate in your integration template. That way, you only need to set the client certificate once.

Note: This feature will only provide additional security when the server that Aha! Roadmaps 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.

Top

Test the integration

Congratulations! You're ready to test your new integration. To do this, send a feature to Jira by following these steps:

1. Navigate to Features Board.

2. Click on a feature card, scroll to the Integrations section, then select Send to Jira. A link to the Jira record should display in the Aha! Roadmaps 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.

Top

Data deletion

Now that records are flowing between Aha! Roadmaps and Jira, let's talk about what happens when you delete a record in either tool.

If you delete a record in Aha! Roadmaps, it will not delete the record in Jira. Likewise, if you delete a record in Jira, it will not delete the record in Aha! Roadmaps. This is intentional, so that one team cannot delete another team's work.

Top

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, start with the integration logs. Next, review answers to common problems in the Jira and Jira troubleshooting sections of the knowledge base.

Top