VSTS – Aha Integration: Administrator How To Setup

Documents the configuration of the Aha <-> VSTS Integration done by system administrators.

Written in 2016-2017:
This is part of a series of articles that I originally wrote in 2016-2017 and were only published on private internal company wikis. I am publishing them publicly for the first time in 2019, here on my blog.

Written for Microsoft’s VSTS:
Some content is written for Microsoft’s Visual Studio Team Services (VSTS), as it existed in 2016-2017. VSTS was renamed to Azure DevOps in 2018 (WikiPedia).

Learn More:

• VSTS – Aha Integration: User Docs & Good Practices
• VSTS Product Backlog Hierarchy
• Knowledge Base – Aha! Support
• Getting started – Aha! Support and lots more Aha How To Videos
• The Aha! data model – Aha! Support
• Aha Pricing FAQs

Known Issues:

• DO NOT DELETE the Aha Integration after it has been used, because it will also delete all links from Aha to VSTS. Breaking any existing synchronization that has been previously established.
• The VSTS Account used by the Aha <-> VSTS Integration can only see VSTS projects that it has been granted access to.
  • Use the Test Connection button in the Aha <-> VSTS Integration config page to refresh it’s list of VSTS projects.
  • If it cannot see your VSTS project, you can add the account the Aha <-> VSTS Integration uses to the VSTS team members list.

Configure Aha <-> VSTS Integration:

1. From Aha Product: Settings (gear icon) > Product

2. Integrations > Add new integration

3. Scroll down to find VSTS – Click add button

4. Set the title
This is what appears on Actions > Send to and Update <title> menu options.
Click Actions > Use template Visual Studio Team Services
This preloads configuration options you will need.

5. Select the VSTS Project from the list.
The checkbox next to this must be uncheck for your changes to be saved.

6. Uncheck box next to this.
The checkbox next to this must be uncheck for your changes to be saved.
Select the Area Path that the VSTS work item will be created in.

7. Uncheck box next to this.
The checkbox next to this must be uncheck for your changes to be saved.
Select Epic.
This is the work item type that will be created.

8. Uncheck box next to this.
The checkbox next to this must be uncheck for your changes to be saved.
Map the VSTS States on the left with the Aha Status on the right, as illustrated in this screen shot on the right.

9. Check box next to Enable.
The checkbox MUST be checked for the integration to work.

Configure VSTS Service Hook:

To receive updates from VSTS you must setup a Service Hook subscription.

1. In VSTS Project:
Click admin (gear icon) > Service Hooks

2. Click Create a new subscription (plus icon).

3. Select Web Hooks.

4. Select Trigger as Work item updated.

5. Go to Aha Integration configuration that you setup above.

6. Scroll down
Copy Webhook URL

7. Paste Webhook URL in to Settings > URL

8. Click Finish button.

Aha <-> VSTS Integration Documentation:

This was copied from the Aha admin UI. This is the only documentation from Aha we can find on the Aha <-> VSTS Integration

Instructions

This integration allows you to push features and requirements from Aha! to Microsoft Visual Studio Team Services (VSTS) – previously called Visual Studio Online (VSO).

This integration works with the online version of Visual Studio. If you run Team Foundation Server on-premise then use the separate Team Foundation Server integration instead.

Features

• One Aha! product is associated with one VSTS project.
• A feature can be sent to VSTS using the Send to Visual Studio Team Services item in the Action menu on the features page.
• Requirements are sent to VSTS together with the feature.
• Only the name, description and attachments of features and requirements are sent.
• If you set up a subscription in VSTS the integration can receive updates about name changes, description changes or status changes.
• The mapping of VSTS states to Aha! workflow statuses is configurable.

Configuration

You need to be Product Owner in Aha! to set up this integration.

To configure this integration, first configure your Visual Studio Team Services account.

1. Open your account dropdown (usually identified by your first initial or profile image) in the top right of the page and choose the
   Security.
2. Select Personal access tokens.
3. Add a new access token with scopes: Project and team (read), Work items (read and write).
4. Save the token value which is generated.

Next create the integration in Aha!

1. Enter the account name of your Visual Studio Team Services account. It is equal to the subdomain of your Visual Studio Team Services account.
2. Enter the personal access token you created in Visual Studio Team Services.
3. Click the Test connection button.
4. On success, you should be able to choose a project from Visual Studio Team Services. You also must select an area of this project where features and requirements should be created.
5. Select the workitemtype to which features should be mapped. Then select for each VSTS state to which Aha! workflow status it should be mapped.
6. Repeat step 5 for requirements.
7. Enable the integration and test it by going to one of your features in Aha! and using the Send to Visual Studio Team Services
   item in the Action menu.
8. The feature should now appear in your Visual Studio Team Services project together with its requirements.

If you want to be able to receive updates from VSTS you must setup a subscription.

1. Copy the Webhook URL from the configuration page.
2. In your Visual Studio Online account, go to the project you want to integrate with.
3. Click the small cog in the top center of the main navigation menu and click on the Service Hooks option.
4. Add a new service hook by clicking the + Create subscription button.
5. Scroll to the option for the Web Hooks service and click Next.
6. Under Trigger on this type of event choose the Work item updated trigger from the dropdown menu. You can leave the filters unchanged and click Next.
7. In the 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.

Troubleshooting

To help you troubleshoot an error, we provide the detailed integration logs below. Contact us at support@aha.io if you need further help.