 |
|
Call from Quable PIM
Quable PIM uses the information you entered when creating the QuableApp connection to "talk" to the third-party API. The conversation has two parts: the call with information being sent and instructions for a response.
How it works
When a user clicks on the QuableApp button, an API call is made to the Quable API. The Quable API will perform a callback to the URL provided in the QuableApp settings with the requested parameters and wait for a specific answer (see below).
This answer should include a URL that will be loaded in the screen displayed to the user. If the answer does not include a URL, a message will be displayed.
Calling the URI
The Quable PIM API makes a POST call to the third-party API's Resource URI:
curl --request POST \
--url http://thirdpartyapp.theirdomain.com/appservice
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
Here's a breakdown:
| Description | |
|---|---|
| Request | HTTP verb / method to announce that information is being sent and to create a resource in the API:POST |
| URL | The address of the API resource: "{{http}}://thirdpartyapp.theirdomain.com/appservice" |
| Headers | Identifies the coding language of the information being sent to let the API know what to expect: "Accept: application/json" "Content-Type: application/json" |
Next, comes the body of the conversation, the data. It includes the information to process and callback instructions for the API:
"data": {
"quableInstanceName": "my-instance",
"userName": "johnDoe",
"userEmail": "[email protected]",
"userId": 153,
"sourceAction": "document_page",
"documentIds": [
"001234",
"A23979"
],
"notificationCallback": {
"url": "http://{{YOUR-PIM}}.quable.com/myservice",
"token": "abc1defgh23ijkl4mnopq56urstuv78wxyz9",
"method": "POST"
}
}
The data contains two parts: Identity/Processing information and Callback instructions.
Here's a breakdown of both:
| Data Parts | Description |
|---|---|
| Identity | Information identifying Quable PIM and the user requesting access to the application: "quableInstanceName" "userName" "userId" "userEmail" |
| Processing information | Information on the type of content to be processed: "sourceAction" "documentIds" |
| Callback instructions | The URL of the Quable API to call at the end of processing in order to send a notification to the user (if desired) : "notificationCallback.url" "notificationCallback.token" "notificationCallback.method" |
Response to Quable
The external application receives a call from the Quable API with the information given in the connection and the data about the user and the objects to be processed.
In order for the PIM to offer the content of the external application to the user, the latter must respond with an HTTP 200 code and a request body as below.
- Success -
200:
{
"url": "https://{{YOUR-APP}}.domain.tld/my-app-form",
"err": 0,
}
Any response other than an HTTP 200 code and a body containing the value "0" for the "err" attribute will be considered an error and indicated as such to the user.
Content Management
If all conditions are met, the URL provided in the request body will be called in the window and the external application will manage its content.