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.

Quotas and rate limits

In order to protect practice servers and integrators from performance issues due to spikes in query rates, we apply a rate limit to queries in both staging and production. Over a rolling 5 second period, integrators can send at most 15 queries total of the following types:

  • SQL Passthrough immediate query POSTs
  • FHIR API POSTs
  • FHIR API GETs

The rate limit does not apply to SQL Passthrough asynchronous queries.

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.

Webhook notifications

This feature is considered experimental while we gather feedback on its suitability. While experimental, it may receive breaking changes at any time. Do not rely on this feature in production until it is no longer experimental.

Available for:

  • Async queries
  • Registered queries

Integrators can be notified of completed async and registered queries via webhooks, once the feature has been configured for their subscription. This removes the need to poll Halo Cloud to check for new results.

For security reasons, the webhook payload includes as little data as possible. It does not include the query result, due to risks around who might see that data or how it might be stored. Webhooks must also be configured for an integrator’s subscription, rather than being a per-query option. This allows us to ensure the webhook payload goes to a designated, pre-negotiated, secure URL or URL pattern.

The webhook notifications work as follows:

  • When an async or registered query completes successfully, a webhook will be sent to the specified URL.
  • All webhooks are sent as a HTTP POST.
  • The webhook payload will only contain:
    • The Halo GUID the query was sent to
    • The Query GUID of the query run
    • The type of source query (async or registered)
  • There is no retry logic in the webhooks. We only send each webhook once.

See Getting started for how to configure webhook notifications.

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