Getting started with Halo Cloud

This page outlines how to get started with Halo Cloud in general. Details of how to use specific products can be found under their respective docs pages.

Prerequisites

To get started with Halo Cloud, you will need:

Your Halo Connect subscription key
A server running:
- A supported PMS database which has:
  - The appropriate database credentials set up
  - If required, your integration enabled in the database and/or UI
- An instance of Halo Link
A way to send HTTP requests
- For testing, a program like Postman or Insomnia is fine

Secure your Halo Connect subscription key

Please ensure your Halo Connect subscription key is kept secret. It should be stored in a secure manner, and only shared within your organisation as needed. Halo Connect staff will never ask for your subscription key.

If you think your subscription key has been compromised, please contact us immediately so we can enact security precautions and mitigate any potential risks.

You will also need to fetch the Halo GUID associated with your PMS database. See Working with Halo GUIDs below for how to do this.

Environments

Halo Connect has both production and staging environments.

Production connects to live practice databases, and should only be used with production quality code.
Stage is designed for development and testing, and receives updates before production so that integrators can test new features and bug fixes early.

To successfully connect to an environment, you will need for that environment:

A Halo Connect subscription key
The Halo Cloud API base URL
A Halo Link instance that connects to a supported PMS database

Production subscription keys can not be used with staging Link instances and vice versa. Depending on which PMS you are integrating with, they may also have requirements of moving from staging to production. Please check with the PMS provider regarding production requirements.

Installing Halo Link in Stage requires an extra step compared to production

Please see the Halo Link installation instructions for integrators for more information about setting Halo Link to Stage.

This is particularly important for any PMS which bundles Halo Link, which will install Halo Link in production by default. It is best to set Link to Stage before installing Halo Link or any PMS software.

Moving from staging to production

When your product is ready to rollout in production, please reach out to the Halo Connect team. There are a few steps to the process, including:

Finalising the commercial agreement for a production subscription
Analysis of your planned API usage, to ensure provisioning
If possible, a beta test of your integration running as it would in production for at least one day on one practice server, to ensure all factors have been accounted for
Coordination of a rollout strategy, to ensure both parties can manage and monitor the rollout over time

API Reference

The API reference can be found in the navigation on the left, or alternatively at the following links:

StagingProduction

https://docs.stage.haloconnect.io/api-reference/integrator-openapi.html

https://docs.haloconnect.io/api-reference/integrator-openapi.html

The Halo Connect API has been documented using the OpenAPI Specification.

Connecting to Halo Cloud

The following details how to connect to Halo Cloud.

Base API URL

This is the base API URL for Halo Cloud. All products and their endpoints extend this URL.

StagingProduction

https://api.stage.haloconnect.io/integrator

https://api.haloconnect.io/integrator

Available endpoints

The Halo Cloud API reference covers all Halo Cloud products and endpoints. There are currently three categories of endpoints:

Category	Description	URL prefix
SQL Passthrough	Endpoints for sending immediate and async SQL queries.	`/sites/{haloGuid}/queries`
FHIR API	Endpoints for sending FHIR queries to practices.	`/sites/{haloGuid}/fhir/R4`
Site APIs	Endpoints for fetching information regarding "sites".	`/sites`

For example, the full URL for sending an immediate query to a site with a particular Halo GUID in staging is: https://api.stage.haloconnect.io/integrator/sites/{haloGuid}/queries/immediate.

A "site", when used in the API reference and API endpoints, refers to a PMS database. This could be a live practice database or a development database hosted by an integrator.

Authentication

To authenticate with Halo Cloud, you will need to include your subscription key in your HTTP POST as either:

A header with the name Ocp-Apim-Subscription-Key, or
A query parameter with the name subscription-key

Webhook notifications

To configure webhook notifications:

To start receiving webhooks, an integrator would register a URL with us via a manual process.
Currently, this can only be a single URL or URL template per integrator.
URL templates are populated for each webhook sent and includes variable substitutions from a defined set.
- {siteId} is replaced with the siteId from the query
- {queryId} is replaced with the queryId from the query
- {source} is replaced with the source of the query; either “async” or “registered”

For more information or to configure webhook notifications for your subscription, please Contact Support.

Test queries

To test your connection to Halo Cloud, you could:

