Integrating Third-party Applications with Provet Cloud

Quick Links

Integration Solution Example

Webhooks

REST API

Integration Catalogue in Provet Cloud

Data Available Through the REST API

Permissions

Usage Example

Custom Integrations

Introduction

Provet Cloud veterinary practice management system can be integrated with third-party applications using tools called REST API and webhooks. This article describes the usage of these integration methodologies.

Webhooks are available in Provet Cloud to send notifications to third-party systems about additions or changes in the data inside Provet Cloud. The webhooks don't transfer the actual changed data, but instead, they transfer the information about what has changed by simply notifying the third-party system about the change. The actual data can then be fetched by the third-party system by utilising the REST API of Provet Cloud.

REST API is a communication method to access, edit or add to the data residing in Provet Cloud programmatically by any third-party application. Provet Cloud's REST API offers most of the key Provet Cloud data to be read or manipulated by other systems.

The combination of Provet Cloud webhooks & REST API creates unique possibilities for building integrated solutions. Any vendor of other systems familiar with these technologies can easily integrate with the data residing in the Provet Cloud veterinary practice management system by utilising these technologies.

Nordhealth offers consultancy to assist with the usage of the REST API & webhooks. We can also build customised adaptors to process or format the data to more traditional transfer formats such as XML, ASCII, or CSV files.

NOTE: See more from our developer site.

Integration Solution Example

Case: If a third-party system (e.g. a financial system) would like to have immediate information about a newly created consultation in the Provet Cloud, this could be archived by combining the webhooks & REST API in the following way by utilising the consultation webhook.

  1. A consultation is created in Provet Cloud.
  2. Provet Cloud sends a consultation HTTP hook notification to the URL defined in the settings.
    • Webhook: Consultation create/update
    • Parameter: consultation_id=123 (consultation with ID 123 has been created)
  3. Third-party system receives the hook and knows that consultation with ID 123 has been created in the Provet Cloud.
  4. Third-party system requests the consultation with ID 123 data by using the REST API call.
  5. Provet Cloud returns the data for the consultation with ID 123 in the JSON format.
  6. Third-party system receives the data of the consultation and processes it in the desired way (and creates further REST API calls, if necessary).

integration-solution-scheme.png

Webhooks

Webhooks are configured and enabled in Settings > General > Integrations > Webhooks.

  • Webhooks are HTTP POST requests to the URL defined in the settings for each webhook
  • The POST request has data identifying what type of data was updated, and the ID of the object
    • Example: “consultation_id=123”
  • Webhooks expect to receive an HTTP 200 response on the successful process
    • If the response is other than HTTP 200, the notification delivery will be retried
    • On the settings page, you can also see an up-to-date list of triggered webhooks and their delivery status. A log is available for the review
  • Webhooks can be set to be department-specific, in which case they only trigger when items on a certain department are updated, or can be set to be organization-wide, in which case they always trigger.
    • Leaving the department field empty will make the webhook work across the entire organization.
    • Certain actions where departments cannot be inferred, such as updating clients and patients through the REST API, do not trigger department-specific webhooks.
  • Multiple webhooks can be set for the same trigger and/or department, and updates will trigger all of the webhooks that apply in the situation.
  • Webhooks can be given an optional name to help identify and differentiate them.
  • No longer needed webhooks can be disabled by unchecking the Active checkbox.

