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 supported PMS database which has:
- 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:
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.
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
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
Stagefrom its:
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.
Automate handling of Halo GUID changes
Halo GUIDs are assigned by Halo Link when it is installed. Therefore, a practice's Halo GUID may change if Halo Link is reinstalled or if a practice migrates to a new server.
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
If a practice re-installs Halo Link or migrates servers, their Halo GUID may change. This will usually result in integrators receiving a 403 Forbidden error when trying to query the practice due to that Halo GUID becoming non-authoritative. Handling such errors can be done manually, or could potentially be automated using the workflow below.
If the practice's secondary identifier(s) have been recorded, this information can be used to also confirm that the practice's business details haven't changed, such as in the case of a practice merger or split.
- Retrieve the practice's PMS ID from storage, or re-request it from the practice. Optionally also retrieve or ask for their secondary identifier(s).
- Use the Get Halo GUIDs API endpoint to trade the PMS ID for the practice's current authoritative Halo GUID.
- Check if the Halo GUID returned by the endpoint is different to the previously recorded Halo GUID. Optionally check the secondary identifier(s) haven't changed.
- If the Halo GUID has changed (and the secondary identifiers haven't), update the stored or cached Halo GUID for that practice and send a test query, or flag the change for manual review. If not, contact the practice or Halo Support to investigate.