Query the Get site status endpoint, to check the status of your Halo Link instance. In staging, use the URL https://api.stage.haloconnect.io/integrator/sites/{haloGUID} and substitute your Halo GUID for {haloGUID}.
Try one of the SQL Passthrough API query examples.

For testing, programs such as Postman or Insomnia are perfectly suitable for querying Halo Cloud.

Working with Halo GUIDs

Halo Cloud routes queries to practices by Halo GUID. The following outlines how to use Halo GUIDs, including recommendations for handling errors and changes.

Staging vs production

There are a few differences between how PMS IDs and Halo GUIDs work in production vs staging.

Production

All connected PMS databases must be full production copies. Developer licenses and demo databases can not connect to production.
Halo GUIDs should be fetched by trading the practice's unique PMS ID for their Halo GUID using the Get Halo GUID API endpoint.
Each PMS has a different PMS ID system. To check what each PMS's PMS ID is called and where to find it, see the relevant PMS guide page.

Staging

Developer licenses and demo versions of PMS databases often do not have a unique PMS ID, in which case Halo Link will assign a fake PMS ID so that the database can be uniquely addressed. This will be the first 8 characters of the database's Halo GUID.
Fake PMS IDs can be used with the Get Halo GUID API endpoint. Non-unique real PMS IDs can not.
It is easiest to get the Halo GUID of a Halo Link instance set to Stage from its:
- Application logs
- Registry values

Recommendations

Record PMS IDs

We recommend integrators store the PMS ID of practices they connect to. A practice's PMS ID does not tend to change unless the business itself changes significantly, so this is the best way to identify practices if something changes.

It is particularly useful when a practice's Halo GUID changes, such as due to a server migration, because it allows the integrator to automatically fetch the practice's new Halo GUID.

Use secondary identifiers

For each PMS, our Get Halo GUID and Get status endpoints will return at least one other piece of identifying information for each practice, such as the practice's business name (as fetched from their database) or their ABN.

We recommend integrators use this information to check they have the right practice when onboarding new practices.

If you're comfortable with storing or caching the secondary identifier, this can also be used to check for business changes. For example, a practice's name changing could be a sign of a practice split or merger.

See the relevant PMS guide to check what secondary identifer(s) are available for each PMS.

Automate handling of Halo GUID changes

Halo GUIDs are assigned by Halo Link when it is installed. While we have ways to account for most server changes that might invalidate a Halo GUID, there are cases in which a practice's Halo GUID may change.

We recommend integrators implement workflows to account for such changes with minimal service interruption for customers.

Fetching a Halo GUID

To fetch a practice's Halo GUID, we recommend:

Ask the practice for their PMS ID and optionally their secondary identifier(s).
Use the Get Halo GUIDs API endpoint to trade the PMS ID for the practice's current Halo GUID.
Check the second identifier(s) are correct.
Store or cache the Halo GUID for that practice for use when sending queries.
Optional: Send a test query to check everything works.

Handling Halo GUID changes

A practice's Halo GUID may occasionally change, usually due to a practice split or merger, or a significant server infrastructure change. When this happens, integrators will receive a 403 Forbidden error when trying to query the practice.

Handling such errors is often a simple process, and can possibly be automated. Although if a practice's secondary identifier(s) have changed, we recommend integrators reach out to the practice as this could signify a change to the business structure which may affect your product. If not, it's likely the cause was an infrastructure change, in which case it is up to the integrator whether they want to check with the practice.

To resolve such issues, we recommend:

When onboarding a practice, record their PMS ID and secondary identifier(s).
Upon receiving a 403 Forbidden error, use the Get Halo GUIDs API endpoint to trade the practice's PMS ID for their current Halo GUID.
Compare the practice's current and previous Halo GUID and secondary identifier(s).
If the secondary identifier(s) have changed, contact the practice to confirm any business changes.
If the Halo GUID has changed, you may choose to do some combination of:
Contact the practice to confirm what changed.
- Contact Halo Support to confirm what changed, as we have likely already discussed the change with the practice.
- Switch to using the new Halo GUID for sending queries, which should resolve the 403 errors.
If neither the Halo GUID nor secondary identifier(s) have changed and you continue to receive 403 errors, please contact Halo Support.

Prev: Halo Cloud overview

Next: SQL Passthrough overview Next: FHIR API overview