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.

Available APIs

Our long-term goal is to offer a range of API products for various use cases, bridging the gap between various practice management systems. Our current product range is:

SQL Passthrough API

An unopinionated SQL passthrough API which allows integrators to run standard SQL queries on practice databases via Halo Cloud APIs.
- 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
Bp Premier FHIR API

The Bp Premier API is an upcoming API product which will give integrators a new way to interact with Bp Premier, no SQL required.

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 practice server or a development environment which has Halo Link installed.
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

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 Conenct, 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 installation

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 concepts

"Site" definition

A "site" is a server or virtual machine which has Halo Link installed. This is usually a practice server or a development environment belonging to an integrator.

This definition does not necessarily match the definition of "site" used by the various PMS vendors. For example, a Bp Software "site" (a medical practice) may have multiple Halo "sites" (servers with Halo Link installed).

A single Halo and PMS "site" pairing may also support the operations of multiple physical practices and/or practice locations.

Identifying sites by Halo GUID

Every Halo Link installation is given a unique Halo GUID identifier. Integrators must include a Halo GUID when sending queries via Halo Cloud so that Halo can route the query to the appropriate site.

Halo GUID vs PMS Site ID

A site's Halo GUID is not the same as the ID assigned to that site by the PMS it runs.

See the Halo & Bp guide for more information about Bp Premier.

Fetching Halo GUIDs

The Get Halo GUIDs API endpoint allows integrators to trade a practice's PMS Site ID for a Halo GUID.

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. Integrators using developer copies of Bp Premier can fetch the fake Bp Site ID from the Halo Link logs or registry. Fake Bp Site IDs can then be used with the Get Halo GUIDs API endpoint as usual.

See the Bp Premier guide for more information.

Authoritative vs non-authoritative Halo Link instances

Each Halo Link instance is given its own unique identifier -- what we call a Halo GUID. We associate Halo GUIDs with PMS IDs, which identify PMS licenses, in order to detect when one practice is running multiple installations of Halo Link which are connected to different copies of the PMS database. This usually happens if:

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.
The practice is migrating servers and needs to temporarily run two servers to ensure uptime during the switch.

This results in a situation where multiple Halo Link instances with different Halo GUIDs are connected to PMS databases which have the same PMS ID. For example:

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

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.

Halo GUID workflows

Initial fetch of a site's Halo GUID

For onboarding practices running Bp Premier...

See the Halo & Bp guide for more detailed information.

For retrieving a site's Halo GUID the first time:

Request the PMS Site ID from the practice.
Store the PMS Site ID for later reference.
Use the Get Halo GUIDs API endpoint to trade the PMS Site ID for the site's current authoritative Halo GUID.
Recommended: Check the name returned by the Get Halo GUIDs endpoint contains an appropriate value, e.g. is similar enough to the practice's business name to be fairly likely to refer to the correct practice. This is to reduce the risk of querying the wrong practice.
Store or cache the Halo GUID for that site for use when sending queries.
Recommended: Store the name returned by the Get Halo GUID endpoint as well, to be able to detect future 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.

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:

Send a query to a site using a certain Halo GUID.
Receive a 403 Forbidden error.
Retrieve the PMS Site ID from storage.
Use the Get Halo GUIDs API endpoint to trade the PMS Site ID for the site's current authoritative Halo GUID.
Check if the Halo GUID returned by the endpoint is different to the Halo GUID used to send the query.
Recommended: Check if the name returned by the endpoint is the same as it was previously. This can help detect non-standard changes such as practices merging or splitting, which need to be treated differently.
If so, update the stored or cached Halo GUID for that site, or flag the change for manual review. If not, contact Halo Support.