Start integrating with ONEiO for free!

How to configure Atlassian JIRA for integration with ONEiO


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

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.

  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

Paste your ONEiO's endpoint token we created before in Step 1. Be aware we have different URI's for Test and Production environments: 



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.


  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


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 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],!=[YOUR JIRA INTEGRATION USER ID],!=[YOUR JIRA INTEGRATION USER ID] user.accountId!=1234567890,!=1234567890,!=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 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   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   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.


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) X 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 mapping to the update rule.



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 .



Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request



Please sign in to leave a comment.