Aha! Roadmaps | Convert an integration from 1.0 to 2.0

Aha! Roadmaps offers more than 30 integrations for you to choose from. At both the account-level and workspace level, you can connect your roadmap with your tool of choice. Most integrations are two-way integrations, meaning that as you share context with another team in the integrated tool, you receive progress updates back.

Our 2.0 integrations offer the most flexible and comprehensive integration capability, including the ability to:

• Map Aha! Roadmaps record types to nearly any record type in the integrated tool.

• Map any standard or custom fields in Aha! Roadmaps to any similar field in the integrated tool, and specify how updates should flow between the two systems.

• Import your backlog directly from your development system for a seamless transition to your Aha! Roadmaps workspace.

• Automatically import new records created in your development system.

If you are using a 1.0 integration where a 2.0 integration is available, upgrading your integration is simple. 2.0 integrations have all the functionality of the original 1.0 integrations, plus extended capabilities and a more intuitive experience. You can convert any 1.0 integration to a 2.0 integration with no loss of data or connection.

Click any of the following links to skip ahead:

• Available 2.0 integrations

• How to convert to a 2.0 integration

• Convert a Jira integration

• Convert a Rally integration

• Converting an Azure DevOps integration

• Convert a GitHub integration

• Map the Aha! Roadmaps URL field

• Use integration templates

• Use webhooks for Jira integrations

Available 2.0 integrations

The following integrations are available for integrations 2.0:

• Azure DevOps Services

• Azure DevOps Server

• GitHub

• GitHub Enterprise

• Jira

• Rally

• Trello

Top

How to convert to a 2.0 integration

Every 1.0 integration that has the ability to convert to a 2.0 version has that option in the More options menu of the integration settings.

To convert an integration, navigate to Settings ⚙️ Account Integrations for account-level integrations, and Settings ⚙️ Workspace Integrations for workspace-level integrations.

Click on the integration you want to convert, click the More options dropdown in the upper right, then select Convert to integrations 2.0.

After you click Convert to Integrations 2.0, you will be prompted to confirm your choice. You cannot convert back to a 1.0 integration, so it is important to be sure you want to convert prior to confirming the selection.

When you convert the integration, Aha! Roadmaps will transfer over the 1.0 integration's mappings to the 2.0 framework.

Once the integration is converted, you will be directed to the 2.0 setup workflow and need to re-authenticate your integration.

After authenticating, you can proceed through the setup workflow to verify everything is configured as you would like, including the new field mapping options available in 2.0.

Top

Convert a Jira integration

Converting this integration will automatically migrate all linked records to the 2.0 integration, and apply the following:

• Project

• Record mappings

• Preferences for syncing tags

• Preferences for sending releases

Before you convert, consider these points:

• The new integration will need to be authenticated. Be sure to have your Jira credentials available.

• Some custom fields may need to be re-mapped. Please make note of any custom fields that are mapped in the existing integration.

Top

Convert a Rally integration

Converting this integration will automatically migrate all linked records to the 2.0 integration, and apply the following:

• Workspace

• Project

• Record mappings

• Preferences for syncing tags

• Preferences for sending releases

Before you convert, consider these points:

• The new integration will need to be authenticated. Be sure to have your Rally credentials available.

• Status mappings must be re-mapped. Please make note of status mappings in the existing integration.

Top

Converting an Azure DevOps integration

Converting this integration (either Azure DevOps Server or Azure DevOps Services) will automatically migrate all linked records to the 2.0 integration, and apply the following:

• Project

• Area

• Record mappings

• Status mappings

• Default fields

Before you convert, consider these points:

• The new integration will need to be authenticated. Be sure to have your Azure DevOps Services or Azure DevOps Server credentials available.

Top

Convert a GitHub integration

Converting this integration will automatically migrate all linked records to the 2.0 integration, and apply the following:

• Repository

• Issue mappings

• Preferences for syncing labels

Before you convert, consider these points:

• The new integration will need to be re-authenticated. Be sure to have your GitHub credentials available.

• Status mappings must be remapped. Please make note of status mappings in the existing integration.

Top

Map the Aha! Roadmaps URL field

In integrations 1.0, the URL for the Aha! Roadmaps record automatically populates in the development system. In integrations 2.0, this field needs to be manually mapped. The field to map from Aha! Roadmaps is called URL. The corresponding field that URL should map to depends on the development system. For example, in Jira, the field to map URL to is called Aha! Reference.

Top

Use integration templates

When you convert an integration template from 1.0 to 2.0, all integrations using that template will automatically convert over as well.

The template integration will take you into the above-described workflow, where you need to first re-authenticate and then proceed through the setup workflow to validate your configurations and enable the integration.

All other integrations using the template will also need to go through the setup workflow to validate configurations and enable the integration. However, the credentials will not need to be entered again.

Top

Use webhooks for Jira integrations

Webhooks are used to communicate changes in Jira back to Aha! Roadmaps. In most cases, a single webhook is needed to support every integration; adding multiple webhooks will cause problems and is not recommended outside of a few specific situations.

One of those situations is when you convert integrations from 1.0 to 2.0. A webhook belonging to a 1.0 integration will only support Jira to Aha! Roadmaps communication for other 1.0 integrations. Similarly, a webhook for a 2.0 integration will only support communication for other 2.0 integrations.

If you convert all of your 1.0 integrations to 2.0, you have nothing to worry about. The webhook you had active previously will be transitioned over and will support your 2.0 integrations just like it did previously.

If you only convert some of your integrations over, you will need to ensure one of the converted integrations has its webhook added to Jira. Otherwise, your 2.0 integrations will not receive Jira updates. Similarly, if you convert the integration to 2.0 that had its webhook in use within Jira, you will need to add another webhook for your remaining 1.0 integrations.

Top