Skip to content

Halo Cloud overview

Halo Cloud is a collection of API products and meta-level APIs that enable easier integration with practice management systems (PMSs) via the cloud.

All Halo Cloud APIs are RESTful APIs accessible through HTTPs that return JSON-encoded responses and use standard HTTP response codes.

Our long-term goal is to offer a range of API products for various use cases, bridging the gap between various practice management systems. Currently, our available APIs are:

  • SQL Passthrough API

    An unopinionated SQL passthrough API which allows integrators to run standard SQL queries on practice databases via Halo Cloud APIs. Currently supports Bp Premier.

    • Maximum flexibility by allowing direct SQL access.
    • Minimal work required to switch existing SQL-based integrations to Halo Cloud.
    • Reduces development costs of new integrations by removing the need to develop and install a local agent on practice servers.

    Read more

  • FHIR API

    The FHIR API is an upcoming API product which will give integrators a new way to interact with PMS systems, no SQL required, using the HL7® FHIR® standard. Currently supports Bp Premier.

    • Maximum interoperability with other health care systems.
    • Develop for the future by adopting the standards Australian health care is moving towards.
    • Reduces the work required to understand the specific of the PMS database by surfacing the data using an international standard.

    Read more

Definitions

Many of the following terms are explained in more detail elsewhere in these docs. The following is just a quick reference guide.

Term Definition More info
Practice server(s) A server or set of servers which support one or more practices, on which the Bp Premier database and Halo Link are installed.
Site A PMS database which an installation of Halo Link connects to. This could be on a practice's server or an integrator's development environment.
Halo GUID Halo Connect's unique identifer for each practice server with Halo Link installed. Link
Halo Link Halo Connect's local agent which enables communication with on-premise PMS databases. Link
Halo Cloud Halo Connect's collection of API products and meta-level API endpoints.
Authoritative Halo Link instance The singular Halo Link instance integrations are allowed to connect to. Link
Non-authoritative Halo Link instance(s) Any other Halo Link instances that integrations are not allowed to connect to. Link

Basics

Base API URL

This is the base API URL for all Halo Cloud endpoints, regardless of product.

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

https://api.haloconnect.io/integrator

API reference

The combined API reference for all products is available at:

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.

Endpoint categories

There are currently three categories of endpoints:

Category Description More info
General Basic endpoints unrelated to a particular product. Here
SQL Passthrough APIs Endpoints for using immediate and async SQL queries. Here
FHIR APIs Endpoints for sending FHIR queries to practices. Here

Using Halo Cloud

Integrator requirements

To use Halo Cloud, you will need:

  • A subscription key for staging or production (per your agreement with us)
  • The Halo Link installer, for installation on development or testing machines during development
  • A test Bp Premier instance, for Halo Link to connect to for development and testing purposes

Warning

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.

Environments

Halo Connect has two public environments:

  • Staging: for development and testing
  • Production: for live use with practices

Integrators who are testing or developing for Halo Connect products will be given a subscription key for staging. This restricts access to "practice servers" or Halo Link installations which are also configured for staging. This is a security precaution to prevent accidental interactions with live practice servers.

When you are ready to move to a production subscription, 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

Halo Cloud authentication

Authenticating with Halo Cloud requires integrators supply their subscription key with each POST, either as:

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

PMS database authorisation

Halo Connect does not handle PMS database access authorisation. What data integrators can access is managed by the respective PMS provider (such as Bp for Bp Premier). For this reason, using Halo APIs requires integrators to have onboarded with the relevant PMS and for database credentials to have been created for the integrator's access requirements.

When an integrator onboards with Halo Connect, we coordinate with the relevant PMS provider(s) to securely store the integrator's credentials. When the integrator sends us a query, we then use those credentials to run the query on the specified practice server on their behalf.

If you find that your database access is not sufficient for your product, please reach out to the relevant PMS to discuss expanding your access.

Halo Link is an server-based local agent that takes queries from Halo Cloud and executes them on the nearby PMS database. To develop with or test Halo Cloud, integrators will need to install Halo Link in their own development or test environment using the Halo Link installer supplied with your subscription.

For more information, see the Halo Link docs.

Query routing

