VSTS – Aha Integration: User Docs & Good Practices

Documentation for people using Aha <-> VSTS integration and good practices. This integration is done utilizing Aha’s own integration software.

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: Administrator How To Setup
• 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

How It Works in Summary:

1. Create an Aha Feature.
2. Use Actions > Send To VSTS. A VSTS work item is created.

How Changes Sync from Aha -> VSTS:

1. Make changes in Aha to Summary, Description or Attachments. Changes automatically save.
2. IMPORTANT: Use Actions > Update VSTS to manually push changes to VSTS.

How Changes Sync from VSTS -> Aha:

1. Make changes in VSTS to Title, Description or State.
2. Save changes in VSTS & they are automatically synced to Aha.

IMPORTANT – Known Limitations:

Aha’s Integration with VSTS is very rudimentary, and so is very limited. All users of Aha must be made aware of these limitations, in order to avoid problems.

• Aha’s Integration with VSTS CANNOT automatically update the VSTS work item. You must manually push an update from Aha. See instructions above.
• Aha changes will be OVERWRITTEN by VSTS changes, IF they are not manually pushed from Aha.
  • This problem occurred in testing with changes to Description and Status/State fields.
  • Because Aha’s Integration with VSTS cannot automatically update the VSTS work item, this problem can occur. Here’s the sequence of steps that can cause this:

1. After synchronization from Aha item to VSTS work item is setup using Aha’s Actions > Send To VSTS (see How To Use: section below).
2. Changes are made in Aha. User does NOT use Actions > Update VSTS to manually send Aha changes to VSTS.
3. Changes are made in VSTS.
4. VSTS automatically send changes to Aha, overwriting changes made in Aha

• Aha’s Integration with VSTS CANNOT sync all fields. And some of those fields CANNOT be synced in both directions. See the Fields Synchronized: section below.

Fields Synchronized:

This Aha developed integration software is very limited and cannot sync all fields. Here are the fields it can sync:

(Sync Directions have been tested to be supported by Aha’s Integration with VSTS)

Aha Field Name	VSTS Field Name	Sync Directions
Summary	Title	Both Directions
Description	Description	Both Directions
Attachments (see Notes below)	Attachments	ONLY from Aha
Status (see Notes below)	State	ONLY from VSTS

Notes on Attachments:

• File attachments added or deleted in VSTS DO NOT sync back to Aha at all.
• Attachments in Aha are not effected.
• If you delete an attachment in VSTS,
  • then add an attachment in Aha and push an update,
  • the attachment deleted in VSTS will be re-added back to VSTS.

Notes on Status:

• Sync values are based on mapping (see below)
• Changes to Aha Status DO NOT sync back to VSTS.
• Aha Status is overwritten to match VSTS, when next VSTS change syncs to Aha.

How To Use:

Create VSTS Work Item from an Aha Feature:

1. Enable sync from Aha

1. Open Aha Feature.
2. Click Actions menu
3. Click Send to VSTS…
   (this label may appear different for each Aha Product)
4. This will create the VSTS work item and link it to the Aha Feature.

2. Parent VSTS work item in VSTS

• Once the work item is created in VSTS, you need to manually link it to the appropriate parent. The Aha’s Integration with VSTS cannot do this.

In Aha see if Feature has been synced to VSTS.

• In Feature on the right bottom, look in Integrations section.
• If it has been synced to VSTS, a Linked to Work Item NNNNNN will be displayed.
• You can click the blue hyperlink to open the VSTS work item.

Update VSTS Work Item from Aha Feature:

• Aha’s Integration with VSTS CANNOT automatically update the VSTS work item. You must manually push an update from Aha.
• Manual updates from Aha can be done with the:
  • 1 by 1 approach described below.
  • In bulk using the steps in the next section below.
• VSTS, however, CAN automatically send updates to Aha.

1. Open Aha Feature.

2. Click Actions menu, then Update VSTS…

In Bulk, Create VSTS Work Item from an Aha Feature:

