Skip to main content

JIRA Integration

Getting Started

The Blameless platform integrates with Jira to allow you to automatically:

  • Create a Jira ticket when a Blameless incident is created The Jira ticket can be updated with comments when the incident statuses are changed by configuring a webhook in your Jira instance.
  • Create a Jira ticket when a Blameless follow up action is created
  • Update Blameless incidents and follow up actions state and summary using Blameless webhooks

When a Blameless incident or follow up action is created, the corresponding Jira ticket can be automatically set with a default jira project and default values to required Jira fields when configured in the Jira global settings.

However, the default Jira project and values for required Jira fields can be overwritten at the incident type level. It also can be overwritten at the creation of a follow-up-action via the Blameless web console (UI). The following table summarizes where the default Jira project and values to required Jira fields can be set:

IncidentFollow Up Action
GlobalYesYes
Incident typeYesYes
Slack - Blameless Bot (*)NoYes
Microsoft Teams - Blameless Bot (*)NoNo
Web console - Blameless UI (*)NoYes

(*) At the time of the creation of the Blameless resource (incident or follow up action).

To start using the integration with Jira, you need to configure how you want Blameless to authenticate with Jira, at a minimum.

This section describe how to:

  1. Securely connect Blameless to your Jira Cloud account or your Jira server running on-premise by selecting an authentication method.
  2. Configure your default Jira project and default values for required Jira fields for Blameless incidents.
  3. Configure your default Jira project and default values for required Jira fields for Blameless follow up actions.
  4. Setup your Blameless webhook in Jira.
note

You may only have one ticketing integration enabled at a time.

Setup the JIRA Integration

  1. Launch Blameless.
  2. Select "Settings" from the left navigation menu, select 'Integrations" > "Ticketing" > "JIRA".
JIRA Settings
  1. Click on the “Manage” button. The JIRA Global Settings window opens. The window contains the following drop down settings elements:
  • Global Setting
  • Global Settings for Incident Ticket
  • Global Settings for Follow Up Ticket
JIRA Global Settings
  1. Add the above elements into the respective fields of the JIRA Integration window.
  2. Save the updates.
note

Date fields configured for tickets related to Blameless need to be formatted as "yyyy-mm-dd".

i.e., 2022-11-18

Jira Global Settings

Jira Instance

Before you start, enable the integration with Jira in Blameless by selecting the “Enable Jira” toggle button.

