Learn how to troubleshoot common Jira issues.
Integrating ProductPlan with Jira is typically seamless and easy. In some cases, ProductPlan may have trouble communicating with Jira so we've put together a few things you can try.
In some unique cases, your Jira instance may be set up differently than others. So if you find that you are still experiencing issues after reviewing this information, please don't hesitate to reach out to our team at support@productplan.com.
Setting Up Your Integration
How do I know which version of Jira I'm using?
Note: Finding which version of Jira that you're using may require assistance from your Jira Administrator.
After logging in to Jira, click on the "?" icon at the top right of your screen. Click on About Jira. Product and version information should be displayed in this area.
Additionally, some Jira accounts display version information on the bottom of each page after you log in.
My organization is migrating / upgrading to Jira Data Center v0.x. What does this mean for my integration?
Organizations are continuously ensuring their systems are effective and efficient. This, coupled Atlassian’s recent decision to discontinue support for Jira Server, means that you may be encountering updates to your Jira environment.
Generally speaking, moving to v9 of Jira’s Data Center will disconnect your integration. This version introduced a different way to authenticate, so your connection will need to be reset using their new authentication. This support center article includes instructions on setting (or resetting) an integration with Data Center v9.
Please keep in mind that migrating between Jira Cloud and Jira Data Center or Server will also likely result in updated Jira URLs, so your integrated roadmap bars may need updated links.
I got an error after entering my Jira URL. What's wrong?
Note: If this is the first time someone on your team is configuring the integration please be sure to work with a Jira Admin on the configuration steps listed here.
Here are possible reasons for seeing this error message below after entering your Jira URL:
Jira Cloud
-
The Jira URL you entered may be incorrect.
-
Your organization may have IP Allowlisting security in place. Please work with your Jira administrator to enable the proxy and allow our IP addresses (noted above). Please also see this Jira article for more information.
-
A server may be down and you need to try again later.
-
A request times out. Please wait a few minutes and try again.
Jira Server or Data Center
-
The Jira URL you entered may be incorrect.
-
Our IP Addresses (noted above) must be allowlisted on your organization's firewalls. Please connect with your Jira administrator and IT team for assistance.
-
Your firewall needs to be configured to correctly route traffic to your Jira server.
-
A request times out. Please wait a few minutes and try again. If the problem persists, please contact your IT team for assistance.
-
Your server may be down or was made inaccessible over the internet
I got an error message after adding the ProductPlan application link in Jira. What's wrong?
"We were unable to connect your Jira application. This could be because you have not configured your Jira application or because your Jira endpoint is not typed correctly. Please try again, or contact support if you are having trouble"
To fix this error, follow these steps:
-
First, check to be sure that you copied the Incoming Authentication Key in its entirety. You may need to scroll to the bottom of the modal in Jira to see all the fields.
-
If you are still receiving an error message and you can confirm that the Incoming Authentication Key is correct, please be sure to double-check your Jira URL is correct: http://yourcompany.atlassian.net
I got an error message about an invalid public key. What's that mean?
Public Key is Invalid:
After entering in the Public Key, you may receive an error message that says:
"ProductPlan" (Generic Application) is not registered as a service provider and "JIRA" (JIRA) cannot make requests using OAuth."
To fix this error, follow these steps:
-
Make sure you have admin access to Jira
-
Double-check that your Jira URL is correct
-
Be sure that you copied the whole entire Public Key (including the beginning and end certificate).
I am using Jira Data Center, and am still not able to set up my integration.
Work with your IT team to review your organization's server environment to ensure the following:
-
Check the serve.xml file (located at <jira-install>/conf/server.xml) inside the connector piece for the following attributes:
-
scheme="https"
-
proxyName="<your_base_url>"
-
proxyPort="443"
-
secure="true"
Should look like this:
<Connector port="8080" relaxedPathChars="[]|" relaxedQueryChars="[]|{}^\`"<>"
maxThreads="150" minSpareThreads="25" connectionTimeout="20000" enableLookups="false"
maxHttpHeaderSize="8192" protocol="HTTP/1.1" useBodyEncodingForURI="true" redirectPort="8443"
proxyName="<your_base_url>" proxyPort="443" scheme="https" secure="true"
acceptCount="100" disableUploadTimeout="true" bindOnInit="false"/>
-
-
Confirm that your Jira applications are running over SSL or HTTPS (support article).
Additionally, you should confirm that:
-
Your base URL is accurate. If you previously had an integration set up, it should be the same as before.
-
Your redirect URI is correct (support article).
-
You’ve entered client id and secret.
-
Your application link’s capability should be set to Write.
If you are still experiencing issues, please utilize your organization's logging tool to troubleshoot.
I want to use multiple Jira projects but it's only allowing me to choose one upon configuration?
You can choose more than one Jira project later on, we just need you to choose one to start so you can choose which fields you'd like mapped from Jira to ProductPlan. When importing or syncing, you can choose issues across multiple projects. As long as those projects share the same field usage as your initial Jira project, we will be able to support mapping to your ProductPlan fields.
Syncing Information
I've chosen a project to connect Jira to ProductPlan, why can't I choose "sync now"?
After you have chosen a project, and chosen which fields you want mapped from Jira to ProductPlan, you will then want to Import items into your Parked Section of your Table Layout before you can sync.
What happens if I import items from Jira or sync items on a roadmap that I am not the owner of?
You do not need to be the owner of a roadmap in order to import or sync with items from Jira. However, keep in mind that we will always use the roadmap’s owners field mappings as the source of truth for the sync.
You can review the field mappings for your roadmap by clicking on Roadmap Settings, then navigating to the Integrations section. Please note that Jira allows for two fields to have the same label, so further troubleshooting may need additional assistance from your Jira Administrator.
My updates are not syncing from Jira.
Example #1: I updated information in Jira, but when I click ‘Sync from Jira’ on the roadmap, the fields are not refreshed.
-
A roadmap’s information is synced based on the fields that the roadmap owner mapped. If you are an editor of a roadmap, your Jira integration fields may be different. You can review field mappings in the Integrations section of the roadmap settings, view the mapped field in the integration error details, or check with the owner of the roadmap.
Example #2: My edits are not updating, but it looks like I have the correct field mappings.
-
Jira allows multiple fields to have the same name, so occasionally there is a case of “mistaken identity” when mapping and syncing your Jira integration. This Jira article may help shed light on how to check the fields for issues, or your Jira administrator can help review the fields for the project(s) you are trying to sync.
Why are my percent complete calculations inaccurate?
Example: "My bar in ProductPlan is showing that it is X% complete, but in Jira the epic is 100% complete. I've tried refreshing in ProductPlan and it's still showing X%."
To fix this error, follow these steps:
-
We use Jira's Resolution field (not the Status field) to calculate percent complete, so first be sure that the “Resolution” field is set to a done type state (typically it will be called “Done” but it can have different names). Sometimes the issue is that your team may have configured JIRA in a customized way (e.g. using the Resolution field for something else). If it is, it will be counted towards completion. You may also want to review articles for Jira Cloud or Jira Center if you need additional assistance in troubleshooting the Resolution field settings.
-
We calculate percent complete based on all Issue types (Story, Bug, Task, etc. - except for Sub-Tasks). These must be direct descendants of the item in question; we do not look at the status of issues below the initial level.
-
If it's still not updating, check your integrations page. You can set percent complete to Story Points or Number of Stories - please make sure you're mapping to the correct field.
Why aren't my dates syncing correctly?
To fix date syncing errors, please check if any of the situations below apply to you and adjust accordingly:
-
First check to see if your Jira dates are outside the range of the main roadmap timeline date range.
-
Check to see if your Jira issue has two dates. Jira does not require dates, but roadmaps require both start and end dates in order to sync.
-
If you change the date mappings on your ProductPlan Integrations page for items currently on your roadmap syncing with Jira then this could break the lock as well.
-
If the child bars in a container have Jira sync dates that will place them outside the start/end date of the parent container, the child bar(s) date sync lock will be broken and the bars will not move.
-
If you are working on a roadmap that you are not the owner of, and the roadmap owner does not have Jira dates configured, the sync will not work.
-
Verify that you have the correct date fields syncing; sometimes teams are under the assumption they're utilizing a "due date" field for "end date", but may actually be using some other title, like "complete date", etc.
-
If the roadmap owner imports issues from multiple projects that have different start/end dates then it will only sync dates for the projects that have the same dates as the mapped fields. For items in different projects with different dates it will sync title, description and percent but not dates.
On a failed pull we can sometimes show an incompatible data state in your timeline or list layouts. When this state is present, you can use the integrations pane in the bar's details to understand more about the failure and work to address the issue.
This error alert shows the fields with errors, the type of error encountered, and the mapped fields in the associated integration.
My Lanes / Legends are not syncing. What's wrong?
To fix lane or legend syncing errors, please check if any of the situations below apply to you and adjust accordingly.
-
If you change the roadmap-specific fields on your Jira Integrations page for items currently on your roadmap syncing with Jira then this could break the lock as well.
-
If you are working on a roadmap that you are not the owner of, and the roadmap owner does not have Jira lanes/legends configured, the sync will not work.
-
Verify the lane and legend fields you'd like to appear in ProductPlan are from custom drop-down fields in Jira.