Incoming REST Calls
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.
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 |
|---|---|
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
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 https://rixter.atlassian.net/wiki/spaces/RIFJ/pages/1491075076
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
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.