Start configuring your integration with Jira by providing the base URL to your Jira server API endpoint or your Cloud instance (e.g. https://yourname.jira.com)

Jira instance base URL

The URL of your Jira API endpoint.

important

The following is a prerequisite when connecting Blameless to a Jira SERVER deployed in a private network: You will need to obtain a set of Blameless IP addresses related to your own Blameless instance (e.g.: https://your_instance_name.blameless.io), to whitelist if you are using the Jira Server instance or are going through a firewall.

Please contact a member of the Blameless' Customer Success team to obtain these IP addresses. This only applies to a Jira server connection and not to the Jira Cloud.

Authentication

Blameless supports the following two authentication methods with Jira:

  • Basic Authentication
  • OAuth 1.0

First, you must specify the URL of the Jira instance you want to connect Blameless to. It can refer to your Jira Cloud instance (e.g. https::<your_jira_account_name>.atlassian.net) or your Jira server deployed on-premise.

  • Jira Instance URL

Depending on the selected authentication method different field settings must be provided

  • Basic Authentication
    • Jira User Name
    • Jira API token
  • OAuth 1.0
    • RSA private key: generated outside of Blameless
    • consumer_key: Arbitrary string manually created

Basic Authentication

Jira Account User name

This must be the username for the Jira account to be used

Jira Password / API Token

A Password is used with Jira Server (on-premise) A Jira API Token is used with the Jira Cloud -- refer to Creating a Jira API Token.

important

Do not attempt to use an API Token that is generated from any other account than the one used to create the integration, including that of the JIRA Admin.

OAuth 1.0 Authentication

Connecting Blameless to Jira using OAuth 1.0 is a 3-step process as instructed in this section. All parameters must be entered in Blameless first, then Jira. Once added, Blameless automatically provides the user with a direct link to the Integration settings in Jira where they must enter those parameters (step 3).

OAuth in Review Settings
  1. First you will need to generate an RSA Private Key
  2. Enter the generated RSA Private Key and Consumer Keys in Blameless.
  3. Click on the auto-generated link to go to the Integrations settings in your Jira account to add a new application link and enter the Consumer Key, the RSA Private and Public Keys and the auto-generated Consumer Callback URL.

Only once Step 3 is complete, can they then authorize the connection between Blameless and Jira:

  1. Select the checkbox labeled "Check here if you have completed all the steps (This action will also save your settings)".
  2. Click on the "AUTHORIZE JIRA" button.
important

Once the integration in both Blameless and Jira is completed, Blameless will be given the same Jira permissions as the user used to create the Integration in Jira (see Step 3). This Jira user account must be provided with sufficient privileges to see the list of Jira projects and create Jira tickets in those projects.

All Jira interactions on behalf of the Blameless user, will be done by the Jira user that created the application link.

Step 1: Generate the Keys

The first step involves generating the RSA Public and Private Keys. The RSA private key is required for the initial authorization setup and every time Blameless creates Jira tickets.

note

Please contact a member of the Blameless' Customer Success team if you have questions regarding how to generate Keys.

The provided instruction is one example on how to generate your RSA public and private keys using the openssl command on a Unix operating system. However, this is only for guidance as your RSA keys can be provided via any other standard and compliant methods that respects your security policies with regards to the management of public and private keys in your organization. You may contact your security administrator for any assistance with regards to your internal security policies.

Next, copy and paste the RSA public and private key strings contained in each file into their appropriate fields in the Blameless Jira Oauth 1.0 authentication settings:

  • oauth.pem: contains the private RSA key string
  • oauth.pub: contains the public RSA key string

Step 2: Enter the generated keys

From the sections above, gather the following elements to complete this step:

  • RSA Private Key
  • Consumer Key

While the RSA keys are generated and supplied outside of Blameless, you will need to manually create a Consumer key. It is a random string with alphanumeric characters with no space.

Step 3: Configure OAuth in your Jira account

  1. Locate and copy the auto-generated Callback URL which appears in the Step 3 content (bolded URL path).

  2. Click on the following URL to go to your Jira integration settings to create a new application link and enter the above Consumer Key, the public RSA key, and the provided custom Callback URL):

    http: // URL to Jira CONFIG

note

This URL is activated (bold highlight) only if you complete Step 2 (all parameters must be entered).

  1. Create a new application link or update an existing one.
  2. Enter the provided consumer key.
  3. Enter the provided public RSA key.
  4. Enter the provided Callback URL.
  5. Specify an Application name and leave the Application Type value as is.
OAuth in Review Settings
  1. Click the "Continue" button. From the list of applications edit the one just created, you will see this prompt:
OAuth in Review Settings
  1. Select Incoming Authentication and fill everything, at this stage you will need the consumer key to be the same as the one configured in blameless, along with the Public RSA key, and the consumer callback URL
note

Once you save this new application link, you can return to Blameless to complete the configuration and authorize Blameless to connect with Jira using OAuth 1.0.

Authorize the connection

First, click on the checkbox to confirm that you have completed the above step #3. This checkbox is provided to remind you to complete the above manual steps and will save your settings. The checkbox will also not be activated until you complete all steps.

The "Authorize Jira" button becomes active only after you have completed all the above steps:

  • Entered all required fields in steps #2
  • Clicked on the provided URL in step #3
  • Checked the Confirmation checkbox
OAuth in Jira Connection confirmation

If you click "Authorize"

You are redirected to Jira to allow (or Deny) Blameless to create Jira tickets into your Jira account:

  • If the “Allow” button is selected: You will be returned to the Blameless application.
  • If the “Deny” button is selected: Jira will send an error message reporting the authorization steps were not completed.
OAuth in Jira Connection confirmation
note

Instead of "blameless.atlassian.net", the “Welcome to Jira” screen should display the URL to your own Jira instance as designated by the user as part of the setup.

Authentication Errors

The following table contains possible error conditions preventing the authorization process. Generic error messages will point you to these areas within the process.

AreaCauseMessage
Private KeyKey incorrect or missing."Unable to complete the authorization with Jira, please check your settings and try again."
Consumer KeyKey incorrect or missing."Unable to complete the authorization with Jira, please check your settings and try again."
Callback URLURL was incorrect or left out."Unable to complete the authorization with Jira, please check your settings and try again."
Authorization DenialUser clicks the "Deny" button."Authorization was denied."
Token Issue during authorizationToken is not valid"The request token you are trying to authorize is not valid. Please try another token. (Close this dialog, then go back to the site requesting access and tell it to try again.)"
Missing or Wrong URLMissing wrong URL for the Jira instance"Unable to reach your Jira server/account, please check your settings and try again."

Advanced Settings

  1. If using the Connectivity Health Check: Move the slider to the active position.
  2. Enter a polling value (in seconds) to the Interval field
  3. If this is a secured link, enter the Client Side Root certificate and CA Certificates.
  4. Continue to the “Global Settings for Incident Ticket” section.

Global Settings for Incident Ticket

This section of fields provides default values for all Jira tickets created automatically for all Incidents started in Blameless, unless you specified different values in the Incident Type settings. All fields are also required in this section.

Global Settings for incident tickets
  1. Search and select the Jira Project name.

  2. Select a Jira issue type from the following drop down options:

    • Task
    • Story
    • Bug
    • Epic
  3. Select the Blameless field you want to map to the the Jira ticket summary from the following drop down options:

    • Incident ID
    • Incident Name
    • Incident Description
    • Incident Creator
    • Incident Creation Date
    • Incident Status
    • Incident Severity

    Additional required Jira fields may show up further below, depending on the selected JIRA Issue Type.

  4. Select the default value for each required Jira field. These values relate directly to the Project and Type identified in the previous two fields.

Global Settings for Follow Up Action Ticket

These Jira fields provide a set of default values for all Jira Tickets created for all Follow Up Actions created in Blameless. All fields are also required in this section.

GLobal Settings for Follow up Actions
  1. Search and select the Jira Project name.

  2. Select a Jira issue type from the following drop down options:

    • Task
    • Sub-task
    • Story
    • Bug
    • Epic
note

The list of Jira issue types shown here varies depending on the list of issue types you (or Jira administrator) created under the selected Jira project.

  1. Select the default Jira link type you want to establish with the Jira ticket that was created for the corresponding incident (refer to the previous section), from the following drop down options:
  • None (default)

  • Blocks

  • Clones

  • Duplicated

  • Causes

  • Relates to

    These values relate directly to the Project and Type identified in the previous two fields.

Supported Blameless / JIRA fields

The following is a the list of supported fields. If you have a field that is not listed here, it is not supported and Blameless will prevent you from creating the Follow-up Action.

Supported system fields:

  • assignee
  • issuetype
  • priority
  • project
  • Summary

Supported types of custom fields:

  • Free-form text (string)
  • Date/times (date picker)
  • Single select option (i.e., radio button, single choice list)
note

Unsupported fields in the Jira Global settings for Incidents and Follow Up Action are detected and displayed to the user, but cannot be set. Please select a different Jira issue type and/or Jira project which have only supported Jira fields.

Optional: JIRA Webhooks

note

Access to the JIRA Webhook settings requires JIRA Administrator rights.

  1. Go to any JIRA project and click on "Settings".
  2. Click on "System".
  3. Scroll to the bottom of the Settings list and locate the "Advanced" option and select "Webhooks".
JIRA Webhooks
  1. Click on "Create a Webhook".
Create Webhook
  1. Enter a recognizable name for the webhook and copy and paste the resulting JIRA Webhook URL from the Blameless JIRA Integration pane into the JIRA Web hooks "Settings" field.
note

This Details window is only visible to those logged in with JIRA Administrator permissions.

JIRA Webhook SettingsJIRA Webhook URL
  1. Please select the Issue created, Issue updated, and Issue deleted events to trigger the webhook callback.
note

We suggest the following settings.

  1. Leave the “Events” field blank to capture everything.

  2. Select the following issues located just under the "Events" field.

    • Issue Created
    • Issue Updated
    • Issue Deleted

Blameless only tracks those options within the Details window; all other options are ignored.

Testing the Integration

  1. From the Blameless UI, go to "Settings" > "Integrations" > "Ticketing" > "JIRA".
  2. Scroll down and select the Default project key for incident ticket dropdown.
  3. If you see the list of projects in the dropdown, the integration was successful.
JIRA Test