Aha! Roadmaps | Integrate with Azure DevOps Services or Azure DevOps Server (version 1.0)
We have updated this integration to version 2.0! 2.0 integrations have all the same functionality of a 1.0 integration, plus expanded capabilities and support. All new Aha! Roadmaps integrations are now 2.0 integrations. If you are ready to update your integration from 1.0 to 2.0, please follow these steps. You can also learn more about the Azure DevOps Services 2.0 integration.
This two-way integration allows you to push your features and requirements from Aha! Roadmaps into Azure DevOps Services or Azure DevOps Server as issues and get updates back. Azure DevOps Services, formerly known as Visual Studio Team Services (VSTS) is a cloud-based offering from Microsoft. Azure DevOps Server, formerly known as Team Foundations Server (TFS), is the on-premises offering.
When you have completed your roadmap and feature planning on the Aha! Roadmaps side, you can move features into Azure DevOps for the engineering team to work on. You can send them individually or in bulk for a sprint or release. This makes it easy for your team to set brilliant strategy and share visual roadmaps while engineering can continue to work in Azure DevOps.
All development tool integrations are configured under Settings ⚙️ Workspace Integrations. You workspace owner in Aha! Roadmaps to set up this integration.
Click any of the following links to skip ahead:
Azure DevOps Services
Azure DevOps Server
How the Azure DevOps Services integration works
This two way integration allows you to push features and requirements from Aha! into Microsoft Azure DevOps Services and receive updates back in Aha! from Azure DevOps Services.
As with any Aha! and development tool integration, it is important to understand that Aha! Roadmaps comes first in the process. You plan, strategize, and complete work in Aha! Roadmaps and then send features and releases from Aha! Roadmaps to your development tool.
![Features board with highlight on the integrations field and the Azure Devops integration](https://images.ctfassets.net/4zfc07om50my/44tStJGQX3350N128DR8AC/d0f1fe5b62b6b715fa7bee6661b7b9e8/Screen_Shot_2023-03-29_at_12.19.13_AM.png?w=750&h=469&q=90&fm=png&bg=transparent)
Features of the integration
One Aha! Roadmaps workspace is associated with one Azure DevOps Services project.
A feature can be sent to the Azure DevOps Services server using the Integrations Send to Azure DevOps Services menu on the features page.
Requirements are sent to Azure DevOps Services together with the feature.
Only the name, description and attachments of features and requirements are sent to Azure DevOps Services.
If you set up a subscription in Azure DevOps Services, the integration can receive updates about name changes, description changes or status changes from Azure DevOps Services.
The mapping of Azure DevOps Services states to Aha! workflow statuses is configurable.
Configure your integration
You need to be a workspace owner in Aha! Roadmaps to set up this integration.
Configure your Azure DevOps Services account.
You will need to create a personal access token within Azure DevOps Services.
Note: Step 4 of the Microsoft personal access token article includes an example screenshot with Custom defined selected. For Aha! purposes, Full access must be selected when you create a personal access token.
Create the integration in Aha!
Navigate to Settings ⚙️ Workspace and click the + button next to Integrations.
Click on Azure DevOps Services.
Enter the account name of your Azure DevOps Services account. It is equal to the subdomain of your Azure DevOps Services account.
Enter the personal access token you created in Azure DevOps Services.
Click the Test connection button.
On success, you should be able to choose a project from Azure DevOps Services. You also must select an area of this project where features and requirements should be created.
Select the workitemtype to which features should be mapped. Then select for each Azure DevOps Services state to which Aha! workflow status it should be mapped. You may also indicate default values for fields that are required in Azure DevOps Services but not entered in Aha! under Default feature fields.
Repeat step 7 for requirements.
Enable the integration and test it by going to one of your features in Aha! and using the Send to Azure DevOps Services item in the Integrations.
The feature should now appear in your Azure DevOps Services project together with its requirements.
Setup a subscription to receive updates from Azure DevOps Services
Copy the webhook URL from the configuration page.
In your Azure DevOps Services account, go to the project you want to integrate with.
Click the small cog ⚙️ in the top center of the main navigation menu and click on the Service Hooks option.
Add a new service hook by clicking the + button to create a new subscription.
Scroll to and select the option for the Web Hooks service and click Next.
Under the Trigger on this type of event dropdown choose the Work item updated trigger from the dropdown menu. You can leave the filters unchanged and click Next.
In Action Settings, paste the webhook URL from Aha! into the URL field. You can leave the option fields unchanged and click Finish to create the subscription.
How the Azure DevOps Server integration works
This two-way integration allows you to push features and requirements from Aha! Roadmaps into the on-premises Microsoft Azure DevOps Server and receive updates back in Aha! from Azure DevOps Server (formerly Team Foundation Server).
Note:
This integration requires Azure DevOps Server 2015 or later, as prior versions of Azure DevOps Server did not include API support.
You will need to create a firewall exception in order for Aha! to communicate with your on-prem Azure DevOps Server. See the allow listing IP addresses for on-prem development systems article for help.
As with any Aha! and development tool integration, it is important to understand that Aha! Roadmaps comes first in the process. You plan, strategize, and complete work in Aha! and then send features and releases from Aha! to your development tool.
Features of the integration
Authentication with Azure DevOps Server is done using NTLM.
One Aha! workspace is associated with one Azure DevOps Server project.*
A feature can be sent to the Azure DevOps Server using the Integrations Send to Azure DevOps Server menu on the features page.
Requirements are sent to Azure DevOps Server together with the feature.
Only the name, description and attachments of features and requirements are sent.
If you set up a subscription in Azure DevOps Server, the integration can receive updates about name changes, description changes or status changes.
The mapping of Azure DevOps Server states to Aha! workflow statuses is configurable.
Configure your integration
You need to be a workspace owner in Aha! Roadmaps to set up this integration.
To configure this integration, first add the integration in Aha! under Settings ⚙️ Workspace Integrations.
Enter the URL of your Azure DevOps Server server, including the collection name, but without a trailing slash.
Enter your Azure DevOps Server username and password.
If you are using a personal access token, enter that as the password. The username field should be ignored.
Click the Test connection button.
On success, you should be able to choose which project to integrate with. You also must select an area of this project where features and requirements should be created.
Select the workitemtype to which features should be mapped. Then select for each Azure DevOps Server state to which Aha! workflow status it should be mapped.
Repeat step 5 for requirements.
Enable the integration and test it by going to one of your features in Aha! and using the Send to Azure DevOps Server item in the Integrations menu.
The feature should now appear in your Azure DevOps Server project together with its requirements.
If you want to be able to receive updates from Azure DevOps Server you must set up a subscription.
Copy the Webhook URL from the Aha! Roadmaps configuration page.
In your Azure DevOps Server account, go to the project you want to integrate with.
Click the Project settings button in the bottom left and select the Service hooks page.
Add a new service hook by clicking the + Create subscription button.
Choose the Web Hooks service and click Next.
Choose the Work item updated trigger from the dropdown menu. You can leave the filters unchanged and click Next.
In the Action settings, paste the Webhook URL from Aha! into the URL field.
Press Finish to create the subscription.
*Note: You can add the integration multiple times if you want to integrate multiple projects with a single Aha! workspace. Once you have added an integration, you may change the title to specify the project this integration belongs to by clicking on the title at the top of the integration set-up page. You can also create a separate integration for each of your Aha! workspaces, and have each integration point to just one Azure DevOps Server project.
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.