This support article refers to the historical 1.0 version of the Aha! integration with Jira. If you are using the new 2.0 version of our Jira integration or would like to learn more about the new framework, you can review 2.0 documentation here.
If you are looking for details about advanced field mapping for 2.0, reference this article.
The Jira integration is our most robust integration and offers advanced functionality. This document explains what that functionality is and how it works. For information on the basic functionality of the Jira integration, please refer to the Integrating with Jira document.
Issues created in Jira automatically populate into Aha!
Aha!'s integration with Jira is two-way. This means that once a link is established between Aha! feature/requirement and Jira issues, updates are bi-directional and automatic. Links are established one of two ways:
- You send features to Jira from Aha!
- You import backlog items from Jira to Aha!
Aha! is where you plan and vet your releases and features. However, once you send features to Jira, they may be split into additional user stories or sub-tasks. It's also possible that they -- and existing issues in Jira -- may be moved into a version or user story already linked to Aha! This is especially common when using sub-tasks in Jira or mapping Aha! features to Jira epics. When this occurs and the issue in Jira gets created in Aha!, the Jira issue will update to include the Aha! Reference ID.
The two-way integration with Jira supports two workflows where items in Jira automatically populate back into Aha!
- If a new issue is created in Jira and linked to an existing Aha!-linked parent item (mapped to Release or Feature), it will automatically be created in Aha!
- If an existing Jira issue is moved under an existing Aha!-linked parent item (mapped to Release or Feature), it will also be automatically created in Aha!
Note: Common parent items are: Fix Version, Epic (if mapped to Features), User Story (if mapped to Features). Any issue in Jira that is mapped to Features in Aha! is potentially a parent item.
- An existing Jira issue is moved to a Fix Version associated with an Aha! Release, a feature will automatically be created in Aha! under that release.
- Aha! Features = Jira User Stories and Aha! Requirements = Jira Sub-tasks; a feature is sent to Jira, then a sub-task is added to the user story in Jira and a requirement is added to the feature in Aha! automatically.
- Aha! Features = Jira Epics and Requirements = Jira User Stories; Stories created in Jira and associated with the Epic will populate as a requirement under the feature in Aha!
Customize what issues get created from Jira to Aha!
In some cases, you may not want all issues to be created in Aha! automatically. You can manage what automatically gets created in Aha! through a couple of different settings in the Jira integration configuration page or by directly editing the webhook in Jira. There are two common scenarios:
A) You don't want Aha! to create any features automatically from issues added in Jira.
- Check the "Don't auto import" checkbox in the integration configuration page to prevent Aha! from automatically importing issues that are related to an issue already linked to Aha!
- Alternative solution: Modify your existing webhook and disable the "Issue Created" event. This will prevent Jira from notifying Aha! about new issues.
B) You want to limit which issues are converted to features.
- Check the "Only auto import mapped issue types" checkbox in the integration configuration page to prevent Aha! from automatically importing issue types that are not mapped to features or requirements. Note: if this is not checked, unmapped issue types are automatically imported as features.
- If you wish to be able to import issue types beyond the integration mapping for features, uncheck the "Only auto import mapped issue types checkbox" and edit the webhook instead. Add a JQL query to the webhook that will only allow the issue types that you want to be automatically created in Aha!. Example: issuetype in (Epic, "User Story", Sub-task)
This will cause Jira to only notify Aha! of new issues that match your criteria.
For help with JQL see the bottom section in Import features from Jira.
Aha! Releases and Jira Fix Versions
An entire release in Aha! can be sent to Jira via the Release action item Send features to Jira. Aha! maps a release to a Jira Fix Version. There is an option in the Aha! integration configuration to disable this if you do not want to have Aha! create Jira Fix Versions or update the FixVersion field. This can be desirable if the development team is referencing multiple FixVersions per feature in Jira, as otherwise Aha! will overwrite the multiple FixVersion references on a feature in Jira and update FixVersion with the feature's Aha! release.
- When a release is first sent to Jira, a corresponding Fix Version record will be created in Jira. The name and date on the Fix Version will be based on the Aha! release.
- Each time the release is sent to Jira again, the name and release date will be updated to match the release in Aha! Changes to the Fix Version in Jira will not be reflected back in Aha!
- Each feature in the release which has a corresponding issue in Jira will have its version field set to the Fix Version that was created. When features are moved between releases in Aha! the version field in Jira will be updated to match.
- If a Fix Version already exists in Jira with the same name as the Aha! release, then a new Fix Version will not be created. A link between the Aha! release and the Jira Fix Version will be created.
Aha! never deletes issues from Jira. Any feature or requirement that is deleted from Aha! will not cause deletions in Jira. Likewise, deleted issues in Jira will not cause features or requirements in Aha! to be deleted.
This is to protect against inadvertently deleting another team's work.
Collaboration between the product and development team is essential. The Jira integration supports two-way updates of comments where comments added in either application will be reflected back and forth. However, due to API limitations, they will show up as written by the user with which the integration was configured.
Comments on a feature in Aha! are not sent over initially. Once the feature has been sent to Jira, any future comments will be updated on either end.
You can assign owners to both features and requirements in Aha! Assignees can be Product Owners, Contributors, Reviewers, or Viewers. If every user in Jira is also in Aha! you can map assignees between the two.
Assignees are mapped based on their email address. They must be using the same email address in both systems for the mapping to happen. If a user with the same email address is not found in the other system, then no change to the assignee is made (for data flowing in either direction).
Note: When features or requirements are sent to Jira, the reporter field will be set to the Jira user who has the same email address as the Aha! user who originally created the feature or requirement.
Estimates and Time Tracking
The integration supports feature/requirement estimates as well as time tracking. For full details, please view this document.
Sometimes, changes are made to fields in Jira that are not mapped to Aha! In this case, a comment will be added in Aha!
Once Aha! records are linked to Jira records, changes in the structure of the records will not be synced (e.g. changing a feature to be a requirement or changing a requirement to be a feature).