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. Our current product range is:

The SQL Passthrough allows integrators to run standard SQL queries on practice databases via our cloud API, rather than needing to develop, install, and maintain a local agent for connecting to PMS databases.

Being an unopinionated passthrough API, the SQL Passthrough API also allows maximum flexibility regarding which PMS data and functionality you can access. Designed to allow integrators to switch their current products to Halo Connect with minimal work, the SQL Passthrough API is also perfect for reducing the development costs of new integrations.

Read more about the SQL Passthrough 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 about the Bp Premier API

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 A server which supports one or more practices, on which a PMS may be 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 server The main server for a practice which integrators can connect to. Link
Non-authoritative server Secondary server(s) for a practice which integrators can not 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 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 sites

One of the reasons Halo has its own site identification system is to be able to represent a practice running multiple servers. This is common if:

  1. The practice is migrating servers, and needs to temporarily run two servers to ensure uptime during the switch.
  2. The practice runs both a production server and a backup server, which is meant to mirror the production server.

In both cases, only one server should be contactable by integrators at a given point in time. We call that server the authoritative server, and any secondary servers non-authoritative.

Trying to query a non-authoritative server will result in a 403 Forbidden error. This can be handled using a workflow similar to that outlined below.

Halo GUID workflows

Initial fetch of a site's Halo GUID

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

  1. Request the PMS Site ID from the practice.
  2. Store the PMS Site ID for later reference.
  3. Use the Get Halo GUIDs API endpoint to trade the PMS Site ID for the site's current authoritative Halo GUID.
  4. 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.
  5. Store or cache the Halo GUID for that site for use when sending queries.
  6. Recommended: Store the name returned by the Get Halo GUID endpoint as well, to be able to detect future changes.

For step 1, see the Halo & Bp guide for more information about Bp Premier.

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:

  1. Send a query to a site using a certain Halo GUID.
  2. Receive a 403 Forbidden error.
  3. Retrieve the PMS Site ID from storage.
  4. Use the Get Halo GUIDs API endpoint to trade the PMS Site ID for the site's current authoritative Halo GUID.
  5. Check if the Halo GUID returned by the endpoint is different to the Halo GUID used to send the query.
  6. 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.
  7. If so, update the stored or cached Halo GUID for that site, or flag the change for manual review. If not, contact Halo Support.

Read more...

SQL Passthrough API Bp Premier API