Jira

Jira issues can be automatically created in case of a 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.

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.

Set up the Integration

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.
   • Go to your Jira application and head to PERSONAL SETTING > Atlassian Account Settings.
   • Go to the Security tab.
   • In the API tokens section, click the Create and manage API tokens.
   • Click Create API token.
   • Give a label to your API token, for instance Sifflet integration and click the Create button.
   • Click the Copy button.
2. Go to your Sifflet application, hover the Settings sidebar entry and click the Collaboration Tools entry.
3. Go to the Jira section and click the Connect to Jira button.
4. Fill in the below fields:
   • Jira domain: Enter your company's Jira domain (e.g., siffletdata.atlassian.net).
   • User email address: Enter your email address.
   • API token: Paste your previously copied Atlassian API token.
5. Click the Connect button.
6. 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.

Creating Jira Templates

With your Jira integration configured, you can use issue templates to customize the Jira issues created by Sifflet. Templates let you specify the values for various issue fields, ensuring each issue has the required context.

To create a new Jira template:

1. In Sifflet, go to Settings > Collaboration Tools and click on the Jira section.
2. Click on the New issue template button.
3. You will be prompted to provide the following:
   • Template Name: A descriptive name for your template.
   • Project: The Jira project where the issue will be created.
   • Issue Type: The type of issue to create (e.g., Bug, Task, Story).
4. After you select a Project and Issue Type, Sifflet will load all the available fields for that combination. You can then specify the values for the fields you want to include in the template.

   📘

   Configuring Custom Fields

   When you're setting up your templates, it's important to know that Jira's API expects different value formats for different custom fields. Here are some guidelines to help you:

   • Fields referencing Jira entities (e.g., Assignee, Reporter, Priority): These fields expect an object with an id or key. For example: {"id": "user-id"} or {"id": "priority-id"}.
   • Multi-select or label-type fields: These expect an array of strings or objects, depending on the field's configuration. For example: ["label-1", "label-2"] or [{"value": "option-1"}, {"value": "option-2"}].
   • Simple text fields (e.g., App link): These typically accept plain strings.
   • Rich text / multiline fields (e.g., Description, Environment, Comment): These require input in Atlassian Document Format (ADF). Sifflet handles the Description field for you, but if you want to use another rich text custom field, you'll need to provide the value in ADF. Here is a minimal example:

   JSON

   {
     "type": "doc",
     "version": 1,
     "content": [
       {
         "type": "paragraph",
         "content": [
           {
             "type": "text",
             "text": "This is a sample description"
           }
         ]
       }
     ]
   }
   

   For more details, you can refer to the Jira API documentation.

   To find the ID of a custom field, you can follow the instructions in this guide.

5. Once you've configured the fields, you can click the Send test issue button to create a dummy issue in Jira and verify your configuration.
6. Click Create to save your template.

Create Jira Issue From Monitor

To create a Jira issue from a monitor:

1. When creating or editing a monitor, go to the Notification method section.
2. Toggle the "Create incident when monitor fails" button.
3. Tick the "Create Jira issue linked to incident" checkbox.
4. Choose the template you want to use.
5. Save the monitor.

Now, when this monitor fails, a Jira issue will be created automatically using the template you selected. 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 issue template you want to use.
3. 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.

📘

Unlinking issues

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.

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. In your Jira project settings, navigate to Webhooks and create a new webhook. (More details are available in the dedicated documentation page.)
4. Paste the webhook URL and select the issue events you want to be notified about (e.g., issue_updated).
5. Head back to your Sifflet application. Paste the previously copied secret in the field of step 5 of the checklist. Click the Save button.
6. 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.

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. To resolve this, add the missing required fields to the Jira issue template you're trying to use in Sifflet.

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.