In most cases, once you save your Jira integration configuration in Aha! Roadmaps, you are ready to go — no further configuration needed.
In case you do run into trouble, we have gathered some of the most common issues with record creation here, 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:
Field cannot be set
Symptom
You cannot create Aha! Roadmaps records from Jira, and you see an error message that looks like this:
Remote error for ‘create_feature’. Data not accepted: summary: Field ‘xxxxxx’ cannot be set.
Explanation
Any error that follows this format indicates something has changed in your Jira configuration (on the Jira server) so that the user account used by the integration with Aha! Roadmaps no longer has the ability to edit some Jira issues.
Resolution
If you log in to Jira using the same user account, you should see that you can't use the Edit screen to modify the same fields.
Aha! Roadmaps can only set fields via the API that are visible in the Edit screen in the Jira user interface. The Edit screen is the popup that you see when you click the Edit button on an issue.
Make sure that the field is mentioned by the error message is visible on the default screen in Jira.
Invalid version ID
Symptom
You cannot create Aha! Roadmaps records from Jira and you see an error message that looks like this:
Remote error for ‘create_feature’. Data not accepted: fixVersions: Version id ‘xxxxx’ is not valid.
Explanation
When you send a release to Jira from Aha! Roadmaps a new Version is created in Jira. This error indicates that the version in Jira that was created by Aha! Roadmaps has been deleted in Jira. This means that the link from the Aha! Roadmaps release to the Jira version is now broken.
Resolution
You need to break the link between the records, so that Aha! Roadmaps creates a new version in Jira. To do this, navigate to Releases → Details in Aha! Roadmaps and select the release that this error relates to. In the Integrations field, click More options, then Delete link next to the link to the Jira version.
The next time you send the release (or records within the release) to Jira, one of two things will happen:
A new version will be created, resolving the error message.
If an existing version with the same name already exists in Jira, it will be linked to the Aha! Roadmaps release, resolving the error message.
Invalid name
Symptom
You cannot create Aha! Roadmaps records from Jira and you see an error message that looks like this:
Remote error for "create_feature': Data not accepted: : name xxxxxx is not valid
Explanation
This error message means that the value of a predefined choice list custom field sent from Aha! Roadmaps does not match one of the choices in Jira. This situation could occur if the names of the two fields do not match, or if you have merged two Aha! Roadmaps custom fields but still need to update your integration field mapping.
Resolution
To resolve this issue, double-check that your predefined choice list in both Aha! Roadmaps and Jira match. In particular, look to ensure neither sets of choices contain any extraneous whitespace.
Cannot find issue type
Symptom
You cannot create Aha! Roadmaps records from Jira and you see an error message that looks like this:
Remote error for ‘create_feature’. Integration needs to be reconfigured: issue types have changed, can’t find issue type
Explanation
This error message indicates that you have not mapped all Aha! Roadmaps record and Jira issue types to each other. You need to finish configuring your Jira integration.
Resolution
To do this, navigate to the integration configuration in Settings ⚙️→ Workspace → Integrations and map Aha! Roadmaps records to the appropriate Jira issue types. You may wish to follow our recommended Jira mappings.
Unhandled 404 error
Symptom
You cannot create Aha! Roadmaps records from Jira and you see an error message that looks like this:
Remote error for 'create_feature': Unhandled error: STATUS=404 BODY
Explanation
This error indicates that you haven't completed the configuration. Specifically, you have not selected a Jira project and have not mapped record types and fields between the two tools.
Sometimes this error appears when someone has tested the connection successfully and therefore thought the integration was complete.
Resolution
To do this, navigate to the integration configuration in Settings ⚙️→ Workspace → Integrations and complete the following steps:
Select a Jira project in the integration configuration.
Map Aha! Roadmaps records to the appropriate Jira issue types. You may wish to follow our recommended Jira mappings.
Map Aha! Roadmaps fields to each other.
Operation value must be a string
Symptom
You cannot create Aha! Roadmaps records from Jira and you see an error message that looks like this:
Remote error for 'create_feature': Data not accepted: customfield_xxxxx: Operation value must be a string
Explanation
You will get this error if you map a custom Aha! Roadmaps field to the field in Jira that is not supported. This is because it cannot be set through the Jira REST API (which is what Aha! Roadmaps uses). Any fields in Jira that cannot be set by the Jira REST API will not be mapped through Aha! Roadmaps even though they may show up on the list of custom fields available for mapping.
For example, you may be trying to map a custom field in Aha! Roadmaps to the Jira sprint field. The sprint field is key to the operation of Jira. Changing the sprint affects a number of things. The Jira UI is able to display the sprint in a friendly way, but the Jira API does not support translating the internal representation into a form that is useful to external systems.
Resolution
Unfortunately, this means that Aha! Roadmaps (and other external systems) cannot include the custom field in an integration.
Components are required
Symptom
You cannot create Aha! Roadmaps records from Jira and you see an error message that looks like this:
Remote error for ‘create_feature’: Data not accepted: components: Component/s is required.
Explanation
This error message means that the components field is set as a required field in your Jira configuration. It is not required by default.
Resolution
To resolve this issue, you can either configure Jira to not require the components when creating new issues or you can configure a mapping to a custom field.
Jira component or custom field mapping (one-way)
Aha! Roadmaps enables you to map custom fields from Aha! Roadmaps to components and other fields in Jira. In both cases, it is a one-way integration from Aha! Roadmaps to Jira. This means that changes in Jira will not be reflected back to your Aha!Roadmaps account.
Since Jira restricts the values that these fields can take, you must ensure all of the following conditions are met:
Configure the custom field in Aha! Roadmaps to only allow values that are valid for your Jira configuration.
The field can be named anything but its type must be Predefined tags field.
The tag values must exactly correspond to the possible component values that are configured in Jira.
Important notes:
All requirements of features will automatically be mapped to those custom fields.
For each feature that you want to send to Jira, make sure at least one component is chosen. If you do not choose a component that is required in Jira, you may receive the following error: Remote error for ‘create_feature’: Data not accepted: components: Component/s is required.
Mapping non-component custom fields to Jira
The process for mapping custom Aha! Roadmaps fields to default or custom fields in Jira is the same as above, except you may use the other custom fields — not just the Predefined tags field. Ensure that the values in each field match those that are in Jira. For example, if you only select one value in Jira, you will set up a custom field as a pre-defined choice list type.
Follow these steps to map custom fields in Aha! Roadmaps to Jira fields:
Set up the custom fields in Aha! Roadmaps.
Go to your Integration configuration page in Aha! Roadmaps and click Test connection to trigger a refresh of available Jira fields to which you can map.
Add a field mapping between the custom field you created and the component field in Jira.
Test by sending a feature with the custom field values selected to Jira (via the Integrations dropdown, then clicking Send to Jira).
Note that on Jira sprints, it is common to attempt to map a custom field in Aha! Roadmaps to the Jira Agile sprint field. However, the sprint field is key to the operation of Jira Agile. Changing the sprint affects a number of things. The Jira UI is able to display the sprint in a friendly way, but the API does not support translating the internal representation into a form that is useful to external systems. Unfortunately, this means that Aha! Roadmaps and other external systems cannot integrate.
No matching parent record found
Symptom
You cannot create Aha! Roadmaps records from Jira and you see an error message that looks like this:
Did not create new issue 'PROJECT_NAME-1234', no matching parent record found
Explanation
If a newly created Jira issue is the child of an issue originally created in Aha! Roadmaps, Aha! Roadmaps will create a new issue. If a newly created Jira issue wasn't the child of an Aha! Roadmaps issue, the issue will not be created in Aha! Roadmaps and you will see this warning.
For example:
Aha! Roadmaps record |
Jira issue |
Initiative |
Epic |
Feature |
Story |
Requirement |
Sub-task |
If you add a story to an epic that was created from Aha! Roadmaps a new feature will be added to Aha! Roadmaps for the story.
If you add a subtask to a user story or a task, a new requirement will be created in Aha! Roadmaps.
Aha! Roadmaps record |
Jira issue |
Initiative |
Epic |
Feature |
Story |
Requirement |
Task |
If you add a new task and use relates to to connect it to the user story, it will not be created in Aha! Roadmaps because tasks are not children of stories. New records in Aha! Roadmaps will not be created if the issue in Jira is not a child of a linked issue back to Aha! Roadmaps.
Resolution
These warnings can safely be ignored. If you wish issues to be automatically created in Aha! Roadmaps, you may need to review your mappings and choose issue types in Jira that allow for this. You may wish to follow our recommended Jira mappings.