The following Webhook events are currently available in the settings of the Provet Cloud. Each of the hooks can have a different (or same) URL address, to which the Provet Cloud sends the hook when triggered at the event.

  • Accounting report create/update: parameter accountingreport_id
  • Appointment create/update: parameter appointment_id
  • Appointment delete: parameter appointment_id
  • Appointment reminder create: parameter reminder_id
  • Appointment reminder update: parameter reminder_id
  • Appointment reminder delete: parameter reminder_id
  • Client create/update: parameter client_id
  • Client delete: parameter client_id
  • Client communication preference create: parameter communication preference id
  • Consultation create/update: parameter consultation_id
  • Consultation delete: parameter consultation_id
  • Consultation item create/update: parameter consultationitem_id
  • Consultation waiting discharge: parameter consultation_id
  • Consultation finalize: parameter consultation_id
  • Diagnostic imaging worklist create: parameter diagnosticimagingworklist_id
  • Diagnostic imaging worklist update: parameter diagnosticimagingworklist_id
  • Diagnostic imaging worklist delete: parameter diagnosticimagingworklist_id
  • Email sent log
  • Health plan status update
  • Insurance claim create/update: parameter insuranceclaim_id
  • Invoice create / update: parameter invoice id
  • Invoice draft hook, notifies when a draft invoice is updated or items added automatically
  • Invoice payment create: parameter invoicepayment_id
  • Invoice finalized: parameter invoice_id
  • Invoice row delete
  • Laboratory referral create/update: parameter laboratory_referral_id
  • Notes & communication
  • Organization item create/update: parameter organizationitem_id
  • Organization food create/update: parameter item_id
  • Organization laboratory analysisis create/update: parameter item_id
  • Organization laboratory analysis panel create/update: parameter item_id
  • Organization medicine create/update: parameter item_id
  • Organization procedure create/update: parameter item_id
  • Organization supply create/update: parameter item_id
  • Patient create/update: parameter patient_id
  • Patient Referral create
  • Patient referral feedback sent
  • Prepayment (unallocated payment) create/update: parameter unallocatedpayment_id
  • Reminder create/update
  • Reminder delete
  • Reminder template delete
  • SMS sent log
  • Stock item entry
  • Stock item entry delete
  • Stock order
  • Stock order delete
  • Stock order item
  • Stock order item delete
  • Treatment plan create
  • Treatment plan update
  • Treatment plan delete
  • Treatment plan item create
  • Treatment plan item delete
  • User create, parameter user id
NOTE: This list here was updated during May 2024. Additional hooks are being constantly developed based on requests from our users.

REST API

Provet Cloud provides the REST API for enabling access to the data stored in the Provet Cloud. The API uses OAuth 2.0 authentication. The data is returned in the JSON format.

  • To access the REST API, you must ask Provet Cloud Support to generate you an integration template
    • Provet Cloud API support two grant types: Authorization Code and Client Credentials.
      • Authorization Code is used for authenticating user interfaces and cases where users access the API as themselves. PKCE is supported and highly recommended. Public clients MUST use PKCE. 
      • Client Credentials is used for backend connectivity where services communicate directly with another without any user actions.
  • The REST API can be accessed by using a URL compiled as follows: https://<provet_environment>/<provet_id>/api/0.1/
    • <provet_environment> URL differs a bit for each environment. It can be, for example
      • provetcloud.com for EU environment
      • us.provetcloud.com for USA environment
    • In the URL <provet_id> is the unique id of the Provet Cloud instance for your company
    • The whole URL is always shown in API settings in Provet Cloud Settings -> Integrations -> API Tokens

Provet Cloud REST API is browseable, which should allow a good possibility for developers to evaluate the possibilities of data transfer.

Integration Catalogue in Provet Cloud

Once the template is created, the integration can be seen in the integration catalogue in Provet Cloud: Settings -> Integrations -> Open API access -> Add Application. The catalogue lists the available integrations and has a short description of what each integration does. If the integration has more setup instructions, that is shown in the catalogue too.

The integrations can have restricted visibility: they can be restricted to only certain Provet Cloud tenants or in certain countries. The third party providing the integration can choose how widely the integration needs to be visible on the tenants. When there are restrictions, the application is shown in Integration Catalogue only on those tenants / in those countries that it is allowed on.

Options in a New Client Registration

Every time a new client registers to use an integration i.e. chooses it from the integration catalogue in Provet Cloud (Add Application), unique client credentials are sent to the integration provider. There are two options for notifying a registration of a new client that can be chosen when creating an integration template:

  • email
  • hookup URL

When the integration is used only on one Provet Cloud instance, email is a good choice: then the person receiving the email can configure the authentication details to the integration and start using it. On the other hand, when the integration is widely used, hookup URL and automating adding a new client is recommended.

Hookup URL is listening for any automated notifications of new clients. When a new client adds the integration in Provet Cloud, the orchestration tool sends automatically a JSON message to that given URL. There isn't a need for any human interaction, when the integration automatically parses the new client from the JSON message and adds their credentials to their client table.

