Jira
Overview
Jira issues can be automatically created in case of Sifflet monitor failure and manually created from Sifflet incidents. Generating Jira issues ensures data quality problems detected by Sifflet fit into your existing incident and task management workflow and that no important issue gets accidentally overlooked.
Manage the Integration
Set up the Integration
You can allow the creation of Jira issues from Sifflet monitors and incidents and activate Jira-based Sifflet incidents closing using the built-in Jira integration.
Allow Issue Creation From Monitors and Incidents
Follow the below steps to set the Jira integration up and allow your team to create Jira issues from Sifflet monitors and incidents:
- Sifflet authenticates to Jira using an API token. If you already have one handy, copy it. Alternatively, follow the below steps to create a new one. If you need any additional information on the below steps, you can visit this Atlassian documentation page.
- Go to your Jira application and head to
PERSONAL SETTING
>Personal Jira Settings
- Go to the
Security
tab - In the
API tokens
section, click theCreate and manage API tokens
- Click
Create API token
- Give a label to your API token, for instance
Sifflet integration
and click theCreate
button. - Click the
Copy
button.
- Go to your Jira application and head to
- Go to your Sifflet application, hover the
Settings
sidebar entry and click theCollaboration Tools
entry.- Go to the Jira section and click the
Connect to Jira
button - Complete the form that shows up in a modal:
URL
: Enter your Atlassian account URL, e.g.https://companyname.atlassian.net/
User email address
: Enter your email addressAPI token
: Paste your previously copied Atlassian API token
- Click the
Connect
button.
- Go to the Jira section and click the
- If you have a success message and the Jira integration shows up as
Connected
, it means Sifflet was able to connect to Jira and has access to at least one Jira project.
Activate Status Changes Sync
Optionally, you can enable status changes sync from Jira to Sifflet. This will ensure any Sifflet incident gets moved to In progress
or Closed • Fixed
when its linked Jira issue gets transitioned to an In-progress
or Done
status. Enabling status changes sync allows you to benefit from Sifflet incident management troubleshooting and collaboration capabilities while ensuring a smooth incident management process thanks to automated closing of your Sifflet incidents.
Follow the below steps to enable status changes sync from Jira to Sifflet:
- Click the switch button to turn
Enable status changes sync from Jira to Sifflet
on - Copy the webhook URL showing up in step 1 of the checklist
- Head to your Jira application to register your webhook. If you need any additional information on the below steps, you can visit this Atlassian documentation page.
- Click the gear icon at the top right hand corner of your screen and click
System
below theJira settings
section - Look for the
Advanced
section on the left sidebar and click theWebHooks
entry - Click the
Create a WebHook
button - Rename your webhook to reflect the fact that it's used for a Sifflet integration, e.g. "Sifflet integration webhook"
- Replace the
https://example.com/rest/webhooks/webhook1
in theURL
field by paste the URL you previously copied from the Sifflet app - Click the
Generate secret
button and hit the copy to clipboard icon to copy the generated secret to your clipboard. You will need to paste it on the Jira integration configuration on your Sifflet application in an upcoming step. - In the
Issue related events
section, check theupdated
checkbox below theIssue
subsection. This will ensure Jira sends an event to Sifflet whenever an issue gets modified.
If there's a high number of projects and issue types on your organization's Jira instance, it is recommended to consider specifying a JQL query to restrict sent events to the project(s) and issue type(s) of interest. - Click the
Create
button at the bottom of the page.
- Click the gear icon at the top right hand corner of your screen and click
- Head back to your Sifflet application
- Paste the previously copied secret in the field of step 5 of the checklist
- Click the
Connect
/Save
button.
- Your Sifflet incidents' status should now update following Jira issues status changes. You can confirm the sync is working by changing the status of a Jira issue linked to a Sifflet incident to a
In-progress
orDone
status and confirm that the corresponding Sifflet incident status gets updated accordingly.
Edit the Integration
You can edit your Jira integration, for instance if you need to change the user email address and/or replace the API token used by the integration. Follow the below steps to do so:
- Hover the
Settings
sidebar entry and click theCollaboration Tools
entry - Go to the Jira section and click the
Edit
button - Add the new value to the
User email address
field and/or click theChange
button belowAPI token
field to edit the API token value - Click the
Connect
button - If the modification is successful, you see a success message.
Disconnect the Integration
Follow the below steps to disconnect the Jira integration:
- Hover the
Settings
sidebar entry and click theCollaboration Tools
entry. - Go to the Jira section and click the
Disconnect
button. - Disconnecting the Jira integration will unlink all Jira issues from your incidents & prevent users from creating new Jira issues from Sifflet incidents. If that's ok for you, you can click the
Disconnect
button. - If the disconnection is successful, the Jira integration card should no longer display the
Connected
indication and should show theConnect to Jira
button.
Create Issue From Monitor
Follow the below steps to automatically create Jira issues when a new Sifflet incident gets created following up on a new monitor failure:
- Edit an existing monitor or create a new one
- Go to the
Notification method
section of your monitor wizard - Toggle the
Create incident when monitor fails
button - Tick the
Create Jira issue linked to incident
checkbox - Select the project you want your issue to be created in
- Select the type you want your issue to be created with
- Click the
Save
button - An issue will be created on every new incident creation. The link to the Jira issue will show up on your monitor details page and on the associated freshly-created incident page.
Create Issue From Incident
Follow the below steps to create a Jira issue from a Sifflet incident:
- On your incident page, click the
Create Jira issue
button - Select the project you want your issue to be created in
- Select the type you want your issue to be created with
- The
Summary
field is prepopulated with[Sifflet]
and the incident name. You can modify this as needed before actually creating the issue. - The
Description
field is prepopulated with details about the incident and corresponding monitors. You can modify this as needed before actually creating the issue.
If you carefully examine the prepopulated content, you will see some characters such ash3
, brackets, parentheses, etc.. These correspond to formatting characters Sifflet uses to ensure the Jira card created by default has a nicely formatted description. You can add more or get rid of this formatting as you see fit. Read more about formatting options on Jira documentation here. - Click the
Create issue
button. - If the issue creation is successful, you should see a success message and the
Create Jira issue
button should have been replaced by a button containing a link to the created Jira issue. You can click it to visit the Jira issue.
Status Changes Sync
If the status changes sync is enabled on your Jira integration, whenever a Jira issue linked to a Sifflet incident gets transitioned to an In-progress
or Done
status, the corresponding Sifflet incident will get moved to In progress
or Closed • Fixed
as a consequence.
If the Jira issue originates from a monitor the link to the Jira issue will also get removed from your monitor details page.
Sifflet incidents status changes triggered by Jira issues status changes are logged accordingly as events on the event timeline of incident details pages.
Unlink Issue
You can unlink a Jira issue from a Sifflet incident, which can be helpful if you wish to create and link a new Jira issue to the incident. Follow the below steps to do so:
- Click the downward arrow of the button displaying the Jira issue key
- Click the
Unlink Jira issue
button - If the unlink is successful, the button should change to
Create Jira issue
, allowing you to create a new Jira issue from this incident and link it to it.
If the Jira issue originates from a monitor, unlinking the Jira issue at the incident level will also result in the removal of the link to the Jira issue from your monitor details page.
Troubleshooting
I'm missing one or several projects when creating a Jira issue from a Sifflet incident
Sifflet integration for Jira uses an API token that inherits permissions of the user who created it. If one or several projects are missing from the list of projects when creating a Jira issue from a Sifflet incident, it's probably because the user who created the API token used at the integration level doesn't themselves have access to these projects.
To confirm, go to the Collaboration Tools
page, go to the Jira section, click the Edit
button, check the User email address
field and confirm with the person whose email is entered whether or not they have access to the project you're looking to create Jira issue in. If they don't have access, you might want to replace the existing User email address
and API token
with new ones that have permissions on the project(s) of interest.
Bad Request - Jira issue creation failed - Failed to create Jira issue: <FIELD_NAME> is required.
This error means you're trying to create a Jira issue with a type that involves some required fields. This isn't currently supported by the Jira integration. You should use an issue type that doesn't have required fields other than Summary
and Description
.
Sifflet incidents status doesn't change when Jira issues status change
This means there is most likely an issue with the webhook sending events to Sifflet. It's recommended to perform the following checks:
- Confirm that the status change sync is activated on your Jira integration configuration
- Confirm that the
Status
field of the Jira webhook configuration is set toEnabled
- Confirm that the
URL
field of the Jira webhook configuration uses the URL specified in the Jira integration modal on your Sifflet application - Try generating a new secret for your Jira webhook on your Jira application and edit it accordingly on the Jira integration modal of your Sifflet application
- Confirm that the the
updated
checkbox in theIssue related events
>Issue
section is checked. - Confirm that no JQL query in the
Issue related events
section excludes one or several of the Jira projects that should trigger events to update Sifflet incidents status.
Note: Only users with the "Admin" system role can access the Collaboration tools
page so you might need to reach out to someone on your team with the "Admin" system role to perform some of the above verifications if you have a more restrictive system role.
I got a success message after setting up my integration, yet Sifflet incidents status doesn't change when Jira issues status change
The success message issued after Jira integration set up only reflects the fact that Sifflet is able to create issues on at least one Jira project. It doesn't test the ability for changes on Jira's side to result in Sifflet incident status changes. If Sifflet incidents status isn't updated following up on Jira issues status change, check out this troubleshooting guideline.
My monitor is configured to automatically create Jira issues. The monitor failed, yet no Jira issue was created.
Jira issues only get created in case of new Sifflet incidents. If your monitor failed but no Jira issue was created, it might be because an incident was already opened for that monitor.
Integrating Sifflet and Jira Through Email
An alternative approach to integrate Sifflet and Jira is to leverage Sifflet Email integration and Jira's ability to create issues and comments from email. This approach can be relevant if you're looking to create Jira issues on every monitor failure, regardless of whether or not an incident was created.
Set up the Integration
Follow the below steps to set the integration up:
- Go to the
System
section of yourJIRA SETTINGS
- Click on the
Incoming Mail
entry of theMAIL
section - Copy the email address corresponding to the incoming mail server you want to send Sifflet failing monitor emails to from the
Set up your incoming mail server
section of the page - Head to the
Settings
>Collaboration Tools
page of your Sifflet application - Add the copied email address to the list of
Configured mail addresses
in theMail
section of the page - Head back to the
System
section of yourJIRA SETTINGS
- Click the
Add incoming mail handler
button in theMail Handlers
section of the page and configure it to suit your need
For more details on any of the above steps, visit the Sifflet and Jira related documentation pages.
Configure Monitors to Create Issues on Failure
Once the above steps have been completed, you can head back to your Sifflet application and start adding the configured email address to the monitors you expect Jira issues to be triggered from in case of failure.
Updated 9 days ago