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
-
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:
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
- 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.
| 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. |
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 @yourdomain.com)]" 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 @yourdomain.com)] 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.
SetTransition
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) |
| transition.name | X | The name of the transition you want to set. ONEiO will lookup corresponding transition id and uses it in the REST call. |
Note
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 transition.name mapping to the update rule.
AddAttachment
| 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:
Comments
Please sign in to leave a comment.