Aha! Roadmaps | Integration configuration errors

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 integration configuration 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:

• Jira field is not available in the integration mappings

• Map Status to affect both Jira Status and Resolution fields

• Allow list errors

• Status mapping is not inherited from an integration template

• Unhandled 405 error

• Unknown error when choosing a Jira project

Jira field is not available in the integration mappings

Symptom

You want to map an Aha! Roadmaps field to a Jira field but you cannot find the Jira field in the list of available fields.

Explanation

This is a very common question. The answer is almost always one of two options:

• Because the user you have used to set up this integration does not have the proper user permissions to view those fields in Jira

• Because the field is not visible in the proper Jira Screens.

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 Edit screens 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

The Where is my field? option in Jira makes this easy to diagnose. Let's use it to find your missing field and add it to the missing screens.

Add your field to the Create screen

1. Log in as the same user you used to configure your Jira integration.

2. Click the + button on the left side of your screen to Create an issue.

3. Click the Configure fields dropdown menu, then click Where is my field?

4. Begin typing to find your field, then select it from the list of suggestions.

5. The Where is my field? modal will show you information on your field. Scroll down to the Field Screen section to see information on your field's Screen settings and where to go to change the configuration.

6. Follow the appropriate hyperlinks to modify the configuration of the field in question.

Add your field to the Edit screen

1. Log in as the same user you used to configure your Jira integration.

2. You need to edit an issue that already exists. Click Issues and filters, then click All issues.

3. To limit your search to issues in your project, click Basic, then use the Project dropdown to select your project.

4. Click on an issue's Key or Summary field to open it.

5. Click the Admin dropdown menu, then select Where is my field?

6. Begin typing to find your field, then select it from the list of suggestions.

7. The Where is my field? modal will show you information on your field. Scroll down to the Field Screen section to see information on your field's Screen settings and where to go to change the configuration.

8. Follow the appropriate hyperlinks to modify the configuration of the field in question.

Test the integration in Aha! Roadmaps

The last step is to update Aha! Roadmaps with the newly available field.

1. In Aha! Roadmaps, go to Settings ⚙️ Workspace and select your Jira integration. Click on the Mappings step.

2. Click Reload configuration at the bottom of the screen to force Aha! Roadmaps to update available fields. Your current mappings will not be affected.

3. The field should now appear as an option on the list of available field mappings.

4. Try sending a feature or release to Jira. The data that was previously not showing up should be there.

Top

Map Status to affect both Jira Status and Resolution fields

Symptoms

You want the Aha! record Status to inform both the Jira Status and Jira Resolution fields. If you use two separate mappings from these fields to the Aha! Status, you will see the following error:

'resolution': Could not find valid 'id' or 'name' in resolution object

Explanation

You can map Aha! Status to the Jira Status field, and you can also map Aha! Status to the Jira Resolution field — but not over two different mappings. Doing so will cause those fields to conflict and trigger the error above.

Resolution

Instead, use the Jira Status with resolution field in your field mappings. This allows you to show an issue's status (e.g. Closed) as well as its resolution (e.g. Won't Fix).

Top

Allow list errors

Symptoms

You are trying to configure your Jira integration and you see an error message that looks like one of these:

Configuration error for 'installed': getaddrinfo: Name or service not known

Execution expired

Event ‘installed’ failed due to an unhandled error

Error: request to <url to server> took too long to respond

Explanation

These errors could indicate a temporary network outage. But if they persist, they often indicate that your version of Jira is behind a firewall and Aha! Roadmaps does not have permission to access it.

Resolution

In order to grant Aha! Roadmaps access, you will need to add Aha! IP addresses to your allow list.

Top

Status mapping is not inherited from an integration template

Symptom

You are using an integration template for multiple Jira integrations but the record status mapping (usually the feature statuses) does not seem to be inherited along with the rest of the integration configuration.

Explanation

Generally, this issue occurs for one of two reasons:

1. You are using your integration template across multiple Aha! Roadmaps workspaces. Those workspaces have different statuses and workflows.

2. You are using your integration template across multiple Aha! Roadmaps workspaces. Those workspaces use different statuses on the associated projects in Jira.

Resolution

In either case, the integration template's status mapping will only work in situations where Aha! Roadmaps and Jira use the same exact statuses. You have a few options:

1. Configure both workspaces to use the same statuses and workflows.

2. Update both Jira projects to use the same issue statuses.

3. Choose to not map statuses in your integration.

Top

Unhandled 405 error

Symptom

After you have completed your integration configuration, you test the integration but see an error message that looks like this:

Remote error for 'installed': Unhandled error: STATUS=405

Explanation

You may get this error if your Jira instance is not running the latest version. The problem is that Aha! Roadmaps is trying to create a new custom field via the Jira REST API but older API versions don't support this operation.

Resolution

There is a simple workaround — you can create the field manually:

1. Create a new custom field in your Jira instance.

2. The custom field must be a URL type and be named exactly Aha! Reference. Aha! Roadmaps will use this field to store the link back to the related feature for each issue.

3. The field should be added to the Default screen.

Aha! Roadmaps will recognize this field next time it imports data from Jira and won’t try to recreate it.

Unknown error when choosing a Jira project

Symptoms

After you have completed your integration configuration, you are trying to select a Jira project to link with your Aha! workspace. You choose the desired project and you see an error message that reads:

An unknown error occurred while communicating with your Jira account

Explanation

You might encounter this error if you are trying to select a Jira project but do not have access permissions to create issues within that Jira project.

Each Jira integration's webhook runs as a particular user. That user needs to have Create and Edit permissions within your Atlassian account. You can only access Jira projects that your integration Run as user has access to.

Resolution

Ensure the selected integration user has access to Create and Edit issues in the chosen Jira project.

Top