JSON schema for the data sent for new integration registrations:

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"provet_id",
"client_id",
"client_secret",
"algorithm",
"authorization_grant_type",
"client_type",
"redirect_uris",
"token_url",
"authorize_url",
"openid_autodiscovery_url"
],
"properties": {
"provet_id": {
"type": "number",
"description": "Provet ID of the tenant who added this integration."
},
"client_id": {
"type": "string"
},
"client_secret": {
"type": ["null", "string"]
},
"algorithm": {
"type": ["null", "string"],
"description": "Signing algorithm used.",
"examples": [null, "HS256", "RS256"]
},
"authorization_grant_type": {
"type": "string",
"description": "Authorization flow used.",
"examples": ["authorization-code", "client-credentials"]
},
"client_type": {
"type": "string",
"description": "Client type.",
"examples": ["confidential", "public"]
},
"redirect_uris": {
"type": "string",
"description": "Space-separated list of callback URIs.",
"examples": ["https://example.com/callback"]
},
"token_url": {
"type": "string",
"description": "OAuth2.0 token endpoint URL."
},
"authorize_url": {
"type": "string",
"description": "OAuth2.0 authorize endpoint URL."
},
"openid_autodiscovery_url": {
"type": ["null", "string"],
"description": "OpenID autodiscovery URL. Null if integration does not use OpenID."
}
}
}

Data Available Through the REST API

The REST API can be used to read most of the data and create/update some selected parts of the data. The first page of the browsable API lists all of the objects that can be accessed. Here’s the list of the most common objects.

Generic

Name

C

U

D

Description

Endpoint

Custom field

     

Custom fields defined in settings; they can be used on patients and clients, for example

custom_fields

Custom field value

If custom fields are used on a patient X, they will generate a row here

custom_field_values

Note

Notes residing in section “Notes & Communication” in patient’s/client’s page

note

noteadmin

Task

Tasks for veterinarians

task

Reminder

Reminders for patients

reminder

Reminder template

Template for creating reminders

remindertemplate

 

Client & Patient

Name

C

U

D

Description

Endpoint

Client

 

Client for patient

client

Patient

 

Patient

patient

Phone number

Phone numbers for clients

phonenumber

Imported history

 

Allows importing patient history from old systems in specific format

importedhistory

 

Invoicing

Name

C

U

D

Description

Endpoint

Invoice

     

Invoices for clients

invoice

Invoice Row

     

Invoice rows of invoices

invoicerow

Invoice payment

 

Payments on invoices

invoicepayment

Prepayment

   

Prepayment (also known as unallocated payments) on clients. Can be used to pay a future invoice

unallocatedpayment

Payment method

     

Available payment methods in the system

paymentmethod

Insurance claim

 

 

Insurance claims for patients

insuranceclaim

Insurance claim client

     

Dummy client copied from client-data for insurance claim

insuranceclaimclient

Insurance claim patient

     

Dummy patient copied from patient-data for insurance claim

insuranceclaimpatient

 

Organisation

Name

C

U

D

Description

Endpoint

Department

     

Departments

department

Department group

     

Group of departments

departmentgroup

User

 

User account of provet cloud

user

User details

Additional information about the user

userdetails

User group

     

Users work group, relates to user access

usergroup

Item list

     

Item list contains X number of items. Departments are subscribed to one item list and they’ll use it on consultations and countersales

itemlist

Item

 

Items in settings. A general extendable model for all items. Contains sub types: Procedure, Medicine, Supply, Food, Laboratory analysis, Laboratory analysis panel

Item

procedure

medicine

supply

food

laboratoryanalysis

laboratoryanalysispanel

Item group

Also known as invoice group. Items can be grouped by subgroup information that is filterable in some searches

itemsubgroup

invoicegroup

VAT group

     

Organization’s VAT groups

vatgroup

Text template

     

Custom text templates to be used around ProvetCloud, for example, consultation notes and discharge instructions

text_template

Item template

Item templates in settings.Describes a set of items

itemtemplate

Item template item

An item, or item template in item template of settings

itemtemplateitem

Alternative pricing

Alternative pricing options for item, for example allowing cheaper bulk sale for certain amount

alternativepricing

Lists

Custom lists in settings for, for example, species and breeds

list

List items

 

A list item in custom lists in settings

listitem

Codelists

     

