Integration Solution Example
Add an Integration Application in Provet Cloud
Provet Cloud veterinary practice management system can be integrated with third-party applications using tools called REST API and webhooks.
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.
Before you can start using the Provet Cloud APIs, we need to enable test environment access for you. Please contact our Partner Development Manager to get started.
We will create a test environment for you to access during initial development. We will also create you an integration template with the desired OAuth2 grant type for you with access to your test environment. This will allow you to develop and test your code with our API.
See our developer page for API documentation, API schema, and other valuable information to help you with your development.
Webhooks are configured and enabled in Settings > General > Integrations > Webhooks. Example: “consultation_id=123”.
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 need 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 > Open API access.
-
Provet Cloud REST API is browseable , which should allow a good possibility for developers to evaluate the possibilities of data transfer.
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.
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." } } }
When a new integration application is added to Provet Cloud, a virtual user and a permission group are automatically created for the integration. The virtual user is called Integration <Integration name> and it can be found in Settings > Users using the Virtual filter. The permission group has the same name as the integration.
Provet Cloud supports automated permission management, reducing manual effort and ensuring consistency. This feature is called 'permission template' and it is added on the integration template. Contact Provet Cloud support to get your permission template on your integration template.
When permission templates are modified, the associated permission group in Provet Cloud is automatically updated to match the latest template. The added permissions are included, and removed permissions are excluded to ensure synchronization.
If a permission template is not used, it has the same permissions by default as the permission group Users.
If an integration requires different permissions (some endpoints are denied or you want to restrict the permissions), the permissions must be edited. Check from the Provet Cloud API schema which permissions each endpoint needs. See also View and Manage User Permissions.
When you have developed and tested your integration and want to release it to public use, contact Provet Cloud support to get your Integration Template visible to all Provet Cloud instances. If your integration is not customer specific and it is meant to be used in many Provet Cloud instances by many users, there are some requirements to be met before going live. These requirements are meant to make the integration onboarding easier and provide needed information for Provet Cloud support.
-
Create a short video about your integration: how to use it and what it does.
-
Create an onboarding instruction that contains all the manual steps needed from the Provet Cloud user to take your integration into use. The steps can include the actions needed in your system as well.
-
See this example onboarding guide. The example integration uses one webhook, but your integration might need some other configuration like a custom field etc.
-
-
Provide us both the video and the onboarding guide and let us know on which markets / in which countries should your integration be visible in.
Updated
Comments
1 comment
Broken link removed.
Please sign in to leave a comment.