Troubleshooting Jira

When integrating your Productboard workspace with Jira, there may be times when Productboard is unable to communicate with Jira. This article helps you to find some of the most common issues you might be running into with the Jira integration.

If the problem you're experiencing isn't on the list, reach out to our support team by clicking on the chat icon or sending an email to support@productboard.com.

In this article:

• Authorization issues
  • OAuth signature is invalid
  • OAuth Token was rejected
  • Invalid Jira server SSL certificate
• Webhooks
  • Expected webhook structure
  • Webhooks aren’t present
  • Creating Webhooks Manually
  • Webhooks are present, but aren't working
  • Webhooks are present and working, but I see an error in my integration settings
  • Limiting Webhook activity using custom JQL filters
• Project fields
  • Reporter is missing
  • Productboard URL isn’t configured
• Other issues
  • The integration authorizer no longer has access to Jira
  • Unable to push to Jira - required fields
  • Custom single or multi-select fields not syncing
  • Why can't I access some Jira projects or Jira issues from the Jira integration?
  • All Productboard updates in Jira associated with a single user
  • When pushing a feature as an epic and a subfeature as a story/task, Jira does not reflect the child/parent relationship.
• See also

Authorization issues

OAuth signature is invalid

Issue description

This error message indicates that the authentication between Productboard and Jira failed. As a result, the Application Link couldn't be created. (For more information about Application Links, read the Atlassian documentation).

Issue resolution

Below you can find different resolutions based on the scenario you're experiencing.

Scenario 1: The URL used in Productboard is different from the URL defined in Jira.

