This support article refers to the 2.0 version of the Aha! TFS integration. For the 1.0 version, please reference our TFS integration 1.0 article or reference our Integrate with Visual Studio Online (Visual Studio Team Services) article.
Aha! provides a two-way integration with Visual Studio Team Services (VSTS) and Team Foundation Server (TFS). This allows product teams to send their planned work from Aha! to their development team working in VSTS or TFS. Before configuring any integration for the first time, it is important to fully understand how to think about integrating Aha! with your development tool.
The main difference between VSTS and TFS is that VSTS is a cloud-based solution that is available through a web browser or IDE client, while TFS is an on-premise offering. For the scope of this article, we will refer only to VSTS but the same steps exist for TFS as well.
This integration supports sending the following Aha! record types to VSTS:
- Master features
The above Aha! record types can be mapped to any work item type in VSTS, including both standard and sub-task types.
To set up an integration with VSTS, you need to be a Product Owner in Aha! for the product you wish to integrate. You will also need to have a VSTS account that has proper access to create/edit records in the project you plan to integrate.
1. Navigate to Settings > Product and press the + next to Integrations on the left side navigation bar. Depending on if you are integrating to the cloud or on-premise, select either Visual Studio Team Services or Team Foundation Server from the integrations 2.0 grouping.
2. This will launch the integration configuration wizard. The first step is to name your integration and optionally select a template if you have already created one. Click Save and continue.
3. Next, you will be prompted to authenticate with valid VSTS or TFS credentials.
For VSTS, you will need to enable Alternate authentication credentials or create a Personal access token within VSTS. Back over in Aha!, you need to enter the subdomain of your VSTS account. If your VSTS domain is https://mycompany.visualstudio.com, then enter "mycompany" as the subdomain. Now, enter the username that you use to login to VSTS. If you enabled Alternative authentication credentials earlier, you will enter your VSTS account password. Otherwise, enter the Personal access token that was created as the password.
For TFS, you will need to enter the Server URL for your TFS account. Be sure to enter the entire Server URL, including the collection part of the path with no trailing slash. As an example of a valid entry, review the following URL: https://tfs.mycompany.com/tfs/DefaultCollection. Next, enter the username and password that you use to login to your TFS account.
4. After authenticating, you will be prompted to choose a project, and an area. Each of these lists is based on what your user has available to them in VSTS.
5. Next comes record mappings. This step allows you to configure how Aha! records are mapped to your VSTS records. The default mappings are based on what is most widely used across our customers. However, you are free to remove the default mappings and add your own to map records together based on what makes sense for your team and how you work.
6. Within record mappings, you have the option to also specify your field mappings. This is an advanced option within the configuration that allows you to customize how each field within the record is mapped between Aha! and VSTS — as well as what relationship links exist for those records.
The relationship links are important to understand because they allow records created in your development system to be automatically imported into Aha! in certain use cases. You can learn more about them here.
7. While not every user will need to customize their field mapping, you do need to define the way statuses are mapped. Within the field mapping section for each Aha! record, there is a line for Status with a gear icon at the far right. Click the gear icon to open up the status mapping window.
8. When mapping statuses, you will be presented with your Aha! status workflow for the record type on the left and your integrated system status workflow on the right. You can drag and drop the statuses to create groupings and mappings. In the above screenshot, you can see that multiple statuses have been grouped together where the Aha! statuses of Ready to develop and In progress are mapped to the single VSTS status of Active.
9. With your records, optional field mappings, and statuses defined, you can click Save and continue to move onto the last step in the workflow. The Enable step allows you to specify how updates from Aha! are sent to your development system. The default is for the user to approve outgoing changes. We recommend this option until the team is familiar with how the integration works, at which point you can switch to the automatic sending of changes. The approval step allows teams that are new to the integration to validate what is being sent to their development system, which can help prevent unintentional changes from going through.
10. All sections of your integration configuration have been set. However, if you set any mappings to sync from VSTS to Aha!, you will need to set up webhooks in VSTS so that Aha! can receive updates.
- Copy the webhook URL from the configuration page.
- In your VSTS account, go to the project you want to integrate.
- Click the gear icon in the top center of the main navigation menu and click on the Service Hooks option.
- Add a new service hook by clicking the + Create subscription button.
- Scroll to the option for the Web Hooks service and click Next.
- Under Trigger on this type of event choose the Work item updated trigger from the dropdown menu. To reduce unnecessary webhooks, add filters for the specific area, item type, or tags that you plan to integrate with Aha! Click Next.
- On the Action screen, under 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.
- Repeat this process two additional times, selecting the following events in step 6: Work item created and Work item deleted.
11. Finally, test the integration by opening one of your features in Aha! and use the Send dropdown to select Send to Visual Studio Team Services. You should see a link to the created VSTS record appear on the Aha! feature after a few seconds. This will let you easily click into VSTS to verify that everything was sent through correctly.