In most cases, once you save your Jira integration configuration in Aha! Roadmaps, you are ready to go — no further configuration is needed.
In case you run into trouble, we have gathered some of the most common issues with linking record types between Aha! Roadmaps and Jira, along with recommended solutions.
Often the best place to start in most of these situations is the integration log messages for your configuration. Those messages will help diagnose and solve the problem.
Click any of the following links to skip ahead:
Cannot establish "Links to” relationships with Jira
Symptom
You want to configure "links to" relationships, but do not see the linking relationship you need in your Jira integration configuration.
Explanation
You may be unable to establish a link to fields such as Parent link, Fix Version, or Epic link. Often, the reason is that those fields are not configured on the Create, View, and Edit screens in Jira.
Resolution
To resolve the first issue, you should add those fields to the Create, View, and Edit screens for your Jira project.
We recommend you use the Find your field option within Jira. This will quickly identify why the field is missing and direct you to what you will need to update the field availability in Jira.
FixVersions is not on the appropriate screen
Symptom
You try to send features to Jira but they are not linked to the appropriate fix version. You may see an error message in your integration logs that looks like this:
Field 'FixVersions' cannot be set. It is not on the appropriate screen or unknown.
Explanation
Aha! Roadmaps can only set fields via the API that are visible on the Create and Edit screens in the Jira user interface. The FixVersion field is visible by default, so it is likely that your Jira instance was customized to remove the field.
Screens in Jira define what fields are available when creating, editing, or viewing a Jira issue. Each of those actions can have a different Screen assigned. So, for example, a field could be visible when viewing an issue but not actually visible when creating or editing the issue.
This causes a problem (and a lot of confusion) because Aha! Roadmaps needs the field visible on Create and Editscreens to communicate through the API. However, you might assume that the field is visible because you can see it when you View the issue.
Resolution
You need to add the FixVersions field to the Create and Edit screens in Jira.
Then, navigate back to Settings ⚙️ → Workspace and open your Jira integration configuration. On the Mappings step, click Reload configuration in the bottom-left corner to fetch the updated Jira configuration.
Version ID is not valid
Symptom
You attempt to update your integration between Aha! Roadmaps and Jira but receive back an error that looks like this:
FixVersions: Version id '####' is not valid
Explanation
This error indicates that a version in Jira that was created by Aha! Roadmaps has been deleted from Jira. This means that the link from the Aha! Roadmaps release to the Jira version is now broken.
Resolution
The solution is to break the existing link so that Aha! Roadmaps creates a new version in Jira the next time you sync the two products. In Aha! Roadmaps, navigate to Releases → Details for the release that this error relates to. Note the link to an existing release in the Integrations field on the Overview tab, then the More options button and Delete link.
When you send the release (or features in the release) to Jira again, a new version will be created. Or if an existing version with the same name already exists, it will be linked for this release in Aha! Roadmaps.
Requirements do not change features when linked Jira issues are moved
Symptom
You move a Jira issue that is linked to an Aha! Roadmaps requirement to another parent Jira issue, but that change is not reflected in Aha! Roadmaps.
Explanation
This issue is the result of a bug that Atlassian has resolved.
If you use Jira Cloud, this issue was resolved in December 2017.
If you use Jira Server, this issue was resolved in October 2019 in versions 8.4.2 and 8.5.0.
However, if you are not able to upgrade your Jira version, please follow the steps below.
Resolution
If a requirement needs to be moved, you need to do the following:
Within the requirement, click the More options button and select the Move to another feature option.
Select the new parent feature you want to move the requirement to.
If the feature that the requirement is moved to is already linked to a Jira epic, it will associate the story with the epic automatically.
If the feature doesn't already exist in Jira as an epic, click More options on the Integrations field in the Overview tab,then Resend all fields to trigger the requirement to sync to Jira, which will also send the parent epic.
Cannot establish "relates to" relationships
Symptom
You try to pass Aha! Roadmaps records linked with the "relates to" relationship to Jira but instead get an error message that looks like this:
Remote error for 'update_feature': Unhandled error: STATUS=404 BODY={"errorMessages":["No issue link type with name 'Relates' found."],"errors":{}}
Explanation
If you see this error, the Relates issue link type does not exist in Jira. The Relates issue link type is a default link type in Jira but can be renamed or removed by a Jira administrator.
Resolution
To fix this issue:
In Jira go to Settings → System → Issue Linking.
Check for the issue link named Relates, which typically has the outward description value of relates to.
The integration works off of the Name value, which must match Relates.
If the link type does not exist, create a new link type and ensure the Name value is Relates.
If the link type exists but has some sort of typo where the name is not spelled exactly Relates, edit the issue link accordingly.