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 firstname.lastname@example.org.
You can sign up for a free trial of ONEiO from the following link: ONEiO Free Trial
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.
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:
|Send all changes to ONEiO
Paste your ONEiO's endpoint token we created before in Step 1. Be aware we have different URI's for Test and Production environments:
|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
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.
- 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
- Url to JIRA instance.
- Key of the project in JIRA
- Issue type id's you want to integrate
Creating an API token for Atlassian JIRA Cloud authentication
API tokens are available in Atlassian Cloud only. If you're using for example Jira Server, you should use credentials instead.
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.
|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.
|Element to map as target
|The id of the issue
|Project key that the issue belongs to.
|whether the issue is a bug, story, improvement, etc. You can add more issue types from the Issue Types admin screen.
|Summary of the issue.
|the main text field for describing the issue
|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 are short text strings for grouping issues into categories. Similar to Components, except that users can put any arbitrary value in there.
|a date picker for when the issue should be fixed by
|a text field for commenting on an issue
|Values: Highest, High, Medium, Low, Lowest
|a user picker that contains the user that created the issue.
|how the issue was resolved (fixed, duplicate, Won't Fix, etc). You can configure these from the Resolutions admin screen.
|Any custom field
|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.
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
|Apply rule for
|Delay rule processing until Conversation attribute is set
|"source_systems_status" not equals "sf:conversation:previous_source_systems_status"
|Element to map as target
|The id of the issue (recommendation is to use sf:conversation:target_jira_id)
|The name of the transition you want to set. ONEiO will lookup the corresponding transition id and uses it in the REST call.
The newer versions of Jira's API allow setting transition with a normal issue update. In these cases, you can add a transition.name mapping to the update rule.
|Target message type
|Apply rule for
|Delay rule processing until the Conversation attribute is set
|Has one or more attachments
|Element to map as target
|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 .