Quick Links
Two-way Communication with Provet Cloud
Introduction
Custom integrations are a feature in Provet Cloud that allows sending requests to external resources from inside Provet Cloud. To get access to the features, please contact Provet Cloud support.
Management
Custom integrations are managed in Settings → Integrations → Custom integrations.
To add an integration, use the blue '+Add' button; use the white pen button on the table row to edit an integration.
Settings
- Name - Specifies the label on the button visible in the user interface.
- Visible page - Specifies on which page the button is visible. Each custom integration can only be visible on one page, but the same configuration can be duplicated to multiple custom integrations.
- Action - Specifies which action will be taken when the button is clicked.
- Send HTTP request - A request is scheduled in the background and sent using Provet Cloud's servers. Users will not see the webpage but may see a notification when the sending progresses. The request will come from Provet Cloud's outgoing IP addresses, so the receiving end must be open for outside requests.
- Open in new window - The target URL is opened in a new window/browser tab.
- Open in side panel - The target URL is embedded in Provet Cloud by opening a side panel on top of the page content and displaying the page as an iframe. The target URL must support embedding (as in, the
X-Frame-Optionsheader must be set correctly).
- HTTP method - Specifies whether the request will be sent as a GET request, with the payload being supplied as parameters in the query string, or as a POST request, with the payload being supplied as form data.
- URL - The target URL, complete with schema.
- Parameter name - Name of the parameter used when supplying the current object's ID.
- Enabled - Allows enabling and disabling a custom integration. Custom integrations can also be deleted if they are no longer needed.
- Add verification hash - Enables a verification hash in the payload that can be used to verify that the request is coming from the custom integration.
- Verification salt - A shared secret that is used to calculate the verification hash, only required when verification hash is enabled.
Prefixing Parameter Value
It is possible to add a custom prefix to the parameter value by specifying the parameter name differently. Normally specifying the parameter name as 'id' would result in a request like https://example.com/?id=1. However, if a custom prefix is required in front of the actual ID value, the parameter name could be defined, for example, as 'id=client_", which will send a request https://example.com/?id=client_1.
Headers
Background requests ('Send HTTP request') can also be given arbitrary, static values that will be added to the requests whenever they are sent. This can, for example, be used to include Authorisation headers in requests.
This feature is not implemented for foreground requests ('Open in a new window', 'Open in side panel'). Sent headers are also not logged.
Payload Information
The settings view will display a list of payload keys and values that will be sent with the request, either as query string parameters (GET) or form data (POST). This list will update as the settings are modified.
Log
Requests sent in the background ('Send HTTP request') will be recorded in an internal log for verification and auditing purposes. This allows administrators to check what kind of requests were sent by who and at what time and inspect the kind of response the custom integration sent back.
The custom integration log can be viewed from Settings → Integrations → Custom integrations → Log.
The log view will list all made requests, beginning with the latest request. Basic information about the requests will be shown in the list, and more information can be accessed in the detail view by clicking on the eye button on the right-hand side of each row.
Logging is not performed on foreground requests ('Open in a new window', 'Open in side panel'), as the browser is in charge of making these requests.
Usage
Once added, custom integrations will be rendered as buttons on their target pages. Custom integration buttons can easily be told apart from Provet Cloud's buttons by their unique brown appearance.
If only one custom integration is set up for a page, it will be rendered as a regular button, with the custom integration name used as its label. See the brown 'Trigger custom integration' button on the image below (client page).
If a page has multiple custom integrations attached to it, the custom integrations will instead be rendered as a dropdown menu, again using the same brown appearance to tell it apart. The menu entries will use the custom integration name as its label, just like the singular buttons. See the image below for an illustration.
Custom integrations do not send detailed information about the currently visible page. Instead, they only send the relevant object ID (client ID, patient ID, invoice ID, etc.) that can be queried from the Provet Cloud REST API, similar to how webhooks work.
Custom integrations do not automatically include information on what page they are registered to. Users should either use different URL endpoints for different pages (for example integration.com/client/ for client page custom integration and integration.com/patient/ for patient page custom integration), or if that is not possible, different parameter names (for example patient_id for patient page integration and client_id for client page integration if both use the same URL) and then distinguish on the integration-side by which parameter is included in the request. For background requests, custom headers can also be used.
There is also no reference to the active Provet ID. If you are building an integration shared between multiple Provet Cloud instances, it is recommended to add endpoints for each Provet ID (for example integration.com/1234/client/ and integration.com/4321/client/ if the integration will be used by both Provet Cloud instances 1234 and 4321). In this case, it's also recommended to use verification hashes to ensure that data is coming from the correct instance, even if there is a misconfiguration with a custom integration URL. For background requests, custom headers can also be used.
Different Actions
Send HTTP Request
If a custom integration is defined as a 'Send HTTP request' action, clicking on the custom integration button will schedule a request to be sent in the background using Provet Cloud's worker servers. The sending will happen asynchronously, and while usually the request is made pretty much immediately, there may be a delay depending on the amount of work currently on the servers. The request will originate from Provet Cloud's outgoing IP addresses.
When the request is being scheduled, the user will see an information notification at the top of the page.
If the request gets handled and completed without the user navigating away from the page, they can be shown an additional notification upon completing the task.
A success notification is shown if the request is sent successfully and the integration responds with a successful HTTP status code (between 200 and 299 inclusive).
However, if the request fails for whatever reason, a red error notification saying 'Integration request failed' will be shown, with a more specific error message in the parenthesis.
Possible error messages at the moment are:
- Backend error - An unknown error occurred on Provet Cloud's worker servers when the request was being sent. This may be an error in Provet Cloud's servers. Contact Provet Cloud support for additional information.
- Connection error - The request to schedule the sending made to Provet Cloud's servers did not go through. This may be an error with the user's connection or perhaps an issue with Provet Cloud's servers.
- Data error - The request to schedule the sending made to Provet Cloud's servers contained invalid data. This suggests a problem in Provet Cloud.
- Integration error - The request was sent successfully, but the integration responded with a non-successful HTTP status code (lower than 200 or higher than 299). The custom integration log may be used to determine the reason if the failure is unexpected.
Open In a New Window
If a custom integration is defined as an 'Open in new window' action, clicking on the custom integration button will open the target URL in a new window, or more commonly with modern browsers, in a new tab. The original Provet Cloud page will remain open in its original window/tab.
If a GET request method is used, users can see the payload information displayed in the browser's address bar. If users should not easily see the payload information transmitted, consider using a POST request instead.
Open In Side Panel
If a custom integration is defined as an 'Open in side panel' action, clicking on the custom integration button fetches the target URL inside the browser and displays it inside an iframe element within a side panel that opens on top of the current page.
The target URL must support embedding via its X-Frame-Options header.
Pages
Client
Client custom integrations will be rendered on the client page on the right-hand side, above the Notes section when browsing any of the client tabs ('Client details', 'Billing', 'Treatments', etc.). It will not be rendered on the patient tabs. The client ID will be sent as a parameter.
Patient
Similarly, patient custom integrations will be rendered on the patient page on the right-hand side, above the Notes section when browsing any patient tabs ('Patient details', 'History', 'Measurements', etc.). It will not be rendered on the client tabs. The patient ID will be sent as a parameter.
Invoice
Invoice custom integrations will be rendered on invoice (including counter sale) pages in the bottom toolbar. The invoice ID (not to be confused with invoice number) will be sent as a parameter.
Consultation
Consultation custom integrations will be rendered on the consultation page above the general info section, both for ongoing and finished consultations. The consultation ID will be sent as a parameter.
Appointment Calendar
Appointment calendar custom integrations will be rendered on top of the appointment calendar. The active department ID will be sent as a parameter.
Shift Calendar
Similarly, shift calendar custom integrations will be rendered on top of the shift calendar, under the shift type and shift template selection. The active department ID will be sent as a parameter.
Diagnostic Imaging
Diagnostic imaging custom integrations will be rendered on the diagnostic imaging referral page in the top and bottom toolbars. The diagnostic imaging referral ID will be sent as a parameter.
Reminders
Reminder custom integrations will be rendered in the selection toolbar on the reminders page when one or more reminders are selected in the table. Multiple reminders can be chosen and sent at the same time. The reminder ID for each selected reminder will be sent as parameters.
Verification Hashes
If there is a risk that outside parties may send requests to the target URL, and it is required to know which requests are coming from the Provet Cloud custom integration, verification hashes can be used as additional validation. When enabled, an additional parameter called "verification" will be added to requests and is an MD5 hash digest of the timestamp and verification salt.
For example, to verify that the verification hash is valid in Python, one might write a function like this:
When using background sending ('Send HTTP request'), the timestamp is generated when the request is actually sent. However, when using foreground sending ('Open in a new window'), the timestamp is generated when a page containing the custom integration button is loaded. This is done in order to generate the verification hash on the server-side and avoid exposing the verification salt to users. Developers of custom integrations might need to consider that the users may spend some time on the page before clicking the custom integration button.
Two-way Communication with Provet Cloud
Provet Cloud allows for a limited amount of two-way communication with custom integrations opened in the foreground using the Window.postMessage() API. The window/tab that opened the custom integration is available via the window.opener object and thus a message can be posted with window.opener.postMessage(message), where the message is a valid command recognised by Provet Cloud.
Currently, the only valid command is "reload", which will perform a full page reload on the window/tab which opened the custom integration. This may, for example, be useful if the custom integration updates Provet Cloud data via the REST API, and the users should see the latest changes when returning from the custom integration.
See Also
Integrating Third-Party Applications with Provet Cloud
Updated
Comments
0 comments
Please sign in to leave a comment.