• Make sure that the Base URL is correct for each application.
• The Application URL and Base URL should be the same unless you're bypassing a reverse proxy.
• If the Application URL is different from the Base URL (and you're not bypassing a reverse proxy), delete and recreate the Application Link.

Scenario 2: A reverse proxy or port forwarding is configured, and the Host header reports the wrong hostname or port.

Make sure you configure the application correctly for use with a reverse proxy. Ensure the reverse proxy is correctly proxying HTTP headers to the downstream.

For more information, see Atlassian documentation here.

OAuth Token was rejected

Issue description

This error message indicates that an OAuth token has been revoked on Jira or Productboard. This may happen because:

• A user manually revoked the OAuth token at the other end.
• The Application Link OAuth configuration was changed at the other end, triggering the removal of all OAuth tokens.

After this warning appears once, the system will discard the token. The user also needs to re-authenticate, so this should not cause any further problems besides the inconvenience.

If you use 2-Legged OAuth (2LO) with either an Execute As user or impersonation, you should never encounter this warning.

Issue resolution

1. Make sure all application links are revoked in JIRA.
2. Re-start the integration process in Productboard, generating a new token.
3. All existing integrations will need to be re-added to get the new token.

For more information, see Atlassian documentation here.

Invalid Jira server SSL certificate

Issue description

You might see an error in Productboard that says that JIRA does not have a valid SSL certificate.

Issue resolution

Productboard requires that all Jira servers have valid SSL certificates. If yours is invalid, a minor update may be all you need to be on your way.

See what's causing the issue using a utility like this SSL Server Test.

Webhooks

Expected webhook structure

Productboard creates two types of webhooks in Jira:

1. Workspace Sync Webhooks for handling all 2-way synchronization of mapped fields between Productboard and Jira (Mapping fields guide).
2. Automatic Import Webhooks for controlling the automatic import of newly created Jira issues into Productboard using a custom JQL filter (Automatic import guide).

Note: When automatic import is enabled without a custom JQL filter, Productboard will rely on the workspace sync webhook to import issues automatically. Automatic import webhooks will be generated automatically in Jira when a custom JQL filter is applied in your Productboard integration settings. If your integration was authorized by a non-admin account, it will be necessary to create this webhook and apply the desired JQL filter manually.

The structure of these webhooks in Jira is as follows:

Workspace and integration IDs as well as tokens can be provided by Productboard’s support team. Request this information by contacting support@productboard.com.

Webhooks aren’t present

Webhooks will be automatically created in Jira by Productboard when the integration is authorized by an admin with the permission to create and modify webhooks.

When an integration is authorized by a non-admin user via the API Token, or Personal Access Token methods, Productboard will not have the ability to create webhooks and they will need to be configured manually or the integration will need to be reauthorized using an admin account.

Creating Webhooks Manually

A Jira admin will have the ability to manually create webhooks after the integration has been authorized using the webhook structure listed above. Required IDs and tokens can be provided to a Productboard admin upon request by contacting support@productboard.com.

To create a webhook manually, follow Atlassian’s instructions available here

Webhooks are present, but aren't working

When webhooks have been established either automatically, or manually, but are not working as expected, further troubleshooting based on the observed behavior will be required.

Common scenarios include:

1. 2-way syncing is not working from PB to Jira

   Changes should always sync from PB to Jira, even in situations where webhooks have not been configured in Jira. In cases where no changes are syncing from PB to Jira:

   • Check to ensure 2-way syncing has been enabled for mapped fields in your integration settings.
   • Confirm that the user who authorized the integration has permission to update the fields being used in Jira as well as permission to view and edit issues in the target Jira project.

2. 2-way syncing is not working from Jira to PB Webhooks are required for 2-way syncing to occur between Jira and Productboard. This includes the syncing of Jira statuses that appear in the integration push button. If you are not seeing the expected updates in Productboard when changes are made in Jira, check the following:

   • Has the field being targeted for updates been mapped between Productboard and Jira?

   • Have you enabled 2-way syncing for this mapped field in your integration settings?

   • Are there any errors present in your Jira integration settings?

   • Are your webhooks configured according to the expected structure listed above?

   • Are webhooks successfully notifying external apps?

In some cases, communication to and from your Jira instance may be restricted for security purposes. This typically only impacts Productboard workspaces integrating with on-premise (data center, or self-managed) Jira instances. Productboard relies on webhook notifications received from Jira to process relevant feature and field updates. If your Jira instance is not able to successfully send webhook notifications to external applications, no updates will be made in Productboard.

To confirm whether or not webhook notifications are being sent to external apps, you can use third-party services like webhook.site to test webhook activity.

If it is confirmed that webhook notifications are not being sent to external apps, it is recommended that you review current internal restrictions with your infrastructure engineers or IT teams, engaging with Atlassian support to resolve the issue where appropriate.

Webhooks are present and working, but I see an error in my integration settings

Productboard can only view and manage webhooks when the integration has been authorized using a Jira account with Global admin permissions.

If you have authenticated the integration using the API token or Personal Access Token methods through a non-admin account, Productboard will be unable to create new or view existing webhooks.

If you have manually created webhooks after authenticating with a non-admin account, Productboard will be unable to verify that they exist and will still display webhook errors even though the required webhooks are active and functional.

In this case, webhook errors can be safely ignored. For assistance creating webhooks manually, reach out to Productboard's support team at support@productboard.com.

Limiting Webhook activity using custom JQL filters

In some cases, you may wish to limit webhook activity in Jira. Without any JQL filters applied, Productboard webhooks are triggered any time an issue is created, updated, or deleted.

JQL filters reduce noise by limiting the conditions when a webhook is triggered. Some common JQL solutions for the different webhook types include:

Workspace Sync

• “Productboard URL” is not EMPTY Limits syncing to issues that are already linked to Productboard.
• Project in (ABC, XYZ) Limits which projects updates are synced from.

Automatic Import

• Project in (ABC, XYZ) Limits which projects issues are imported from.
• issueType in (Epic, Story) Limits which issue types are imported.

Note: JQL Filters for Automatic import are managed in the integration settings under the “Automatic Import” section. JQL filters for Workspace Sync webhooks will need to be manually configured by a Jira admin.

Project fields

Reporter is missing

Issue description

When Productboard pushes a feature into Jira, it will attempt to set the owner of that feature as the Reporter for the Jira issue. If Productboard can't set the feature owner as the issue Reporter, Jira will list the person who authorized the Jira integration as the Reporter.

Issue resolution

1. Ensure that the feature owner in Productboard uses the same email address in Jira.
2. Ensure that Jira user contact details are visible to Productboard. For each individual user in Jira, click the avatar in the upper right corner and select Account Settings. Find the Contact section at the bottom of the page and optionally change the visibility settings to “everyone”.
3. Select Project settings in the left side menu, then scroll down to Permissions at the destination Jira project**.** Check if the user who authorized the integration has permission to Modify Reporter. You can find more information about editing project permissions in Atlassian's documentation.
4. Confirm that the Reporter field is present on the Create issue and Update issue screens in Jira.

Productboard URL isn’t configured

The Productboard URL field allows Jira users to quickly jump to linked items in Productboard. Once this field has been configured in Jira, it will be populated with the correct URL automatically when a new link is established. This field is easily configured for both Company Managed and Team Managed projects using the steps below.

Note: We recommend that you configure this field before conducting your first Jira import or creating issue links as this field can only be set for links created after configuration is complete.

Company Managed projects

When you authorize the Jira integration, a new Productboard URL field is automatically created for you in Jira, to help you jump back and forth between Jira issues and Productboard features/subfeatures easily.

To configure this field in Jira:

1. Select Settings > Issues.
2. Under “Fields” select “Custom fields”.
3. Search: “Productboard URL”.
4. Select “…” > “Associate to Screens”.
5. Select the default issue screens for all projects you wish to enable this field for.
6. Select “Update”.

Team Managed projects

1. In your Jira project, click Project Settings > Issue types > Choose your preferred Issue Type (Epic, Story, Bug, etc)
2. In the right-hand menu called Fields, under Create a Field, click the box called Short Text.
3. Under Enter Field name, type Productboard URL.
4. Click Save Changes.
5. Drag the Productboard URL under the Context Fields section.
6. Repeat the same steps for any other Issue Type as needed.
7. From the right-hand menu under Previously Created Fields, drag the section Productboard URL under the context fields section.
8. Click Save Changes.
9. Repeat the same steps for the other Issue Types – Story, Task, and Subtask, ensuring to click Save Changes for each one.

You'll now see a Productboard URL field displayed on issue screens.

Other issues

The integration authorizer no longer has access to Jira

Issue resolution

Reauthorize the integration using an active Jira account.

Unable to push to Jira - required fields

Issue resolution

If a push from Productboard to Jira fails, and the resulting error indicates required field values are missing, check to confirm if any of your mapped fields are required fields in Jira. If a required field has been mapped with Productboard, the mapped field will need a value present before a new issue can be created in Jira.

Custom single or multi-select fields not syncing

Issue resolution

Select fields will require exactly matching values between Jira and Productboard in order to sync. If your select fields are not syncing as expected for some values, check to ensure you don’t have a leading or trailing space e.g., “VALUE1 “ or “ VALUE2”.

Why can't I access some Jira projects or Jira issues from the Jira integration?

Issue resolution

The user who set up the integration might not have the Jira Administrator Global Permissions. If that's the case, the user doesn't have access to all Projects or Issues. Simply reauthorize the integration using an account that has permission to view, create, and modify issues in your target projects.

All Productboard updates in Jira associated with a single user

Issue description

Suppose a Productboard maker changes a feature or subfeature description in Productboard. In that case, the feature is updated in Jira. Still, the Jira History tab shows that the change was made by the Jira admin who authorized the integration, not the Productboard maker who actually affected that change.

Issue resolution

In Jira, you will always see the admin user who authenticated the integration as the user who created the issue in the history tab. For that reason, we recommend creating an artificial “Productboard” user in Jira and authenticating with that artificial user, so that you see issues that originated in Productboard (and not the specific admin user who authenticated). The Feature owner can be different and will be displayed as “Reporter” in Jira.

When pushing a feature as an epic and a subfeature as a story/task, Jira does not reflect the child/parent relationship.

Issue description When you push a feature from Productboard to Jira as an epic and have a subfeature that you push as a story/task, you would expect Jira to retain the child/parent relationship.

Issue resolution

You must add the Parent field (formerly called “Epic Link”) to all Create Issue and Edit Issue screens for all Jira projects you use with Productboard. You can find more information on how to add fields to create issues and edit issue screens in Atlassian’s documentation.

See also

• Getting started with Productboard's Jira Integration
• Setting up your Jira integration