How to configure Atlassian JIRA for integration with ONEiO

Introduction

This document shows an example of what needs to be done in Atlassian JIRA to make it integration-ready with the endpoint in your ONEiO. Note also, that the number of fields used in integrations might vary. 

In case you have questions related to setting up the integration, send a mail to support@oneio.cloud.

You can sign up for a free trial of ONEiO from the following link: ONEiO Free Trial

Overview

This article gives an overview of the required steps to integrate ONEiO and Atlassian JIRA. In this guide, we cover the following steps required for bi-directional communication between ONEiO and Atlassian JIRA.

1. Creating your JIRA endpoint
2. Creating a Webhook in JIRA
3. Testing inbound messages
4. Creating an API token for JIRA Cloud authentication
5. Inbound Whitelist Filter
6. System fields in JIRA
7. Actions towards JIRA with different Message Types
8. JIRA Cloud vs On-Prem JIRA

 

Endpoint Setup

Access your ONEiO subscription, go to Endpoints, and select New endpoint

Choose the Jira endpoint and click on Create

Fill in the following fields on the General info tab: Name, URL of JIRA instance, and Resolving Values. In case you already created an API token, add the integration user and the API token to their corresponding fields. If not, we can add it later. Click on Save Changes

You can find your entities resolving values by accessing Settings -> Issues -> Issue types in your Jira Instance. When editing any of them, the issue type id is part of the URI. Example:

You can also obtain the issue id and other detailed data by making a request to an existent Incident/issue through Postman.

Just configure a request (get) to the existing incident/issue number, and look for "issuetype" in the response. It will return among other data, the issuetype name and id.

 

Sending messages from JIRA to ONEiO

ONEiO accesses JIRA by using the JIRA REST API.

For a tool to send messages to ONEiO, the tool must have access to ONEiO's IP addresses. Communication is only allowed over HTTPS and the endpoint must have a valid trusted certificate in use.

JIRA sends messages using 'webhooks'. These messages are authenticated using a unique identifier Token which ONEiO provides. 

JIRA Webhooks don't support BASIC authentication, Token based authentication is used instead. ONEiO will provide the authentication token.

 

Creating a Webhook in JIRA

First, let's generate a ONEiO's endpoint token for using it later on Jira's webhook configuration. In your ONEiO's subscription, go to Endpoints and edit your JIRA endpoint. In the General Info tab, click on Generate new token button, then click on generate, and lastly, click on Copy Complete Webhook URL in Jira to clipboard. We will use this token in the next steps.

In your Jira instance, go to Settings -> System

Then go to WebHooks and click on Create a Webhook

Now, configure your webhook. Add the webhook's name, URL, the JQL, and all the events you want this webhook listening to:

 

Field	Value	Example
Name	Case specific.	Send all changes to ONEiO
Status	Enabled	Enabled
URL	Paste your ONEiO's endpoint token we created before in Step 1. Be aware we have different URI's for Test and Production environments:  Test: https://rest-receiver-test.service-flow.com/api?issue.key=${issue.key}&project.key=${project.key}&auth_token=[CUSTOMER_SPECIFIC_TOKEN] Production: https://rest-receiver.service-flow.com/api?issue.key=${issue.key}&project.key=${project.key}&auth_token=[CUSTOMER_SPECIFIC_TOKEN]	https://rest-receiver.service-flow.com/api?auth_token=foobarxxx
JQL	Possibly limit webhook by project and issue type. Leave more complex logic to ONEiO mappings.	project = "SMP" and issuetype = "[System] Incident"
Issue related events	Check all relevant events. Only Issue related events can currently be handled in ONEiO	Issue: created, updated Comment: created, updated Attachment: created

Testing inbound messages

From this point, you can test the integration from Jira to ONEiO by simply creating a new issue in your JIRA instance and checking the ONEiO message feed.

The new issue should be visible in the message feed. Clicking on the issue will show the details of the received attributes.

 

Sending messages from ONEiO to JIRA

For ONEiO to send messages to the integrated tool, the tool's interface must be reachable from ONEiO's IP addresses. The preferred communication way is HTTPS with a trusted valid certificate. In the test environment, self-signed certificates and HTTP can be used as well.

See also Securely connecting ITSM tool with ONEiO to get guidance on how to create a secure connection.

Requirements

1. JIRA user with privileges to create and edit issues. If JIRA Service Desk is used, the user needs to be an agent.
   • Username and password/API token for the JIRA user
2. Url to JIRA instance.
3. Key of the project in JIRA
4. Issue type id's you want to integrate

Creating an API token for Atlassian JIRA Cloud authentication

When using REST API to integrate Jira Cloud, API token needs to be used for authentication. In ONEiO, API token is inserted as the password in the endpoint configuration. No other changes are needed.

 

How to create an API token:

Create an API token from the integration user's Atlassian account:

You can navigate to https://id.atlassian.com/manage/api-tokens or access it through the menus. If you navigate directly to the mentioned URL, jump to Step 4.

