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 do run into trouble, we have gathered some of the most common issues with updating Jira or Aha! Roadmaps records, 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:
Jira updates not reflected in Aha! Roadmaps
Symptom
You update Jira issues but do not see those updates reflected in Aha! Roadmaps records.
Explanation
The problem is often that the webhook URL is incorrect or is not implemented at all. The webhook is required for the integration to be two-way. You add it to Jira and it communicates Jira updates back to your Aha! Roadmaps records.
Resolution
Review your Jira webhook configuration.
Note: On the Enable step of your Aha! Roadmaps integration configuration, a user is identified as the Webhook will run as user. Their user permissions will define the webhook's permissions. Only one webhook is required per Jira instance, but if the user the webhook is running as has limited access in Aha! Roadmaps, the webhook will only update Aha! Roadmaps accordingly.
To configure your Jira webhook:
In Jira, navigate to Settings → System and select Webhooks. You will need to be an administrator in Jira to access this configuration.
Create a new webhook and paste the webhook URL from your Aha! Roadmaps integration configuration into the URL field. Name the webhook something that will identify it as being used for Aha! Roadmaps.
You will want to enable all Issue and Worklog events.
Ensure the Exclude body option is not checked.
You can also optionally add custom JQL. Custom JQL allows you to filter what issue types send updates to Aha! Roadmaps.
Inappropriate screen error
Symptom
You attempt to update records through the integration but see an error that looks like one of these:
Data not accepted: customfield_xxxxx: Field 'customfield_xxxxx" cannot be set. It is not on the appropriate screen or unknown.
Remote error for 'create_feature': Data not accepted: customfield_10600: Field 'customfield_10600' cannot be set. It is not on the appropriate screen, or unknown.
fixVersions: Field 'fixVersions' cannot be set. It is not on the appropriate screen, or unknown.
Explanation
If you see errors like these, it means that the field is missing from the Create or Edit screen in Jira.
Resolution
Aha! Roadmaps records which fields are present when the integration is first configured, so it is possible that the field has since been removed or is not available on the appropriate screens.
Note that field configuration may be different for different users, so you should test in Jira using the same user account that the integration is set up with. Then ensure that the field exists and is on the Create and Edit screens.
If the error is related to the Aha! Reference field and it's no longer in Jira, you should go to the Aha! Roadmaps integrations screen and reload your project data for Jira again. This will recreate the field.
Update feature 404 error
Symptom
You attempt to update records through the integration but see an error that looks like one of these:
Remote error for 'update_feature': Unhandled error: STATUS=404 BODY={"errorMessages":["Issue Does Not Exist"],"errors":{}}
Explanation
This error means that the issue that the Aha! Roadmaps record was originally linked to is no longer accessible to Aha! Roadmaps.
Resolution
There are several potential reasons:
The issue was deleted from Jira.
The issue was moved to another project in Jira.
User permissions in Jira were changed so that the user that is being used for the Jira integration no longer has access to the issues (e.g. project access was removed).
Importing record: Record in Aha! does not exist or you do not have permission to see it.
Symptom
You attempt to update records through the integration but see an error that looks like this:
Importing record: Record in Aha! does not exist or you do not have permission to see it.
Explanation
This means that a record's parent (e.g. the parent feature of a requirement) either exists in a workspace you do not have permission to see, or that it has not been imported into your Aha! account.
Resolution
In order to import records you'll need to ensure that their parent record exists in your Aha! account and is visible to you.
No valid transition to status
Symptom
You attempt to update records through the integration but see an error that looks like this:
No valid transition to status ##### for issue FRED-1234
Explanation
There is an issue with the Jira status transition for a record. The Jira status workflow has been updated, and the integration cannot move through the proper Jira workflow, and so it cannot update record to the correct Jira status. Jira in return tells your Aha! account not to update the status.
Resolution
Check that your workflows in both Jira and Aha! Roadmaps, and ensure that both of them have valid transitions both to and from the status the record is trying to change to.
Then, confirm that these Jira transitions have validators on them, which can cause the sync to fail to send if there is a blank field that is required in Jira, as Aha! fields cannot be set as required on the record itself.
The record is being managed by another Aha! integration
Symptom
You attempt to update records through the integration but see an error that looks like this:
Skipping webhook create for [record]. The record is being managed by another Aha! integration
Explanation
The record has already been imported by — and is being synced by — another active integration. A record can only be managed by one integration at a time.
Resolution
Search for the record in question (use the record ID, e.g. FRED-1234, for a more precise search) to find the integration that originally imported the record. Then, either unlink the record from its current integration, or use the current integration to import changes to the record.