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 a variety of 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.

    • 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.

    • 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 specifics 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 PMS database and Halo Link are 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

Basics

Supported PMSs

Halo Cloud currently works with the following PMS software:

Limitations

Halo Cloud currently does not:

  • Interact with front-end PMS software such as the UI clients practice staff use. Halo Cloud only interacts with PMS databases.
  • Allow integrators to access data at practices they have not been enabled for, or for PMS providers they have not signed up with. Halo Cloud builds on top of existing PMS authorisation and authentication systmes.
  • Enable queries to be fanned out over multiple practices. Queries can only be sent to one practice at a time.

Authentication and authorisation

Halo Cloud leverages the existing authentication and authorisation systems of the PMSs it integrates with, and adds additional systems on top. This means:

  • Integrators must onboard with the PMS provider as usual and receive the required access and credentials to be able to run queries on PMS databases via Halo Cloud.
  • Practices enable and disable integrations as usual, and disabled integrations can not communicate with the practice database via Halo Cloud.

Halo Cloud authentication

When you sign up for Halo Cloud you will receive a subscription key which allows you to send queries via Halo Cloud -- though only to practices which have enabled your integration in the PMS software.

See Getting started with Halo Cloud for how to authenticate with Halo Cloud.

PMS database authorisation

Halo Connect does not handle PMS database access authorisation. What data integrators can access is managed by the respective PMS vendor. For this reason, using Halo Cloud requires integrators to have onboarded with the relevant PMS vendor before they can query any practices using that PMS via Halo Cloud.

When an integrator onboards with Halo Connect, we coordinate with the relevant PMS vendor(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.

Security and monitoring

Halo Connect does monitor the health of queries and Halo Link instances connected to our network using metadata. This allows us to proactively work to resolve any service disruptions, and to help practices and integrators with any issues they might encounter.

Halo Connect does not inspect, monitor, or log any data in or retrieved from practice databases, nor do we store any such data, except for practice metadata like practice name and PMS ID. This is used to identify practices for query routing.

Please see our Security overview for more information, particularly regarding our Shared Responsibility Model.

Using Halo Cloud

See Getting started with Halo Cloud for requirements and setup steps.

Query routing

Routing queries to a specific practice requires the following:

  • Each practice's database 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).
  • Practices tend to be aware of what their PMS ID is, so the Get Halo GUIDs endpoint allows integrators to trade PMS IDs for Halo GUIDs. See Halo GUID workflows for more information.

Halo GUID workflows

See Getting started with Halo Cloud for more information about fetching and handling Halo GUIDs.

Each practice receives a unique PMS ID from their PMS provider which Halo Connect uses to identify that practice internally. However, it is possible for multiple PMS databases to use the same PMS ID, such as in the case of server backups or migrations. To avoid data desynchronisation and corruption, Halo Cloud will only allow integrators to query one database for a given PMS ID. We call this the authoritative database, and any others non-authoritative.

Databases using the same PMS ID will have different Halo GUIDs. So if the authoritative database changes, the Halo GUID integrators should use to query that practice will change. This is why we recommend integrators store practices' PMS IDs, as these can be used to fetch the new authoritative Halo GUID.

Next: Getting started with Halo Cloud

Version: 24.529.2820