Third-Party Applications

🚧

Prerequisites

In order to connect a third-party application, you must have:

  • an account with the third-party application
  • knowledge about the authentication mechanism, headers, endpoints, and parameters

👍

Communications with third-party applications are based on REST principles and follow the RFC2119 guidelines.

Call from Quable PIM

Quable PIM uses the information you entered when creating the third-party 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 button for the third-party application, an API call is made to the Quable PIM API. The Quable API will perform a callback to the URL provided in the connection with the requested parameters and wait for a specific answer (see below).

This answer should include a URL that will be loaded in the window 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 Third-Party 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) in the operation of the Third-Party Application:

"notificationCallback.url"
"notificationCallback.token"
"notificationCallback.method"

Response to Quable

The third-party 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 third-party 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 third-party application will manage its content.