Step1: Login with your integration user to your Jira

Step2: Click on your account/profile icon and select "manage account"

Step3: Select Security, Create and manage API tokens

Click Create API token.

From the dialog that appears, enter a memorable and concise Label for your token and click Create. The label works as the name of your API token.

Click Copy to clipboard, then go to your ONEiO's endpoint settings, and paste the token to the outbound user's password field in ONEiO Endpoint configuration. Store your token securely, like any password!

More details from Atlassian Cloud Support.

 

Inbound Whitelist Filter

We recommend adding your JIRA's integration user to the inbound whitelist filter, in order to avoid recreating the Issue in the connected endpoint (message 'echo').

Edit your endpoint and at the "JIRA -> ONEiO" section, find Inbound Whitelist Filter.

Swap all occurrences of [YOUR JIRA INTEGRATION USER ID] for your integration user id. 

Field	Value	Example
Inbound Whitelist Filter	user.accountId!=[YOUR JIRA INTEGRATION USER ID],comment.author.accountId!=[YOUR JIRA INTEGRATION USER ID],attachment.author.accountId!=[YOUR JIRA INTEGRATION USER ID]	user.accountId!=1234567890, comment.author.accountId!=1234567890, attachment.author.accountId!=1234567890

 

This way, any messages arriving from the integration user will be ignored. You can add more values to the Inbound Whitelist Filter, just add the values separated by a comma (,). See more in our article Endpoint Type Configuration Guide - Atlassian Jira 

Look for [YOUR JIRA INTEGRATION USER ID] and swap it for your JIRA's integration user id

You can find your integration user id by going to your Jira Instance, then Settings -> User management. Click on the user you are using as an integration user and copy the id from URI

 

System fields in JIRA

Below you can find a list of common system fields available in a default JIRA installation. Please feel free to add any missing ones.

Display name	Element to map as target	Mandatory	Description
Issue ID	key	(in update)	The id of the issue
Project	fields.project.key	x	Project key that the issue belongs to.
Issue Type	fields.issuetype.id	x	whether the issue is a bug, story, improvement, etc. You can add more issue types from the Issue Types admin screen.
Summary	fields.summary	(in create)	Summary of the issue.
Description	fields.description		the main text field for describing the issue
Component/s	fields.components.name		a component picker, which references Project Components that you create on the project admin screen. (e.g. UI, Database). Components can have a person who is the Component Lead, who gets auto-assigned any issues with that component set.
Labels	fields.labels		labels are short text strings for grouping issues into categories. Similar to Components, except that users can put any arbitrary value in there.
Due Date	fields.duedate		a date picker for when the issue should be fixed by
Comment	update.comment.add.body		a text field for commenting on an issue
Priority	fields.priority.name		Values: Highest, High, Medium, Low, Lowest
Reporter	fields.reporter		a user picker that contains the user that created the issue.
Resolution	fields.resolution		how the issue was resolved (fixed, duplicate, Won't Fix, etc). You can configure these from the Resolutions admin screen.
Custom fields	fields.customfield_12345		Any custom field
Transition	transition.key		Used with SetTransition message type. Value to be used is the id of the transition.

 

Actions towards JIRA with different Message Types

JIRA's REST API has different functions for different actions. As an example, attachments and transitions need to be set with an additional message. For that, ONEiO provided ready-made messages for you to fulfill these needs. Here are a few examples of the available messages.

SetTransition

To set a new status in JIRA, you need to set a transition. For this, you need a rule that is triggered when you want the transition to be set. Note, that there might be a need to store the earlier state to a conversation attribute to determine when this rule should be matched. See also How to handle JIRA Statuses With Transitions

Target message type	SetTransition
Apply rule for	All messages
Delay rule processing until Conversation attribute is set	sf:conversation:target_jira_id
Typical condition	"source_systems_status" not equals "sf:conversation:previous_source_systems_status"

 

Element to map as target	Mandatory	Description
transition.key	X	The id of the issue (recommendation is to use sf:conversation:target_jira_id)
transition.name	X	The name of the transition you want to set. ONEiO will lookup the corresponding transition id and uses it in the REST call.

 

AddAttachment

Target message type	AddAttachment
IterateBy	each attachment
Apply rule for	All messages
Delay rule processing until the Conversation attribute is set	sf:conversation:target_jira_id
Attribute Condition	Has one or more attachments

 

Element to map as target	Mandatory	Description
key	X	The id of the issue (recommendation is to uses sf:conversation:target_jira_id)

 

JIRA Cloud vs On-Prem JIRA

Generally, there is no difference in setting up Cloud or On-Prem JIRA. The internal steps are the same there are just a couple of prerequisites regarding connecting to JIRA from the internet.

Make sure your installation server is reachable through your f.ex Firewall or any other security installation you have in your network. All information regarding the IPs and Ports ONEiO is using can be found in this article: Production & QA IP addresses and ports .