Aligned Agility will be changing soon! Head to the Adaptavist blog to read the news from our CEO.
BLOG

How to Integrate Aha! Roadmaps with Jira

Peter Kerrigan
Image of arrow loop
Image of arrow loop

Aha! Roadmaps is an excellent tool for scaling and tracking your organisation's strategy and execution. 

To best report on the progress of high-level strategy and work, it is paramount to understand the work that the agile teams will complete. These teams have boots on the ground; they plan work, execute sprints, and release code (or other products) into production daily. To get the most accurate reporting in Aha! Roadmaps, you need to roll up all the teamwork by integrating your two systems. 

The following process outlines the best practices for configuring and managing your integration between Aha! Roadmaps and Jira Software.

Discovery work with your team

Suppose you are brand new to Aha! Roadmaps, or even if you have an existing environment, it is essential to perform a small discovery with the teams using Aha! Roadmaps to understand what their integration requirements are. 

To do this, perform the following steps to run this discovery process:

1. Validate the current parent line and workspace structure with the teams. An accurate design representing a work breakdown must be in place for the integrated data to roll up properly.

2. Ask the following questions to your teams who require integration:

a) Which Jira project(s) need to require integration? Which workspace should the project(s) integrate with?
b) What entities (i.e. Features and Stories) require integration?
c) What fields required integration for each entity type? Are any of these fields mandatory in Jira?
d) Do these fields need to be added or updated in either system (Jira Software or Aha! Roadmaps)?
e) Do workflow statuses correspond appropriately? Do any workflows need to be updated to meet requirements?
f) Will the integration for these fields be uni- or bi-directional?

3. Ensure Features and Requirements/Stories are active in the workspace navigation - allows users to access them once the integration is complete.

You can begin the integration process once you have completed all the pre-works.

Integration steps

To set up the integration, follow the steps below: 

1. Navigate to the settings of the workspace you want to integrate. 

On the left admin menu, select the plus (+) button beside "Integrations" at the bottom of the menu. It will then open up a new page showing all Aha! Integration options for Roadmaps. Select Jira Software as the desired app for integration.

Screenshot from Jira

2. Give your integration a name. 

Once fully set up, it is possible to use your integration as a template for other workspaces. If you intend to reuse your integration template, give it a generic name representing its full use case (i.e. "My Organization's Integration"). Click "Save and continue."

Screenshot from Jira

3. Now you will set up the connection between your Aha! Roadmaps environment and Jira Software

Fill in the requested details, but remember that the required data differs depending on your Jira Software hosting (cloud or On-Premise). 

Note: This step requires users to have Jira Admin permissions; coordination with your Jira Admin will be necessary if you need the appropriate permissions. See the additional steps below for setup: 

a) On-Premise versions of Jira will require a server URL, username, and password to authenticate the user. Depending on your organisation's requirements, you should have a dedicated service account for the integration.

b) Cloud versions of Jira will require a server URL, the username of the authenticating user, and an API token; the API token will require placing here instead of a password. If you are unsure how to generate an API token for Jira cloud or don't have the necessary permissions, reference this article or contact your Jira administrator.

Screenshot from Jira

4. Select the desired project and board to integrate; board selection is required to incorporate sprint data

Screenshot from Jira

Remember, each integration supports one Jira project. If you need to integrate multiple Jira projects with the same workspace, you can create another integration and select your other Jira project. Here is where the integration, as mentioned earlier, can be helpful.

5. Configure the details of your integration

Select the entity types you want to integrate (i.e. Feature and Story) and the field mappings. See the screenshot below and the steps to follow:

a) In this example, you can see that the Aha! feature record type is mapped to a Jira epic, and Aha! requirements are mapped to Jira Stories. If you click on the blue "Field Mapping" button, this will reveal the integration options for fields. The screenshot below shows the field integration details for a Feature/Jira epic.

screenshot from Jira


b) Each field can be integrated uni-directionally or bi-directionally, depending on your requirements; use the blue arrow icons in the centre of the field list to manage the direction of the field integrations. You must include the required fields in Jira within your integration; otherwise, data syncs between the two systems might fail. Reach out to your Jira admin if you need help determining which fields in Jira are necessary for this process step.

c) Status mappings have a practical level of granularity that allows you to map multiple statuses to one if required. In this example, our Aha! Roadmaps workflow matches our Jira workflow for Features/Epics, so the mapping is one-to-one and relatively simple.

Screenshot of Jira

d) If you have differing workflows between each system, you can also map multiple statuses to one; you will achieve this by dragging and dropping statuses to create groups. You should see branching indicator lines in the screenshot below if you have successfully grouped statuses.

Screenshot of Jira


6. After completing the integration setup for fields, select "Save and continue."

The system will bring you to a final review page for your integration. Indicate whether or not you want changes to continue for import and export manually or automatically, and select "Save and continue."

Your integration should now be ready for use. To run an integration test, you will need to carry out the following steps: 

  1. To test your integration, you can create a sample Feature and/or Story in Aha! Roadmaps and ensure it syncs properly to Jira. 
  2. Perform test changes to your work entity in both systems to ensure the bidirectional sync works as expected. 
  3. Change status, modify fields, and create additional work entities to ensure the smooth functioning of the integration. 
  4. If your entity does not sync or is syncing incorrectly, return to the integration setup to review your configuration and log messages. 

