Purpose of the incoming REST calls section it takes care of the mapping of the data from external systems to JIRA.

It is not always possible or feasible for the other system to talk to JIRA using the native JIRA REST API.

In these cases there is a need for a translation and action based on the format that the external system sends, here is were iHUB shines!

With iHUB incoming three steps process 1. Send to ihub → 2. iHUB routes in data to action → 3. action updates issues , external systems will be able to create/update JIRA data.

There is a powerful rule engine that can be used to route the incoming request to the correct action.

The action then takes the input from the incoming REST call and sends that to JIRA in the format JIRA expects.

1 Three-step process
2 1. Send to ihub
3 Authentication
- 3.1 Behind firewall
4 Response from Incoming REST end-point
- 4.1 Standard response:
- 4.2 Echoed Response:
- 4.3 Action Response:
  - 4.3.1 Incoming Rule With Action Response
5 Incoming requests with files (multipart data)
- 5.1 Using incoming files in iHub actions

Three-step process

1. Send to ihub

The external system POST data to iHUBs URL, which is stated in on the Incoming page.

URL ends with /rest/restfulintegrator/1.0/incoming

2. iHUB routes in data to action

iHUB rule engine is where new rules are created. Simply press New Rule button.

And specify what conditions need to be fulfilled for the rule to pass the data to an iHUB action.

Conditions	Description

Conditions

Description

User

Execute of the user is equal or not equal to the specified user

Data

Use JSON Path - Pick data from response expression to check if the payload includes valid data before executing.

URL

add any query param to the POST iHUB URL, such as

/rest/restfulintegrator/1.0/incoming/servicenow
/rest/restfulintegrator/1.0/incoming/github
/rest/restfulintegrator/1.0/incoming/mysystem

To distinguish between systems.

On the Action, part select the iHUB action that will be triggered if the condition is true.

3. action updates issues

The last part is executing the action, this is done in the same manner as all other actions.

The Payload from the external system is available as variables to use in the action.

Checkout Chained actions and JSON Path for more details.

Authentication

Use the JIRA basic auth or OAuth to access the incoming URL from an external system.

Behind firewall

There is no need to open up the full JIRA to the whole world.

Instead of open a single entry in the firewall that allows only communication to a specific URL, since iHUB supports custom URLs we recommend to use a UUID to make it even more secure.

Here is an example.

On your Firewall open up <baseurl>/rest/restfulintegrator/1.0/incoming/014aed18-c4d2-4166-9745-39648cce64e9 (we have used https://www.uuidgenerator.net/ to generate the UUID)

Then on iHUB Incoming rule use this as a URL Condition which says

Operand ~ (contains)
Value 014aed18-c4d2-4166-9745-39648cce64e9

Response from Incoming REST end-point

Standard response:

Standard response is always: HTTP 200 OK

This response is recommended in production envs.

Echoed Response:

From the Incoming Settings page, it's possible to enable debug response mode.

Select the "Respond with POST data and triggered action(s) to "ON" to enable debug mode.

The response will then echo the post body, URL, and triggered integrations. This is recommended for dev mode when setting things up.

Action Response:

A rule can be configured to "wait" for its triggered action and return the action response.

This is setup from the Rule. Open Incoming, select to edit a rule and under the section Rule HTTP Response select:

Triggered Action(s) Response

This rule will now wait for its action to complete before returning a response. By default, due to backward compatibility, the response is returned as a single object (if the request matches one rule) , if more rules are triggered in the same request an array of responses will be returned. If you wish to always return an array of objects (one or more) this can be set up under the “Settings” menu.

Make sure this is set to On.

Response Rule 2. Always return response as an array, response rule 1 needs to be disabled to make this apply.

Note: Debug must be switched off

Sample of response:

Incoming Rule With Action Response

[
    {
  "actionId": 1,
  "actionName": "Create Issue" ,
  "httpStatusCode": 201 ,
  "responseData": {
    "id": "10000",
    "key": "SEAG-1",
    "self": "http://localhost:2990/jira/rest/api/2/issue/10000"
  },
  "requestData": {
     …omitted..
  }
}
]

More info on Http Rule Response

Incoming requests with files (multipart data)

iHub supports incoming files. This is very useful for cases where you do not want to open up Jira for the world to use the JIRA rest API to add attachments.

URL for incoming files is: rest/restfulintegrator/1.0/incoming/files

This can, of course, be combined with a UUID to secure firewall openings ie: rest/restfulintegrator/1.0/incoming/files/014aed18-c4d2-4166-9745-39648cce64e9

From Jira 10 you must add the header to the request to the incoming URL.

X-Atlassian-Token with the value no-check

For instance if we are using postman then to post to iHub then this header needs to be added.

Error you get if this is not included is XSRF check failed

Using incoming files in iHub actions

Using the incoming files in an action is simple, just enable "Incoming files" under the Attachments sections in the "Actions" page.

The integration action request will now be sent as a multipart/form-data request with the incoming files in the request.

Integration Hub for JIRA

Incoming REST Calls