Troubleshooting Jira Integration Issues
Overview
The following are common Jira integration problems and potential solutions.
Uninstall and reinstall the Jira integration only as a last resort. If you do this you will have to reconfigure any Jira project mappings and reconfigure Jira-related runbook steps. For changes to Jira integrations settings, including Jira project configuration, a FireHydrant owner role is required.
Jira incident ticket runbook step failures
From the incident command center in the web UI, check the Jira issue runbook step execution information for errors.
Jira connection authorization needs to be refreshed
This may appear as a token refresh error, for example:
Unable to run and failed entirely. ticketing.ticket_sync_error {"error":"invalid_grant","error_description":"Unknown or invalid refresh token."}
To recover, access the Jira integration settings from Integrations > Jira Cloud (or Jira Server (on premise)) configuration settings. Check the Connection Health. 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.
In order to reauthorize the integration, the account/person who set up the Jira integration must do the reauthorization. The reauthorization can be done from the Jira integrations configuration settings or from the User > My Account settings.
To prevent single points of failure, FireHydrant recommends that a generic Jira system account be used to configure the integration. That allows for multiple FireHydrant admins to manage the integration and prevents problems if a named employee leaves.
No Jira project was specified as the destination
When you add a Create a Jira Cloud Issue step, you'll need to specify the destination project. 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.
Specified Jira project has an unmapped required custom field
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.
Jira action item ticket creation failures
FireHydrant action item Slack command nuances
The following Slack commands will not create an associated Jira ticket:
/fh add task
/ft add task-list
If you would like to create a task with an associated Jira ticket, use the following command instead:
/fh add action-item
Tasks created with the web UI will also create associated Jira tickets when configured.
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
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 on-prem configuration changed
Changes to Jira on-prem permissions or urls can result in the integration connection breaking.
Jira Server projects are missing when attempting to configure multi-project
If after Jira integration setup, you are unable to connect to and view Jira projects with the integration authorizer account, this may be due to the Jira SSO configuration. To correct this, grant the integration authorizer account the ability to connect to Jira Sever via user name and password rather than through SSO.
Another item to check is that you have configured your firewall settings to allow Jira Server to connect to FireHydrant's static IPs.
Jira project of interest is unavailable for selection
A misconfiguration can result in Jira project not appearing in the selectable action item or runbook Project list.
Check that the project of interest is configured in the Jira field mappings and that any required custom fields are mapped.
Jira ticket 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:
- Configure the project with a temporary ticket type, one that does not have custom required fields.
- Map the custom required field.
- Return to the Jira project configuration and replace the temporary ticket type with the permanent one.
Jira ticket attribution issues
Incident ticket attribution problems
With Jira Cloud, when a runbook step is manually attached or executed, the Jira ticket reporter will be the FireHydrant users if their FireHydrant and Jira accounts are linked. This will not occur with Jira on-prem due to a limitation with the Jira software.
Action item ticket attribution problems
Ensure that the FireHydrant user's account is linked to Jira to have correct action item ticket attribution in Jira. Have the user to go to User > My Accounts. Under Linked Accounts find Jira and click Link.
Building in Jira integration configuration resiliency
To reduce the potential for Jira integration failures, FireHydrant recommends the following best practices:
-
Use a generic system account to set up the Jira integration. This way, if a named employee leaves the organization or is out of the office, another admin can reauthorize the Jira connection.
-
Uninstall and reinstall the Jira integration as a last resort only. If you do this you will have to reconfigure any mappings and reconfigure Jira-related runbook steps.
-
Ensure that any Jira projects of interest are mapped in FireHydrant.
-
Ensure that any configured Jira projects that contain custom required fields also have a mapping or default value for the required fields.
-
Set a default project under Organization > Account Overview settings.
-
If Jira ticket reporter attribution is critical, ensure that FireHydrant individual user accounts are linked to Jira accounts through the User > My Account settings.
-
If a Jira ticket is required for FireHydrant tasks, use the web UI or the Slack command
/fh add action-item