Need help with your current integration? We can help you solve it. Speak to an expert.

Aha! Roadmaps is an excellent tool for scaling and tracking your organisation's strategy and execution. 

To best report on the progress of high-level strategy and work, it is paramount to understand the work that the agile teams will complete. These teams have boots on the ground; they plan work, execute sprints, and release code (or other products) into production daily. To get the most accurate reporting in Aha! Roadmaps, you need to roll up all the teamwork by integrating your two systems. 

The following process outlines the best practices for configuring and managing your integration between Aha! Roadmaps and Jira Software.

Discovery work with your team

Suppose you are brand new to Aha! Roadmaps, or even if you have an existing environment, it is essential to perform a small discovery with the teams using Aha! Roadmaps to understand what their integration requirements are. 

To do this, perform the following steps to run this discovery process:

1. Validate the current parent line and workspace structure with the teams. An accurate design representing a work breakdown must be in place for the integrated data to roll up properly.

2. Ask the following questions to your teams who require integration:

a) Which Jira project(s) need to require integration? Which workspace should the project(s) integrate with?
b) What entities (i.e. Features and Stories) require integration?
c) What fields required integration for each entity type? Are any of these fields mandatory in Jira?
d) Do these fields need to be added or updated in either system (Jira Software or Aha! Roadmaps)?
e) Do workflow statuses correspond appropriately? Do any workflows need to be updated to meet requirements?
f) Will the integration for these fields be uni- or bi-directional?

3. Ensure Features and Requirements/Stories are active in the workspace navigation - allows users to access them once the integration is complete.

You can begin the integration process once you have completed all the pre-works.

Integration steps

To set up the integration, follow the steps below: 

1. Navigate to the settings of the workspace you want to integrate. 

On the left admin menu, select the plus (+) button beside "Integrations" at the bottom of the menu. It will then open up a new page showing all Aha! Integration options for Roadmaps. Select Jira Software as the desired app for integration.

Screenshot from Jira

2. Give your integration a name. 

Once fully set up, it is possible to use your integration as a template for other workspaces. If you intend to reuse your integration template, give it a generic name representing its full use case (i.e. "My Organization's Integration"). Click "Save and continue."

Screenshot from Jira

3. Now you will set up the connection between your Aha! Roadmaps environment and Jira Software

Fill in the requested details, but remember that the required data differs depending on your Jira Software hosting (cloud or On-Premise). 

Note: This step requires users to have Jira Admin permissions; coordination with your Jira Admin will be necessary if you need the appropriate permissions. See the additional steps below for setup: 

a) On-Premise versions of Jira will require a server URL, username, and password to authenticate the user. Depending on your organisation's requirements, you should have a dedicated service account for the integration.

b) Cloud versions of Jira will require a server URL, the username of the authenticating user, and an API token; the API token will require placing here instead of a password. If you are unsure how to generate an API token for Jira cloud or don't have the necessary permissions, reference this article or contact your Jira administrator.

Screenshot from Jira

4. Select the desired project and board to integrate; board selection is required to incorporate sprint data

Screenshot from Jira

Remember, each integration supports one Jira project. If you need to integrate multiple Jira projects with the same workspace, you can create another integration and select your other Jira project. Here is where the integration, as mentioned earlier, can be helpful.

5. Configure the details of your integration

Select the entity types you want to integrate (i.e. Feature and Story) and the field mappings. See the screenshot below and the steps to follow:

a) In this example, you can see that the Aha! feature record type is mapped to a Jira epic, and Aha! requirements are mapped to Jira Stories. If you click on the blue "Field Mapping" button, this will reveal the integration options for fields. The screenshot below shows the field integration details for a Feature/Jira epic.

screenshot from Jira


b) Each field can be integrated uni-directionally or bi-directionally, depending on your requirements; use the blue arrow icons in the centre of the field list to manage the direction of the field integrations. You must include the required fields in Jira within your integration; otherwise, data syncs between the two systems might fail. Reach out to your Jira admin if you need help determining which fields in Jira are necessary for this process step.

c) Status mappings have a practical level of granularity that allows you to map multiple statuses to one if required. In this example, our Aha! Roadmaps workflow matches our Jira workflow for Features/Epics, so the mapping is one-to-one and relatively simple.

Screenshot of Jira

d) If you have differing workflows between each system, you can also map multiple statuses to one; you will achieve this by dragging and dropping statuses to create groups. You should see branching indicator lines in the screenshot below if you have successfully grouped statuses.

Screenshot of Jira


6. After completing the integration setup for fields, select "Save and continue."

The system will bring you to a final review page for your integration. Indicate whether or not you want changes to continue for import and export manually or automatically, and select "Save and continue."

Your integration should now be ready for use. To run an integration test, you will need to carry out the following steps: 

  1. To test your integration, you can create a sample Feature and/or Story in Aha! Roadmaps and ensure it syncs properly to Jira. 
  2. Perform test changes to your work entity in both systems to ensure the bidirectional sync works as expected. 
  3. Change status, modify fields, and create additional work entities to ensure the smooth functioning of the integration. 
  4. If your entity does not sync or is syncing incorrectly, return to the integration setup to review your configuration and log messages. 

Need help with your current integration? We can help you solve it. Speak to an expert.