Jira

Getting started

Set up the Jira configuration

Jira global settings

Global settings for incident ticket

Global settings for follow up action ticket

Optional: Jira webhooks

Testing the 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:

	Incident	Follow Up Action
Global	Yes	Yes
Incident type	Yes	Yes
Slack - Blameless Bot (*)	No	Yes
Microsoft Teams - Blameless Bot (*)	No	No
Web console - Blameless UI (*)	No	Yes

(*) 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.

Set up the Jira integration

1. Launch Blameless.

2. Select "Settings" from the left navigation menu, select 'Integrations" > "Ticketing" > "JIRA".

3. Click on the “Manage” button. The JIRA Global Settings window opens. The window contains the following drop down settings elements:

   1. Global Setting
   2. Global Settings for Incident Ticket
   3. Global Settings for Follow Up Ticket

4. Add the above elements into the respective fields of the JIRA Integration window.

5. Save the updates.

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.

Authentication​

Blameless supports the following two authentication methods with Jira:

• Basic Authentication

• oAuth 1.0

• oAuth 2.0 for Jira Server/Data Center
• oAuth 2.0 for Jira Cloud

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

  • Note: This is not needed for oAuth 2.0 Jira Cloud

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

• oAuth 2.0 Jira Server/Data Center
  • Create an application link - instructions are provided in the Jira Settings Modal
• oAuth 2.0 Jira Cloud
  • No additional configuration

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.

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).

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.

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.

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

3. Create a new application link or update an existing one.

4. Enter the provided consumer key.

5. Enter the provided public RSA key.

6. Enter the provided Callback URL.

7. Specify an Application name and leave theApplication Typevalue as is.

8. Click the "Continue" button. From the list of applications edit the one just created, you will see this prompt:

9. SelectIncoming Authenticationand 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

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

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.

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.

Area	Cause	Message
Private Key	Key incorrect or missing.	"Unable to complete the authorization with Jira, please check your settings and try again."
Consumer Key	Key incorrect or missing.	"Unable to complete the authorization with Jira, please check your settings and try again."
Callback URL	URL was incorrect or left out.	"Unable to complete the authorization with Jira, please check your settings and try again."
Authorization Denial	User clicks the "Deny" button.	"Authorization was denied."
Token Issue during authorization	Token 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 URL	Missing 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.

Jira oAuth 2.0 for Jira Server/Data Center

NOTE: If you have already authenticated Jira using Basic Authentication 
and you are switching to Jira OAuth 2.0 for Jira Server/Data Center, 
please perform the following:
(1) Change Authentication Method to Jira OAuth 2.0 for Jira Cloud
(2) Click Save
(3) Follow the Steps below

1. Follow the instructions to create an Application Link in your Jira Data Center/Server admin console.
   
   • Use the information provided in the UI when creating the application link
2. Enter the Client ID and Client Secret for the Application Link into the settings
3. Click Authorize

Jira oAuth 2.0 for Jira Cloud

NOTE: If you have already authenticated Jira using Basic Authentication 
and you are switching to Jira OAuth 2.0 for Jira Cloud, please perform the following:
(1) Change Authentication Method to Jira OAuth 2.0 for Jira Cloud
(2) Click Save
(3) Follow the Steps below

1. Simply click Authorize and the oAuth 2.0 flow will launch

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.

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.

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

3. 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 list of Supported System Fields that, if marked Required in the Jira project, we can support in the Blameless - Jira integration: 

• assignee

• issuetype

• priority

• project

• summary

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

The following custom fields are also supported:

• Free-form text (string)

• Date/times (date picker)

• Single select option (i.e., radio button, single choice list)

Optional: Jira webhooks​

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".

4. Click on "Create a Webhook".

5. 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.

6. Please select theIssue created,Issue updated, andIssue deletedevents to trigger the webhook callback.

 

Testing the integration​

1. From the Blameless UI, go to "Settings" > "Integrations" > "Ticketing" > "JIRA".

2. Scroll down and select theDefault project key for incident ticketdropdown.

3. If you see the list of projects in the dropdown, the integration was successful.