1. Help Center
  2. Guides
  3. Endpoint Types
Start integrating with ONEiO for free!
SIGN UP

Endpoint Type Configuration Guide - Atlassian Jira

Avatar
Janne Kärkkäinen

Endpoint details

In this document, you will find detailed info about Atlassian Jira Endpoint Type. This Endpoint Type is a Self-Service type, so users can add them without the need to reach out to ONEiO Support. 

Endpoint_Type_Configuration_Guide_-_Atlassian_Jira_-_1.jpeg

  

General
Status Sets the status of the endpoint. Active / Suspended.
When an endpoint is suspended, it will continue to receive messages but won't process them. Instead, the messages will be temporarily stored in a queue and processed later once the endpoint status changes back to Active. It's important to note that during suspension, the endpoint will not send out any messages.
URL The base address of your Jira Instance. You can test the HTTP connection by clicking Test Connection button. Note that this function does not test the authentication, it tests only if ONEiO can reach the endpoint.
Name Name of the endpoint. It is recommended to use short names since this name is used in displays throughout ONEiO.
Datetime pattern Date time pattern ONEiO uses to read DateTime fields and how ONEiO sends out DateTime fields. Shown only for reference.

 

[YourJira] -> ONEiO
Webhook details
Webhook target address

Target address to insert to your Jira's webhook configuration.

The targets are different when operating in QA or Production.

  • QA -> 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]
Inbound authentication

In edit mode, you can reset and retrieve a new authentication token. Replace [CUSTOMER_SPECIFIC_TOKEN] for this new token in the Webhook target address
Inbound Whitelist Filter

With this property, you can define conditions to ignore messages arriving from your Jira instance to ONEiO.
This is typically used to filter out messages that are triggered by ONEiO, since there is no way to filter those out in Jira's Webhook configuration. Another typical use-case is to allow only messages for a certain project since Jira has limitations to filtering against project values as well. 

You can have one or more conditions. The different conditions are separated with comma (,). The logical operator between conditions is always "AND". Supported operations in a single condition are:

  • = (or ==) for EQUALS
  • != for NOT EQUALS
  • IN which evaluates to true if any of the values in the list are equal to the value compared to.

Example 1 (Only allow messages from a certain project and filter out messages that were triggered because of messages from ONEiO into Jira. Replace <ACCOUNT_ID> with the integration user's accountId and <PROJECT_KEY> with project key):

user.accountId!=<ACCOUNT_ID>,comment.author.accountId!=<ACCOUNT_ID>,attachment.author.accountId!=<ACCOUNT_ID>,sf:request:param:project.key=<PROJECT_KEY>

Example 2 (Showcasing different operators): attr_1=foo,attr_2==${param:project.key},attr_3!=${username},attr_4 IN (bar1, bar2, bar3)
Entity Type Resolving ONEiO needs to resolve the Entity Type from the inbound message. This configuration describes from what information it is done. 
Resolving Path The field in the inbound message where we can identify the entity
Resolving Values Value matched is resolved to Entity Type.
Fallback Entity Type If no value is matched, the inbound message is resolved as the Entity Type defined here.

 

ONEiO -> [YourJira]
Integration user in Jira

JIRA user with privileges to create and edit issues. This user is included in all calls made from ONEiO to Jira's API, including updates and lookups. 
Password (API Token) The password or API token to the integration user. Jira Cloud always requires API token, but some older on-prem Jiras might still use the password of the user.
Unrecoverable HTTP error codes List of numeric HTTP response codes that are to be handled as non-recoverable when sending messages to Jira's API. If ONEiO receives an error code that is not on the list, it will retry the message automatically. If ONEiO receives an error code that IS on this list, the message will result in an error.

 

Entity types

Jira endpoint comes with two default entity types; Incident and Service Request. The entity type on ONEiO is equivalent to Jira's Issue Type. There is no need to use these ones, but you can use them as examples in case you wish to use some other Entity Types.

You can add new Entity Types freely. Remember to include the new Entity Type in the Resolving table (Entity Type Resolving section in the General Info tab).

 

Common HTTP error codes

Jira response errors usually return enough information about the error encountered.

The error can be returned as plain text or as a JSON. Examples:

401 - Unauthorized

Basic authentication with passwords is deprecated. 
For more information, see: https://developer.atlassian.com/cloud/confluence/deprecation-notice-basic-auth/

404 - The issue doesn't exist

{
    "errorMessages": [
        "Issue does not exist or you do not have permission to see it."
    ],
    "errors": {}
},

400 - Missing project id/key

{"errorMessages":[],"errors":{"project":"Specify a valid project ID or key"}}

 

Error problem
401

 Authentication credentials are incorrect or missing.
403

Usually related to user's permission issues
404 Issue (incident) is not found or the user does not have permission to view it.
400

Returned when there is missing data in the payload, for instance:

  • request body is missing
  • one or more required fields are missing or have the incorrect format
  • one or more fields cannot be set for the issue type.
  • a user does not have the necessary permission to change certain data
  • the request includes an invalid transition
  • subtype or subtasks issues
  • invalid payload
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.

Articles in this section

See more