[en] Custom integrations are a feature in Provet that allows sending requests to external resources from inside Provet. To gain access to this feature, contact Provet support.
[en] Management
[en] Manage custom integrations in Settings > Integrations > Custom integrations.
[en] To add an integration, select the Add button.
[en] To edit an integration, select the pen button on the table row.
[en] Settings
[en] Field | [en] Description |
[en] Name | [en] Specifies the label on the button visible in the user interface. |
[en] Visible page | [en] 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. |
[en] Action | [en] Specifies which action will be taken when the button is selected. |
[en] HTTP method | [en] Specifies whether the request will be sent as a GET request (payload supplied as parameters in the query string) or as a POST request (payload supplied as form data. |
[en] URL | [en] The target URL, complete with schema. |
[en] Parameter name | [en] The name of the parameter used when supplying the current object's ID. |
[en] Enabled | [en] Allows enabling and disabling a custom integration. Custom integrations can also be deleted if they are no longer needed. |
[en] Verification salt | [en] A shared secret that is used to calculate the verification hash. Required when the verification hash is enabled. |
[en] Configuration Options
[en] 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.
[en] Include payload in verification hash: This option recalculates the verification hash using the full payload, including user and client IDs.
[en] Add organization and department information: This option includes the necessary organizational and departmental information automatically. Provet will include these parameters in the request: Provet name (organization core), Provet ID (product organization ID), and Department ID.
[en] Prefixing Parameter Value
[en] It is possible to add a custom prefix to the parameter value by specifying the parameter name differently.
[en] For example, if you define the parameter name as 'id=client_', it will send a request like https://example.com/?id=client_1.
[en] Headers
[en] Background requests ('Send HTTP request') can be given arbitrary, static values that will be added to the requests.
[en] This can be used to include Authorisation headers in requests.
[en] This feature is not implemented for foreground requests ('Open in a new window', 'Open in side panel'). Sent headers are also not logged.
[en] Payload Information
[en] The settings view displays a list of payload keys and values that are sent with the request. This list updates as the settings are modified.
[en] Action Types
[en] 1. Send HTTP Request
[en] A request is scheduled in the background and sent using Provet's servers. Users will not see the webpage but may see a notification when the sending progresses.
[en] The request will come from Provet's outgoing IP addresses.
[en] The sending happens asynchronously, and there may be a delay depending on the amount of work currently on the servers.
[en] You will see an information notification at the top of the page when the request is being scheduled.
[en] 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).
[en] If the request fails, an error notification saying 'Integration request failed' will be shown, with a more specific error message in the parenthesis.
[en] Error Message | [en] Description |
[en] Backend error | [en] An unknown error occurred on Provet's worker servers. Contact Provet support for additional information. |
[en] Connection error | [en] The request to schedule the sending did not go through. |
[en] Data error | [en] The request to schedule the sending contained invalid data. |
[en] Integration error | [en] The request was sent successfully, but the integration responded with a non-successful HTTP status code (lower than 200 or higher than 299). |
[en] 2. Open in New Window
[en] The target URL is opened in a new window or browser tab.
[en] If a GET request is used, users can see the payload information displayed in the browser's address bar.
[en] 3. Open in Side Panel
[en] The target URL is embedded in Provet by opening a side panel on top of the page content and displaying the page as an iframe.
[en] The target URL must support embedding (the X-Frame-Options header must be set correctly).
[en] Usage
[en] Custom integrations are rendered as buttons on target pages.
[en] If only one integration is set up for a page, it is rendered as a regular button.
[en] If a page has multiple integrations, they are rendered as a drop-down menu.
[en] Custom integrations only send the relevant object ID (client ID, patient ID, invoice ID, etc.) that can be queried from the Provet REST API.
[en] Page | [en] Button Location | [en] ID Sent as a Parameter |
[en] Client | [en] On the right-hand side, above the Notes section (not on the patient tabs). | [en] Client ID |
[en] Patient | [en] On the right-hand side, above the Notes section (not on the client tabs). | [en] Patient ID |
[en] Invoice | [en] In the bottom toolbar of the invoice (including counter sale) pages. | [en] Invoice ID (not the invoice number) |
[en] Consultation | [en] Above the general info section, for both ongoing and finished consultations. | [en] Consultation ID |
[en] Appointment Calendar | [en] On top of the appointment calendar. | [en] Active clinic location ID |
[en] Shift Calendar | [en] On top of the shift calendar. | [en] Active clinic location ID |
[en] Diagnostic Imaging | [en] On the diagnostic imaging referral page in the top and bottom toolbars. | [en] Diagnostic imaging referral ID |
[en] Reminders | [en] In the selection toolbar on the reminders page when one or more reminders are selected. | [en] Reminder ID for each selected reminder |
[en] Log
[en] Requests sent in the background ('Send HTTP request') are recorded in an internal log for verification and auditing.
[en] Go to Settings > Integrations > Custom integrations > Log.
[en] The log view lists all made requests, beginning with the latest request.
[en] View more information in the detail view by selecting the eye button on the right-hand side of each row.
Notat
[en] Logging is not performed on foreground requests ('Open in a new window', 'Open in side panel').
[en] Verification Salt & Hashes
[en] The "Verification salt" option is visible only if "Add verification hash" is selected. Additionally, "Include payload in verification hash" is also displayed when "Add verification hash is selected".
[en] Based on the combination of permissions, the verification hash is calculated as follows:
1. Verification salt enabled, "include payload in verficiation option" disabled -> hash calculated as:Hexadecimal verification MD5 hash digest, e.g. "4e531ee13aa16886db72bc1621206d2f". The hash is generated by appending the verification salt after the included timestamp ("2018-07-15T09:12:54+00:00My verification salt"). [string]2. Verification salt enabled, "include payload in verification option" enabled, "Add organization and department information" DISABLED -> hash calculated as:Hexadecimal verification MD5 hash digest, e.g. "23ae5385b3862a571f1b5d6f6b469b1c". The hash is calculated with: "<timestamp><salt><parameter_name><object_id>user_id<user_id>" ("2018-07-15T09:12:54+00:00My verification saltpatient_id1234user_id56"). [string]3. Verification salt enabled, "include payload in verification option" enabled, "Add organization and department information" ENABLED -> hash calculated as:Hexadecimal verification MD5 hash digest, e.g. "163049a017bb405d4bfec754810c9838". The hash is calculated with: "<timestamp><salt><parameter_name><object_id>user_id<user_id>provet_env<provet_env>provet_id<provet_id>department_id<department_id>" ("2018-07-15T09:12:54+00:00My verification saltpatient_id1234user_id56provet_envenvprovet_id12345department_id12"). [string][en] Verification hashes can be used as additional validation to verify which requests are coming from the Provet custom integration.
[en] When enabled, an additional parameter called "verification" is added to requests.
[en] This parameter is an MD5 hash digest of the timestamp and verification salt.
[en] For background sending, the timestamp is generated when the request is actually sent.
[en] For foreground sending, the timestamp is generated when a page containing the custom integration button is loaded.
[en] For example, to verify that the verification hash is valid in Python, one might write a function like this:
from hashlib import md5VERIFICATION_SALT = "My custom verification salt"def is_verification_hash_valid(parameters): hasher = md5() hasher.update(parameters.timestamp.encode("utf8")) hasher.update(VERIFICATION_SALT.encode("utf8")) return hasher.hexdigest() == parameters.verification[en] Two-way Communication with Provet
[en] Provet allows for a limited amount of two-way communication with custom integrations opened in the foreground using the Window.postMessage() API.
[en] The only valid command is "reload".
function refreshProvetCloud() { window.opener.postMessage("reload","*");}[en] This command performs a full page reload on the window or tab that opened the custom integration.
[en] This may be useful if the custom integration updates Provet data via the REST API.