More convenient way to view list items. Contains only active list items, but can list codes that do not come from database, like VeNom codes for example

codelist

Holding place number

Related to production animal features; a numerical information for patient’s holding place

holdingplacenumbers

 

Stock

Name

C

U

D

Description

Endpoint

Level

     

All stock items and their levels

stock/item

stocklevel

Location

     

Location where the stock is held

stock/location

Batch

Stock batches for stock items

stock/batch

Entry

   

Stock entries (usages) for stock items

stock/entry

Wholesaler

Wholesalers for making orders

wholesaler

Order

 

Product order to wholesaler

order

Order item

Item in product order

orderitem

 

Diagnostic imaging

Name

C

U

D

Description

Endpoint

Worklist

Worklist entries for diagnostic imaging referrals

diagnosticimaging_worklist

Modality

     

Modality for diagnostic imaging

modality

Category

     

Diagnostic imaging category

imagingcategory

Sub-category

     

Sub-category for diagnostic imaging categories

imagingsubcategory

Target area

     

Target area for modality

targetarea

Resource

     

Resource for diagnostic imaging

resource

 

Consultation

Name

C

U

D

Description

Endpoint

Consultation

     

Consultation for client and patient(s)

consultation

Item

Base Item for items added to consultation. Contains subtypes: Procedure, Medicine, Supply, Food, Laboratory analysis

consultationitem

consultation_items/procedure

consultation_items/medicine

consultation_items/supply

consultation_items/food

consultation_items/analysis

Treatment plan

     

Treatment plan that contains information about items to be used in future

treatmentplan

Treatment plan item

     

Plan item of treatment plan.

treatmentplanprocedure

treatmentplanmedicine

treatmentplansupply

treatmentplanfood

Estimate

     

Estimation for consultation

estimate

Estimate item

     

Item added for consultation estimate

estimateitem

Item template

     

Item templates (also known as consultation bundles) that have been added to a consultation

consultationitemtemplate

Laboratory referral

Referral (also known as request) for consultation

consultation_laboratory_referral

Laboratory sample

 

A sample containing consultation analyses and panels for consultation

consultation_sample

Diagnostic imaging referral

Referral (also known as request) for consultation

diagnosticimaging_referral

Diagnostic imaging target area

Target area used during consultation

consultation_targetarea

 

Scheduling

Name

C

U

D

Description

Endpoint

Appointment

 

Appointments for patients. Also known as Scheduling event

appointment

Shift

Shifts for users

shift

Shift type

     

Types for shifts defined in settings

shifttype

Reason

Reason for appointment

reason

Reason group

Reason groups can be department specific. Used to group reasons in searches

reason_group

Cancellation reason

       

cancellationreason

Triage

     

An instance holding information about triage events

triage

Triage category

     

Categories for triage in settings

triage_category

Triage entry

     

One event in triage

triage_entry

Veterinarians availability

     

Returns available shifts for veterinarians on the given time period

veterinarians_availibility

On-line booking client

   

Dummy client created for online booking appointment

onlinebookingclient

On-line booking patient

   

Dummy patient created for online booking appointment

onlinebookingpatient

 

Permissions

When a new integration application is added to Provet Cloud, a virtual user is automatically created for that integration. The virtual user is called Integration <Integration name> and can be found in Provet Cloud user settings under the Virtual tab. The virtual user is by default assigned to permission group Users.

If the integration needs different permissions (some endpoints are denied or you want to restrict the permissions), we recommend to create a new permission group just for that one virtual user:

  1. Either copy an existing permission group or create a new one and rename it with a descriptive name, for example same name as the integration.
  2. Grant the group the needed permissions. Check from Provet Cloud API schema, which permissions does each endpoint need. Check also Managing user permissions and groups.
  3. Edit the virtual user and add the user to the new permission group (field Default Permission Group). The user doesn't have a Work role either so you have to choose that as well. Technical is the role meant for virtual users like the integration's user.

Usage Example

To get information about a consultation with ID number 338, an HTTP GET request with the authentication parameters would be sent to the following URL: https://provetcloud.com/<provet_id>/api/0.1/consultation/338/

Response example:

