# Jira Server Troubleshooting Guide Troubleshoot IP safelisting, connection credentials, and user mapping issues specific to the Jira Server and Data Center integration setup. ## Pre Checks ### 1. IP Safelisting Requirements Before starting the troubleshooting process, please ensure that the required PagerDuty IP addresses have been safelisted. - [REST API IPs](/developer/rest-api-ips) - [Webhook IPs](/developer/webhook-ips) - [Jira Server Integration](/account-admin/safelist-ips#jira-server-integration) ### 2. Jira Server Compatibility Requirements Your Jira Data Center/Jira Server version should be compatible with the integration version you have installed. For more information, please reference the compatibility table linked below. - [PagerDuty for Jira Server & Data Center](https://marketplace.atlassian.com/apps/1218226/pagerduty-for-jira-server-data-center/version-history) ### 3. Connection Credentials In Jira, navigate to the PagerDuty application under **Administration** → **PagerDuty settings** → **Account Integration** tab. The credentials must be valid for the PagerDuty and Jira connection. - For URLs, be sure to specify http or https in the field. If the protocol is not specified, the integration will use HTTP. - The user credentials should have read/write access to the connected projects and they should be basic authorization credentials (i.e., username and password), not SSO. - The REST API Key should be a full access key (i.e., not a read-only API key). ![The PagerDuty settings page in Jira showing the REST API key connection credentials](/images/kb/837dd8042bac842ca33bb0038324b4be00024672756bb1a82b84e8c5c49c58b9-PagerDuty_settings.webp) ## General Troubleshooting ![The PagerDuty settings menu location in Jira administration](/images/kb/24891bad9da58b5107d8b9f8299ede7e85adcc4c56ca45480da4fa0a0e950d9d-Jira_PagerDuty_settings.webp) In Jira, under the **User mapping** tab: - There should be a fallback user mapping in the **User mapping configuration** section, in case the Jira action/PagerDuty action cannot be attributed to a linked user account. If the issue persists after completing the pre-checks and general troubleshooting steps, please refer to the following section for more specific troubleshooting steps. ## Troubleshoot Common Jira Server Issues ### PagerDuty Incident did not Create a Jira Issue **1. Project Permissions** ![The Jira project permissions configuration page](/images/kb/e6eb326df84ac9b33e9f8c20a4d7ba5c1836431fb9637c80bd9dfb55b6cbd6b1-permissions.webp) ![The Jira issue permissions settings](/images/kb/97f61023b827552cf2e347ffb5b9aed4a5abbbc400a3b4e6d29c2e3684961f64-issue_permissions.webp) In your Jira project settings, navigate to **Permissions**. In the permission scheme verify which users, groups, and roles can create issues within the project. - Has your Jira admin assigned the **create issues** permission to the Jira integration user or their group? Alternatively, do they have a project role that has permissions to create issues? **2. Issue Types** ![The Jira issue types configuration for the project](/images/kb/33872df406342228db46441f5be8b6f4484e96cf885e107a55e80d95c7a12d10-issue_types.webp) In your Jira project settings, navigate to **Issue types**. In the issue types scheme, confirm which issue types are available for your project. **3. Required Fields** ![The required fields configuration for a Jira issue type](/images/kb/8f41eac46f5880050969ccf79dadc0bc4eb720ef3ff6d3474309aea19fa2e296-fields.webp) In your project settings, navigate to **Fields**. - In the fields scheme, check which fields are available for the affected issue type. - In the fields scheme, check which fields are required/mandatory for the affected issue type. **4. Check Webhooks** ![The PagerDuty settings page in Jira showing the REST API key connection credentials](/images/kb/a3ef834e1065249856f09ea97e1222b748c9eb69d64d5237a058dee07303257b-PagerDuty_settings.webp) On Jira's mapping **Rules** page, confirm that there is a mapping connecting the Jira project to a PagerDuty service. Next, check that the connection is enabled. ![The Jira webhooks page showing the PagerDuty webhook entry](/images/kb/e4199e63e71858bf0d5e70594f1f3f7a15d3fbeaa39a7a1687b91ffa59ff4e4a-check_webhooks.webp) Click **Check webhooks** to the right of the mapping **Rules** page. Select the options above, **Fix missing or useless webhooks** and **Both Jira and PagerDuty webhooks**, to fix broken/invalid webhooks, then run the check. **5. Mapping Rules** ![The Edit Rule screen for a Jira mapping rule](/images/kb/af4ff2e7785989f5f6ed837683451a4138ac636be382adf6524492060cd5846f-edit_rule.webp) Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the **Create Jira issues from PagerDuty incidents** section. - Confirm the rule is configured to create a Jira issue when a PagerDuty incident is triggered. - The PagerDuty incident should match the priority and urgency conditions. If this option is not enabled, responders will have to manually trigger incidents from the incident page by selecting **Create Jira Issue** from the **More** dropdown. ![The PagerDuty incident details page with the Create Jira Issue option](/images/kb/94cce77b9ca9839491f9e9d841f669e38bd7ef0be0e2cc138cb0d832a8318619-PagerDuty_incident_details.webp) If the project has required/mandatory fields for that issue type: - Your Jira administrator can populate custom fields with a default value: - [Set the default value for a custom field](https://support.atlassian.com/jira-cloud-administration/docs/configure-a-custom-field/#Set-the-default-value-for-a-custom-field) - You can add an action to map Jira fields to a PagerDuty incident attribute. ![The mapping rule action settings for creating Jira issues from PagerDuty incidents](/images/kb/e9b0a908908aebbbbdecc17c56d80f38fb8894f46d343005a64544e11062e2be-create_jira_issues.webp) **6. Additional Checks** - The PagerDuty attribute should match the data type expected for the Jira field. - Your Jira administrator can check if there are any conflicting automations configured to process incoming webhooks, or handle automatic issue creation. ### Jira Issue did not Trigger a PagerDuty Incident **1. Check Webhooks** ![The PagerDuty settings link in Jira administration](/images/kb/efd3ad83ff23bb701222b09a8b7ba38bc00e08566759a2a04483d57fe3f87042-jira_pagerduty_settings.webp) On Jira's mapping **Rules** page, confirm if there is a mapping between the Jira project and the PagerDuty service. Next, check that the connection is enabled. ![The Jira mapping Rules page showing the project-to-service mapping](/images/kb/cf66665f93dd8c5c8f41576f2d304e39fd3ae017ff1b90ce92eb3cae99812764-check_webhooks.webp) Click **Check webhooks** to the right of the mapping **Rules** page. Select the options above, **Fix missing or useless webhooks** and **Both Jira and PagerDuty webhooks**, to fix broken/invalid webhooks, then run the check. **2. Mapping Rules** ![The Create mapping rule screen in Jira](/images/kb/fceb929549f5964449ca903c1e588f4ba95965c60d00110630a360489641350e-create.webp) Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section **Automatically create PagerDuty incidents from Jira issues**. - Confirm that the Jira issue matches the project and issue type defined in your rule. - Copy the JQL statement, and search for Jira issues matching the condition. Does the Jira issue appear in the search results as expected? - Verify that **On issue create** is selected. If **Automatically create PagerDuty incidents from Jira issues** is not enabled, responders will have to manually trigger a PagerDuty incident from the PagerDuty app in the issue sidebar. - [Issue Context](https://developer.atlassian.com/cloud/jira/platform/modules/issue-context/) ### PagerDuty Incident Status and Jira Issue Status did not Sync **1. Mapping Rules** ![The Edit Rule screen for a Jira mapping rule](/images/kb/7536bc8a8650b2b9239bbf341bf9da67e6c6b5c55091285275fd4fe8bdeb3139-edit_rule.webp) Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section **Automatically update Jira Issue**. - Confirm there is an action mapping the PagerDuty incident status to the Jira issue status. Scroll down to the section **Automatically update PagerDuty incident**. - Confirm there is an action mapping the Jira issue status to the PagerDuty incident status. The PagerDuty application cannot transition issues/incidents to or from statuses that are not mapped in your rule. **2. Issue Workflow** ![The Jira project settings menu](/images/kb/cae5bf1167cd1da40c4f15d65fbe75d706b2aea841d279189d971e1ef5b48b4f-project_settings.webp) ![The Jira project workflow diagram showing issue transitions](/images/kb/54e6068415305f7e5bb21bfef7f87375422d128a00ec29229b2f6f4043c376a6-project_management_workflow.webp) In your Jira project settings, navigate to **Workflows**. - There should be a workflow scheme associated to the issue type. - Check if there is a workflow transition for that project and issue type, which would allow the issue to transition directly from the current status to the desired status. **3. Additional Checks** **In PagerDuty:** - On the incident page, confirm if the Jira issue is linked to the PagerDuty incident. The Jira issue must be linked to the incident in order to sync the incident record between the two platforms. ![A PagerDuty incident page showing the linked Jira issue](/images/kb/5b8085339d4cf75bcb49205e8babddb737a1cdcc1abf05fe2147e81cf6d399ae-incident_detail.webp) **In Jira:** - Your Jira administrator can check if there are any conflicting automations transitioning the Jira issue to a different status than the one you expected. - Your Jira administrator can check if there are any conflicting automations transitioning the Jira issue to an unmapped status. ### TLS Certificate Errors **1. Troubleshooting TLS Certificate Errors** Most commonly, TLS certificate errors occurs when: - A certificate in the chain has expired. - The certificate being used is self-signed or from an issuer not trusted by PagerDuty. - The certificate chain is out of order. - There is a duplicate certificate in the certificate chain. PagerDuty expects all certificates in the chain to be active, sent in the correct order (with no duplicates) and signed by a trusted root. The below openssl command, or a tool like [SSL Labs](https://www.ssllabs.com/ssltest/), may be helpful in identifying issues with the certificate chain. Please note that the port for your Jira instance may be different from the default `443` used in the example below: ```shell openssl s_client -connect :443 -showcerts ``` For more information regarding PagerDuty trusted root certificates, please reference the article below: - [Trusted Root Certificates](/developer/mutual-tls#trusted-root-certificates) ### Priority is not syncing between Jira and PagerDuty **1. Priorities Feature** ![The incident priority field on a PagerDuty incident](/images/kb/389a6cffe2a6f3f8fd62d4c9ed9838af8318a3bff79cdc48b1c6550b721ebbf6-incident_priorty.webp) To map priorities between Jira and PagerDuty, your PagerDuty account must have access to the [Incident Priority](/incident-management/incidents/incident-priority) feature, and your PagerDuty administrator must [Configure Incident Priority](/incident-management/incidents/incident-priority#configure-incident-priority). In PagerDuty, review the **Priority Level** column on the left, to confirm that the levels are labeled as expected. **2. Priority Scheme** ![The Jira project settings page showing the priority scheme](/images/kb/f38c2d75565031a7c698006fe713763955f4bde88e0f124a1cad72bb176c6f37-project_settings_priorities.webp) ![The View Priority Schemes page in Jira administration](/images/kb/f8b9a03f43a1b48af2df380e37baeae068e66f710eaf746167b3ba97cfb15350-view_priority_schemes.webp) In your Jira project's settings, navigate to **Priorities**. - Verify that the correct priority scheme is associated to your project. - Verify that the priority you were expecting is available in the priority scheme. **3. Priority Mapping** ##### Set Priority for a PagerDuty Incident ![The Jira settings menu used to set priority for a PagerDuty incident](/images/kb/94f0326f8c5b97c907c83e9f9985f810b68229e6a3006c3de0e64c2ee39a8e80-jira_settings.webp) Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section **Automatically create PagerDuty incidents from Jira issues**. - This section should contain mappings between the priorities defined in your JQL statements and the associated PagerDuty [Incident Priorities](/incident-management/incidents/incident-priority). ##### Set Priority for a Jira Issue Scroll down to the section **Create Jira issues from PagerDuty incidents**. - This section should contain mappings between your PagerDuty incident priorities and the associated Jira issue priorities. **4. Additional Checks** **In PagerDuty:** - On an incident's details page under the heading **Synced With**, confirm if the Jira issue is linked to the PagerDuty incident. The Jira issue must be linked to the incident in order to sync the incident record between the two platforms. - On an incident's details page, check if there is an [Incident Priority](/incident-management/incidents/incident-priority) assigned to the incident. ![The PagerDuty incident details page with the Create Jira Issue option](/images/kb/ab441bd39243157c3ec787d40b3cd4df009c569147e220ed33c634240b294a7b-PagerDuty_incident_details.webp) **In Jira:** - Your Jira administrator can check if there are any conflicting automations configured to set the issue priority. ### PagerDuty Incident Fields and Jira Issue Fields did not Sync **1. Screens and Screen Schemes** ![The Jira Screens configuration page](/images/kb/a4fbb31558f5d7abb0b3f2f58fb69c69dd71bc6ae223b596dea5ee4c03297cfd-screens.webp) ![The Jira Screen Schemes configuration page](/images/kb/dfe8c7a358aaff1bb414877505bdbf2e57ddb2c60ca4cf63aabc9eeaaeea9f96-screens2.webp) ![The Jira issue screen showing PagerDuty fields](/images/kb/83e328ba499effbf0b8026f72ba1e93ddfc03edc52194cb9eaccad98ee0f54e9-jipr.webp) The issue field must be placed on a screen that is mapped to the create issue operation via a screen scheme. The screen scheme must be mapped to the issue type via a issue type screen scheme that is associated to the Jira project. - In Jira, navigate to **Project settings** → **Screens**. This should allow you to view the screen scheme associated to your Jira project. - Click on the screen scheme to view the issue types associated to the scheme, and the screens associated to each Jira issue operation. - Select the **Create Issue** screen to view the available fields for the create issue operation. ![The required fields configuration for a Jira issue type](/images/kb/4c3036f74c30ea2d57251561009d908cdae1874079a12aa97880955d69a4182a-fields.webp) In your project settings, navigate to **Fields**. In the fields scheme, check which fields are available for the affected issue type. **2. Field Mapping** ![The field mapping section of a Jira mapping rule](/images/kb/8719f2c474f195fe443a3d40b017f1cd5b6e1aa5e75c206d5a9ca828bd698446-field_mapping.webp) Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section **Automatically create PagerDuty incidents from Jira issues**. - This section should contain an action that maps the PagerDuty incident field to a Jira issue field. Scroll down to the section **Create Jira issues from PagerDuty incidents**. - This section should contain an action that maps the Jira issue field to a PagerDuty incident field. **3. Additional Checks** - PagerDuty attributes should match the data type expected for each Jira field. - Your Jira administrator can check if there are any conflicting automations configured to populate the affected issue field. - The **Jira Integration** user should be granted permission to [Edit issues](https://support.atlassian.com/jira-cloud-administration/docs/permissions-for-company-managed-projects/) within the project. ![The Jira issue permissions settings](/images/kb/752052b2cb8df0b1354f125335176ed2b94e44f093343a76182cda1c5264aadd-issue_permissions.webp) ### A Jira Ticket Triggered Multiple PagerDuty Incidents **Mapping Rules** ![The PagerDuty settings page in Jira showing the REST API key connection credentials](/images/kb/ae47b7a47e3c15787fd8808fbc5f55902a6f44979e26dfa69805e7f9b8272eef-PagerDuty_settings.webp) In Jira, navigate to your mapping **Rules** a check the JQL trigger condition within each rule. Check if there are multiple rules with a JQL trigger condition matching the Jira ticket. ![The Create mapping rule screen in Jira](/images/kb/ff9210f1f648caa739f3c4b916d9ec2d3c6aca7968756a23ca535175bc47398e-create.webp) Review the changes/updates to the Jira issue, to confirm if any updates caused the Jira issue to match the trigger condition again. ### Incident Notes and Issue Comments are not Syncing **Comment Permissions** ![The Jira project permissions configuration page](/images/kb/37d548554c3859155484b9ff8269170e76913270842b3aaba287202ecd8a116e-permissions.webp) ![The Jira comment permissions settings](/images/kb/6f1e935be262beb9961a4bd0b694a3a6e2c358327a9b6ae6aa33fb3c2ec9fef0-comments_permissions.webp) In Jira, navigate to your project settings' **Permissions**. Check the permission scheme to confirm which users, groups, and roles can comment on issues within the project. **Mapping Rules** In Jira, locate the rule connecting the PagerDuty service to your Jira project. Confirm that the **Sync comments & notes** setting is enabled. ![The Edit Rule screen for a Jira mapping rule](/images/kb/a2349cb3bab1818fdcd30d6947dff92282e4654d625f21594ad7e3a5243162f5-edit_rule.webp) **Additional Checks** On a PagerDuty incident's details page under the heading **Synced With**, confirm if the Jira issue is linked to the PagerDuty incident. The Jira issue must be linked to the incident in order to sync the incident record between the two platforms. ## JQL Tips and Tricks - To test the JQL statement in your configuration rule, paste the JQL statement in your configuration rule to Jira, to confirm if that query returns the Jira issue as expected. - There are some AI chat assistants that may be able to help you construct/review your JQL statement. To test the JQL statement, use the testing method above. - For additional details regarding JQL, please reference the resources linked below. ## Additional Resources ### JQL Fields - [JQL fields](https://support.atlassian.com/jira-service-management-cloud/docs/jql-fields/) - [JQL keywords](https://support.atlassian.com/jira-service-management-cloud/docs/jql-keywords/) - [JQL operators](https://support.atlassian.com/jira-service-management-cloud/docs/jql-operators/)