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:

1. 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.
   1. Go to your Jira application and head to PERSONAL SETTING>Personal Jira Settings
   2. Go to the Security tab
   3. In the API tokens section, click the Create and manage API tokens
   4. Click Create API token
   5. Give a label to your API token, for instance Sifflet integration and click the Create button.
   6. Click the Copy button.
2. Go to your Sifflet application, hover the Settings sidebar entry and click the Collaboration Tools entry.
   1. Go to the Jira section and click the Connect to Jira button
   2. Complete the form that shows up in a modal:
      1. URL: Enter your Atlassian account URL, e.g. https://companyname.atlassian.net/
      2. User email address: Enter your email address
      3. API token: Paste your previously copied Atlassian API token
   3. Click the Connect button.
3. 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:

1. Click the switch button to turn Enable status changes sync from Jira to Sifflet on
2. Copy the webhook URL showing up in step 1 of the checklist
3. 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.
   1. Click the gear icon at the top right hand corner of your screen and click System below the Jira settings section
   2. Look for the Advanced section on the left sidebar and click the WebHooks entry
   3. Click the Create a WebHook button
   4. Rename your webhook to reflect the fact that it's used for a Sifflet integration, e.g. "Sifflet integration webhook"
   5. Replace the https://example.com/rest/webhooks/webhook1 in the URL field by paste the URL you previously copied from the Sifflet app
   6. 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.
   7. In the Issue related events section, check the updated checkbox below the Issue 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.
   8. Click the Create button at the bottom of the page.
4. Head back to your Sifflet application
   1. Paste the previously copied secret in the field of step 5 of the checklist
   2. Click the Connect/Save button.
5. 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 or Done 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:

1. Hover the Settings sidebar entry and click the Collaboration Tools entry
2. Go to the Jira section and click the Edit button
3. Add the new value to the User email address field and/or click the Change button below API token field to edit the API token value
4. Click the Connect button
5. If the modification is successful, you see a success message.

Disconnect the Integration

Follow the below steps to disconnect the Jira integration:

1. Hover the Settings sidebar entry and click the Collaboration Tools entry.
2. Go to the Jira section and click the Disconnect button.
3. 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.
4. If the disconnection is successful, the Jira integration card should no longer display the Connected indication and should show the Connect 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:

1. Edit an existing monitor or create a new one
2. Go to the Notification method section of your monitor wizard
3. Toggle the Create incident when monitor fails button
4. Tick the Create Jira issue linked to incident checkbox
5. Select the project you want your issue to be created in
6. Select the type you want your issue to be created with
7. Click the Save button
8. 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:

1. On your incident page, click the Create Jira issue button
2. Select the project you want your issue to be created in
3. Select the type you want your issue to be created with
4. The Summary field is prepopulated with [Sifflet] and the incident name. You can modify this as needed before actually creating the issue.
5. 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 as h3, 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.
6. Click the Create issue button.
7. 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:

1. Click the downward arrow of the button displaying the Jira issue key
2. Click the Unlink Jira issue button
3. 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

Create Issue From Monitor And/Or Incident

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.

My monitor is configured to automatically create Jira issues. The monitor failed, yet no Jira issue was created.

This issue may be due to various factors:

• 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.
• The API token used by your Jira integration might have been revoked.
• The API token used by your Jira integration might have gotten the permissions required to create Jira issue on the configured project and issue removed.
• The configured project and issue type might have been deleted.
• If your monitor's Jira settings were configured using monitors as code, it's worth noting that no validation is done on the configured project and issue type so someone on your team might have inputed inaccurate parameters resulting in broken Jira settings for your monitor.

Status Changes Sync

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 to Enabled
• 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 the Issue 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.

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:

1. Go to the System section of your JIRA SETTINGS
2. Click on the Incoming Mail entry of the MAIL section
3. 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
4. Head to the Settings > Collaboration Tools page of your Sifflet application
5. Add the copied email address to the list of Configured mail addresses in the Mail section of the page
6. Head back to the System section of your JIRA SETTINGS
7. Click the Add incoming mail handler button in the Mail 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.