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
URL

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

Requirements

  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 https://id.atlassian.com/manage/api-tokens
  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 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 if the transition.

 

 

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

Comments

0 comments

Please sign in to leave a comment.