Start integrating with ONEiO for free!

How to configure Atlassian JIRA for integration with ONEiO

Endpoint Setup

Here's how to set up a Jira endpoint in ONEiO in a short video.

Endpoint Setup Details

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

Inbound from Jira to ONEiO

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.

Sending from JIRA to ONEiO

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

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

  3. Configure the JIRA webhook as shown in table:

Webhook configuration

Field Value Example
Name Case specific. Send all changes to ONEiO


Exclude details off  
JQL Possibly limit webhook by project and issue type. Leave more complex logic to ONEiO mappings. project = "PROJECT1" AND issuetype = Incident
Events Check all relevant events. Only Issue related events can currently be handled in ONEiO Issue: created, updated

There is no need to add post function triggers to the workflow.

Outbound from ONEiO to Jira

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

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

Sending from ONEiO to JIRA


  1. JIRA user with privileges to create and edit issues. If JIRA Service Desk is used, 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 integrate
  5. Any date fields integrated

How to create an API token for Atlassian JIRA Cloud authentication

Note: 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. Earlier username & password was allowed, but this has been changed lately. In ONEiO, api token is inserted as the password in endpoint configuration. No other changes are needed.

How to create an API token:

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

  1. Login with your integration user to your Jira
  2. Navigate to
  3. Click Create API token.
  4. 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.
  5. Click Copy to clipboard, then paste the token to outbound user's password field in ONEiO Endpoint configuration.

Store your token securely, like any password!

More details from Atlassian Cloud Support.

System fields in JIRA

List of system fields available in default JIRA installation.  List taken from Atlassian Q&A article. NOTE: List may not include all fields. 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 if the transition.


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, swap the Inbound Whitelist Filter from "[YOUR JIRA LOCAL USERNAME (username without]" to your integration user id (or other user identification param received from the payload, like user_name).


Look for [YOUR JIRA LOCAL USERNAME (username without] and swap it for your JIRA's integration user


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 fulfil 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 Handling 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 uses sf:conversation:target_jira_id) X The name of the transition you want to set. ONEiO will lookup corresponding transition id and uses it in the REST call.


In the newer versions of Jira's API, it is possible to set transition in 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 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.