Skip to content

Advanced

The following is a collection of more advanced topics regarding Halo Cloud.

Query routing

Halo Cloud routes queries to specific practices based on their Halo GUID. Specifically:

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

Handling Halo GUID changes

A practice's Halo GUID may occasionally change, usually due to a practice split or merger, or a significant server infrastructure change. When this happens, integrators will receive a 403 Forbidden error when trying to query the practice.

Handling such errors is often a simple process, and can possibly be automated. Although if a practice's secondary identifier(s) have changed, we recommend integrators reach out to the practice as this could signify a change to the business structure which may affect your product. If not, it's likely the cause was an infrastructure change, in which case it is up to the integrator whether they want to check with the practice.

To resolve such issues, we recommend:

  1. When onboarding a practice, record their PMS ID and secondary identifier(s).
  2. Upon receiving a 403 Forbidden error, use the Get Halo GUIDs API endpoint to trade the practice's PMS ID for their current Halo GUID.
  3. Compare the practice's current and previous Halo GUID and secondary identifier(s).
  4. If the secondary identifier(s) have changed, contact the practice to confirm any business changes.
  5. If the Halo GUID has changed, you may choose to do some combination of:
  6. Contact the practice to confirm what changed.
    • Contact Halo Support to confirm what changed, as we have likely already discussed the change with the practice.
    • Switch to using the new Halo GUID for sending queries, which should resolve the 403 errors.
  7. If neither the Halo GUID nor secondary identifier(s) have changed and you continue to receive 403 errors, please contact Halo Support.

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.

Version: 25.527.5449