1. Go to Features > List.

2. Select the Features you want to bulk edit.

1. Select the filters to display the Features you are looking for.
2. Use the checkboxes in the Features list to select them.
3. Click Bulk Edit button.

3. In Bulk Edit Features dialog box:

1. Click checkbox next to Send to.
2. Select the VSTS… option from the list.

Aha Status to VSTS State Mapping:

Aha Status	VSTS State
Ready to develop	New
In Development	Active
Ready to ship	Closed
Will not implement	Removed

How To Map Aha Items to VSTS Work Items:

Aha’s Integration with VSTS Limitations Drive Mapping Strategy:

• The Aha developed integration that sync data with VSTS, is limited to handling 1 Aha item to 1 VSTS Project & Team Area Path.

Recommended Mapping:

Aha		VSTS
Aha Feature	<< — >>	VSTS Epic

Why ?

VSTS Epic is recommended because that is the level of work breakdown that we should be expecting from Product Managers, complete with all of the requirements and acceptance criteria detail so that Product Owners and Scrum teams can be perfectly clear on what they are expected to build, and when they are done building it.

Responsibilities:

See VSTS Product Backlog Hierarchy for details on responsibilities of Product Managers and Product Owners.

Product Managers:

Need to own responsibility for grooming the detailed requirements and acceptance criteria in Aha, in collaboration with Product Owners. But PMs are the Primary Responsible Person (PRP).
–> Aha features, once ready, are then flagged by the PM to be synced to VSTS as Epics.

Product Owners:

Are then the Primary Responsible Person (PRP) for breaking down Aha features/VSTS Epics in to VSTS Features inside VSTS, in collaboration with their Scrum team.

Aha Permissions Requirements, Licensing & Pricing:

Permissions Requirements:

• Product Managers obviously need Aha edit permissions – Aha Product Owners and Contributors, which have a monthly user fee.
• Product Owners, do NOT need Aha edit permissions – Aha Reviewers and Viewers, which is free.
  • NOTE: Edits in VSTS will sync back to Aha. And that Aha Reviewers have some very restricted contribution permissions. See Licensing section below.
• However, some PMs & POs may wish to collaborate together via Aha, and we should offer them that option and pay the extra fees if they want to do that.

Here is Aha’s guidance on this topic from the Aha Pricing FAQs described above:

“What’s a Reviewer?
A Reviewer is a user who can see data about products they have been given permission to view. They can also comment on, create and complete to-dos. It is a perfect way to increase visibility across your organization by engaging management, engineering, marketing and other key stakeholders. You can have unlimited Reviewers at no additional cost in the Enterprise and Enterprise+ plans.”

Licensing & Pricing:

User Role	Description from Aha Pricing FAQs	Cost
Product Owner	A Product Owner is typically a product, project, marketing, or engineering manager who actively manages strategy, releases, ideas, features, and product launches. This role requires a paid seat.	$99
Contributor	A Contributor has the same capabilities as a Product Owner but cannot manage users or change most product configuration settings. This role requires a paid seat.	$99
Reviewer	A Reviewer is a user who can see data about products they have been given permission to view. They can also comment on, create and complete to-dos. It is a perfect way to increase visibility across your organization by engaging management, engineering, marketing and other key stakeholders. You can have unlimited Reviewers at no additional cost in the Enterprise and Enterprise+ plans.	Free
Viewer	A Viewer is a user who can see data about products they have been given permission to view. They can also answer to-dos. You can have unlimited Viewers at no additional cost in the Enterprise and Enterprise+ plans.	Free

Cost = per user, per month (if purchased annually under Enterprise plan)

Copied from Aha Pricing for details on the types see the section at the bottom titled Frequently Asked Questions > USE AHA! Look at the FAQs on:

• What’s a Product Owner?
• What’s a Contributor?
• What’s a Reviewer?
• What’s a Viewer?

Aha Data Model:

Example Aha Product Hierarchy:

Learn More About Aha’s Data Model:

• The Aha! data model – Aha! Support