Routing queries to a specific practice requires the following:

  • A site is a term we often use to refer to a PMS database which an installation of Halo Link connects to. This could be on a practice's server or an integrator's development environment. You will see this terminology used both in the API reference and other places in these docs.
  • Each site is given its own unique Halo GUID.
  • To route a query to a particular practice, integrators must include the practice's Halo GUID in the query's URI.
  • Since Halo GUIDs identify PMS databases:
    • A PMS database which services multiple physical clinics (e.g. in the case of Bp Premier's locations) is assigned one Halo GUID. Differentiating the database data by clinic location is up to integrators.
    • One Halo Link install can connect to multiple PMS databases. Each PMS database receives a unique Halo GUID.
  • A practice's Halo GUID is not the same as their PMS ID (e.g. Bp Site ID for Bp Premier, or Database ID for Zedmed).
  • Since practices tend to be more aware of what their PMS ID is, the Get Halo GUIDs endpoint allows integrators to trade PMS IDs for Halo GUIDs. See below for more information.

Halo GUID workflows

The Get Halo GUIDs API endpoint allows integrators to trade a practice's PMS ID for their Halo GUID. There are two situations in which this is useful:

  1. Initial onboarding of a practice
  2. Handling Halo GUID changes

Bp Premier developer licenses are assigned fake Bp Site IDs

All sites running Bp Premier using a developer license are assigned Site ID 0. As this is not unique, Halo Link assigns such sites a unique, fake Bp Site ID. This is not reflected in the Bp Premier UI.

See the Bp Premier guide for more information.

Initial fetch for onboarding

When onboarding a practice, integrators will need to fetch their Halo GUID in order to be able to route queries to them. Most practices are aware of their PMS ID, which is usually visible somewhere in the PMS UI, so Halo Cloud includes an endpoint which allows integrators to trade a practice's PMS ID for their Halo GUID. This endpoint also returns extra information which can be used to check the Halo GUID is for the correct practice, in case the PMS ID was incorrectly typed at any point. Exactly what this data is differs by PMS, but it may include information such as the practice's name (in their PMS database) or their ABN.

To retrieve a practice's Halo GUID during onboarding:

  1. Request the PMS Site ID from the practice.
  2. Use the Get Halo GUIDs API endpoint to trade the PMS Site ID for the practice's current Halo GUID.
  3. Recommended: Check the other identifying data refers to the correct practice.
  4. Store or cache the Halo GUID for that site for use when sending queries.

We recommend you store the practice's PMS ID and any identifying information for future reference, as it will be helpful if the Halo GUID changes.

Handling Halo GUID changes

The above steps can also be used to re-fetch a site's authoritative Halo GUID if it changes, such as after a server migration. Such changes to the practice server should not affect the practice's PMS ID.

If the practice's other identifying information has also been kept, this can be used to confirm that the business details have not changed, such as in the case of a practice merger or split.

This could be a manual process, or could be automated in reaction to receiving a 403 Forbidden error after sending a query to a previously-working site. For example, a potential workflow is:

  1. Retrieve the PMS Site ID.
  2. Use the Get Halo GUIDs API endpoint to trade the PMS Site ID for the site's current authoritative Halo GUID.
  3. Check if the Halo GUID returned by the endpoint is different to the Halo GUID used to send the query.
  4. Recommended: Check if the other identifying data returned by the endpoint is the same as it was previously.
  5. If so, update the stored or cached Halo GUID for that site, or flag the change for manual review. If not, contact Halo Support.

Each Halo Link instance assigns a unique identifier to each PMS database it connects to -- this is what we call a Halo GUID. This allows integrators to route queries to specific practice databases using their Halo GUID.

Because a Halo GUID is also linked to the PMS ID for that PMS database, which is usually based on a license, it also allows us to detect when two Halo Link instances are trying to connect to two PMS databases using the same PMS license. 

graph TB
    subgraph Practice servers
        direction BT
        subgraph Primary server
            direction BT
            Zedmed1["PMS Database (PMS ID 1234)"]
            HL1["Halo Link (Halo GUID abcd)"]
            HL1 --> Zedmed1
        end
        subgraph Secondary server
            direction BT
            Zedmed2["PMS Database (PMS ID 1234)"]
            HL2["Halo Link (Halo GUID wxyz)"]
            HL2 --> Zedmed2
        end
    end

This usually happens if:

  1. The practice has multiple servers which have the PMS database installed. This is usually due to backup systems creating duplicates of the practice's server.
  2. The practice is migrating servers and needs to temporarily run two servers to ensure uptime during the switch.

In both cases, we restrict integration access for that practice to only one Halo Link instance, and therefore to only one PMS database. We use the following terminology to differentiate the Halo Link instances:

  • The authoritative Halo Link instance is the Halo Link instance connected to the PMS database which integrations should be connecting to.
  • Non-authoritative Halo Link instances are any Halo Link instances installed on other servers which integrations should not be able to connect to. These can include backup, testing, and migration servers.
Which Halo Link instance should be authoritative?

Integrations should only be connecting to the PMS database which the PMS client that practice staff use is connected to. The authoritative Halo Link instance should be the one connected to that PMS database. 

graph LR
    HC[Halo Cloud APIs]

    I1[PMS integration] --> HC
    I2[PMS integration] --> HC
    I3[PMS integration] --> HC

    subgraph Practice servers
        subgraph Primary server
            BP1[PMS database]
            HL1["Halo Link (authoritative)"]
            HL1 --> BP1
        end
        subgraph Secondary backup server
            direction LR
            BP2[PMS database]
            HL2["Halo Link (non-authoritative)"]
            HL2 --> BP2
        end
    end

    HC --> HL1

    subgraph Practice computers
        subgraph Staff computer
            BP1 --> C1[PMS Client]
        end
        subgraph Staff computer
            BP1 --> C2[PMS Client]
        end
        subgraph Staff computer
            BP1 --> C3[PMS Client]
        end
    end

Setting the authoritative Halo Link instance correctly is important to avoid:

  • Data degradation and desynchronisation due to some integrator queries going to one database and other queries going to the other database, resulting in the data in the two databases becoming different.
  • Backup corruption where a backup is meant to be a snapshot of the PMS database at a specific time, but integrator queries have caused changes since that time.
  • Incorrect data in the PMS client and/or integrations where the PMS client and/or integrations are pulling data from one database, but the other database is the one receiving updates.

For integrators: Handling 403 Forbidden errors

If an integration tries to query a non-authoritative Halo Link instance, it will receive a 403 Forbidden error. If that Halo GUID worked previously, this is likely a sign the practice has done a server migration or similar and now has a new authoritative Halo Link instance, which has a different Halo GUID.

To avoid service interruptions, integrations can automatically handle 403 errors using a workflow such as the one outlined in the Halo Cloud overview.

Which server is authoritative?

Halo Link decides whether a server is authoritative or not at installation. This is noted in Halo Link's logs.

Generally, the first installation of Halo Link for a PMS ID will automatically be set as authoritative. Subsequent installations which try to connect to a PMS database with the same ID will automatically be set as non-authoritative, whether or not Halo Link is being installed on the same server or a different server.

For Bp Premier integrators in staging...

Halo Link uses the Bp Site ID to determine if multiple Halo Link installs belong to the same "practice". When using a developer license for Bp Premier, the Bp Site ID is always 0. Because we cannot differentiate sites by Bp Site ID, all Halo Link installations in staging connected to a developer copy of Bp Premier are treated as authoritative.

Changing which server is authoritative

When migrating or restoring a server, which Halo Link instance is authoritative will likely need to be changed. For more information on what kinds of server changes may require an authoritative change, see the Server configurations page.

For security reasons, changing the authoritative Halo Link instance for a given PMS ID is a manual process requiring human intervention. To change which server is considered authoritative for a site, please contact us and include:

  • The server name
  • The PMS ID
  • The Halo GUID for the Halo Link instance which you want to make authoritative

To minimise interruptions to service, feel free to contact us ahead of any relevant server changes so we can be ready to switch over your authoritative Halo Link instance as quickly as possible once the server changes are complete. Including the server name and PMS ID will also allow us to watch for a new Halo Link instance coming online, reducing some of the back and forth.

Version: 24.514.2668