Troubleshooting Jira Integration Issues

{% note %}
You should only uninstall and reinstall the Jira integration as a last resort. If you do this you will have to reconfigure any Jira project mappings and reconfigure Jira-related runbook steps.
{% endnote %}

Overview

The following are common Jira integration problems and potential solutions. Generally the issues can apply to both Jira Cloud and Jira Server, but there are different sections below for Cloud-specific and Server-specific troubleshooting.

Best Practices & Resiliency

To reduce the potential for Jira integration failures, FireHydrant recommends the following best practices.

You can also check these items for some potentially easy/quick fixes. If you're still seeing issues after following these best practices, then consult the rest of this guide for specific troubleshooting issues.

Cloud & Server

1. Ensure that the integration is installed and configured with a generic service account rather than with a named user.
   • This prevents any issues with the user offboarding and leaving an orphaned integration.
   • This also allows multiple admins to administer the integration independently of their own users and accounts.
2. Check that your service user is configured with the proper permissions. The project and issues permissions should be the same for both Cloud and Server.
3. Does your project or any issue types within the project have custom required fields? Make sure you configure those mappings.
4. Set a default project so that there's a fallback when creating tickets without a selected project.

Cloud-specific

1. If user attribution on tickets is important, then ensure each user has linked their FireHydrant account to their Jira account. You can find instructions on user linking here.
2. Jira Cloud uses OAuth connections, so occasionally an refresh token could expire. Follow these steps to refresh the connection:
   1. To do this, access the Jira integration settings from Integrations > Jira Cloud.
   2. Check the Connection Health on this page. Atlassian occasionally refreshes auth tokens, requiring a reauth from the account who authorized the Jira integration. You can find this account/person in the same integration dialog under Authorized by.
   3. While logged into Jira as the service account, click Reauthorize from the integration configuration settings page, or by clicking Link from the User > My Account settings while logged into FireHydrant as a service user.

{% note %}
Ensure you are logged into Jira as the generic service/admin account, not your personal Jira user, before doing this!!
{% endnote %}

Server-specific

• Ensure you've added FireHydrant's IP addresses to your allowed list/firewall.

Project configuration issues

Jira projects missing when attempting to configure in FireHydrant

Cloud

• Check and ensure the authorizing user/service account has at least browse access for the project(s) in question. See Jira permissions docs.

Server

• Like for Cloud, check and ensure the authorizing user/service account has at least browse access for the project(s) in question. See Jira permissions docs.
• Make sure the authorizing Jira account can connect to Jira Server via username and password rather than through SSO.
• Check your firewall/IP config settings.

Jira project can't be selected

A misconfiguration can result in a Jira project not appearing as an opiton when setting the Running step or creating a Follow-Up ticket.

1. Check that the project of interest has been configured and issues have been mapped
2. Next, check that any required custom fields are mapped.

Issue type unavailable in project configuration

If a ticket type contains an unmapped Jira custom required field, it may not appear in the multi-project configuration.  The recommended approach is to:

1. Configure the project with a temporary ticket type, one that does not have custom required fields.
2. Map the custom required field.
3. Return to the Jira project configuration and replace the temporary ticket type with the permanent one.

Jira Runbook step failures

From the incident command center in the web UI, check the Jira issue runbook step execution information for errors.

Invalid refresh token (Cloud)

You may see the following Runbook step error:

Unable to run and failed entirely. ticketing.ticket_sync_error {"error":"invalid_grant","error_description":"Unknown or invalid refresh token."}

This means that your authorized user will need to refresh the token/connection. See the docs above for instructions on how to do this.

No destination or default project selected

• Check that you have a destination project selected in your Runbook step.
  • This list is populated by the Jira projects that are mapped in the Jira configuration. For more information on field mapping, refer to the documentation.

• If no destination project is present, then FireHydrant will fallback to a default project if configured.
• If neither of the above is set, then the step will fail.

Required custom fields not mapped

Jira will reject requests to create a ticket if required custom fields don't have a value.  To populate those fields with mapped or placeholder values, see the Jira custom field mapping documentation.

Default Jira project was not configured

If a Jira project write failure occurs FireHydrant will attempt to use the Jira project configured as the default under the Organization > Account Overview settings.  If no default project is configured the step will fail.

FireHydrant Jira integration was uninstalled and reinstalled

Another potential cause is if someone has uninstalled and reinstalled the Jira integration.  When this happens, all previously configured Jira projects will need to be readded.

Jira configuration changed

Changes to Jira Server or Cloud permissions or Jira Server url can result in the integration connection breaking.  The account used to set up the Jira integration in FireHydrant needs to have the following permissions:

• Read all Jira projects to be used with FireHydrant.
• Read all Jira ticket types to be used with FireHydrant.
• Read all Jira fields and custom fields to be mapped in FireHydrant.
• Read and create issues in the projects to be used with FireHydrant.

Ticket creation failures

Jira ticket can't be created for a specific project or Jira tickets didn't get created in the expected project

Check the Jira custom field mappings in FireHydrant to ensure that any required custom fields have a value upon ticket creation.  If not, Jira will refuse to create a ticket.  If this failure occurs FireHydrant will attempt to use the default Jira project configured under the Organization > Account Overview settings.

Jira tickets can't be created in any Jira project

Jira connection needs to be refreshed (Cloud)

Refer to the above instructions.

FireHydrant Jira integration was uninstalled and reinstalled

Another potential cause is if someone has uninstalled and reinstalled the Jira integration.  When this happens, all previously configured Jira projects will need to be readded.

Jira configuration changed (Server)

Changes to Jira on-prem permissions or urls can result in the integration connection breaking.

• Check your audit logs in Jira for any recent changes.
• Also check your Jira integration's settings in FireHydrant and ensure the Default Authorized User is who you expect it to be. If you set it up this way, it should be a generic admin service account.

Ticket attribution issues (Cloud)

{% note %}
Ticket attribution to specific users is not supported with Jira Server due to a limitation with the Jira software.
{% endnote %}

Ensure the user's FireHydrant and Jira accounts are linked if this is not working as expected for them.

Incident ticket attribution problems

When a Runbook is manually attached or executed with a Jira ticket step, the Jira ticket reporter will be the FireHydrant user who performed the action.

If this is not working, then have the user double check and relink their accounts per instructions above.

Action item ticket attribution problems

When creating follow-up tickets, the corresponding Jira ticket can set both a Reporter as well as an assigned user.

If this is not working, then have the user double check and relink their accounts per instructions above.