Here's how to set up a Jira endpoint in ONEiO in a short video.
Endpoint Setup Details
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
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.
Configure the JIRA webhook as shown in table:
|Name||Case specific.||Send all changes to ONEiO|
|JQL||Possibly limit webhook by project and issue type. Leave more complex logic to ONEiO mappings.||
|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
- 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
- Url to JIRA instance.
- Key of the project in JIRA
- Issue type id's you want integrate
- 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:
- Login with your integration user to your Jira
- Navigate to https://id.atlassian.com/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 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.
Element to map as target
|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.|