{
   "url": "https://provetcloud.com/<provet_id>/api/0.1/consultation/338/",
   "client": "https://provetcloud.com/<provet_id>/api/0.1/client/1/",
   "patients": [
       "https://provetcloud.com/<provet_id>/api/0.1/patient/1/"
   ],
   "complaint": "Test consultation",
   "admitted_time": "2017-05-18T10:35:00Z",
   "first_entry": null,
   "started": "2017-05-18T10:35:00Z",
   "finished": null,
   "ended": null,
   "status": 8,
   "type": 0,
   "invoice": "https://provetcloud.com/api/<provet_id>/0.1/invoice/609/",
   "supervising_veterinarian": "https://provetcloud.com/api/<provet_id>/0.1/user/1/",
   "department": "https://provetcloud.com/<provet_id>/api/0.1/department/1/",
   "consultation_items": [
       "https://provetcloud.com/<provet_id>/api/0.1/consultationitem/4558/",
       "https://provetcloud.com/<provet_id>/api/0.1/consultationitem/4559/",
       "https://provetcloud.com/<provet_id>/api/0.1/consultationitem/4560/"
   ],
   "reporting_dimension_1": null,
   "reporting_dimension_2": null
}

From the response it is possible to further find the ID of the invoice, that is related to this consultation, as well as all other entities that are related to this consultation. Those can be then acquired by further REST API calls.

Filters

Some endpoints have fields that can be used to filter the results. The filterable fields can be seen at the top of your Provet Cloud REST API endpoint page (eg. https://provetcloud.com/<provet_id>/api/0.1/consultation/) if the endpoint has filterable fields.

The following methods are available for filtering (synonyms are comma-separated):

  • is, eq (equal)
  • is_not, not_eq, neq (not equal)
  • lt (less than)
  • lte (less than or equal)
  • gt (greater than)
  • gte (greater than or equal)
  • range (values between, needs two values in order [from,to])
  • not_in_range (above inversed)
  • contains (text contains the searched text, case-sensitive)
  • contains_not (above inversed)
  • icontains (text contains the searched text, case-insensitive)
  • icontains_not (above inversed)
  • in (item is found in the given list [value1,value2,value3])
  • not_in (above inversed)
  • is_null (true or false)

The filtering methods can be used with query parameters using the following syntaxes:

  [field]__[method]=value (eg. client__is=10 which uses the id of the client for the search)

  [field].[property]__[method]=value (eg. client.id__is=10)

Note that dates should be given for the query parameters in the format YYYY-MM-DD hh:mm+[TimeZone]hh:mm (eg. 2017-12-24 15:30+00:00).

If we need to find all consultations with the conditions

  • complaint contains the word “vacc” (case-insensitive)
  • the admitted_time is between 2017-12-01 00:00+00:00 (greater than or equal) and 2018-01-01 00:00+00:00 (less than)
  • department id is 1
  • client id is 10
  • one of the patients’ id in the consultation is 20

we would use the following url:

https://provetcloud.com/<provet_id>/api/0.1/consultation/?complaint__icontains=vacc&admitted_time__gte=2017-12-01 00:00%2B00:00&admitted_time__lt=2018-01-01 00:00%2B00:00&department__is=1&client__is=10&patients__is=20

Note that "+" signs are URL encoded (%2B) in the above example for the URL to work.

If we need to find all consultations where

  • the client’s first name is John and
  • the client’s last name is Doe

we would use the following URL:

https://provetcloud.com/<provet_id>/api/0.1/consultation/?client.firstname__is=John&client.lastname__is=Doe

Expose

Some endpoints have fields that can be exposed, which will then show some of the inner fields of the exposed object. The exposable fields can be seen at the top of your Provet Cloud REST API endpoint page (eg. https://provetcloud.com/<provet_id>/api/0.1/invoicerow/) if the endpoint has exposable fields. To expose a field, you can add ?expose_<field_name> into the URL, much like filters are used.

Custom Integrations

Even though our webhooks & REST API provide a possibility for self-service integrations, Nordhealth also provides consultancy services for the development of the integrations. See the related article below. Please contact Provet Cloud support to discuss any additional requirements.

See Also

Custom Integrations

https://developers.provetcloud.com/

API Application Control Change 2023 

 

Updated

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request

Comments

1 comment

Please sign in to leave a comment.