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.

Recommendations

Each time Halo Link is installed on a new environment, it creates a new "practice" subscription in the Halo Connect system. This results in a Halo GUID being created which you will have to fetch. If done repeatedly and often, it also increases load on our systems. For example, if a test environment reinstalls Halo Link each time it is spun up, and this happens multiple times a day, that will create multiple "practice" records each day.

We would ask integrators please try to avoid implementing such systems. If this is a requirement for your integration, please contact us so we can coordinate processes such as regular clean ups of orphaned Halo GUIDs.

Use the Get status endpoint to check if a practice is live

We make our best effort to detect and resolve practice outages as quickly as possible. However, sometimes a practice server may be uncontactable for a period of time. Querying the practice during an outage will return an appropriate error.

Depending on how your integration works, it may be wise to use the Get status endpoint to check if a practice is live before sending queries. For example, if your integration polls the server regularly or sends several queries at once for data extraction.

Implement exponential backoff in the case of errors

If you do receive errors from a practice server, especially if your integration polls the server frequently, we recommend implementing exponential backoff. This can help by:

  • Saving you money by reducing your usage during an outage.
  • Lightening the load on the server, which may help resolve the issue quicker if it is due to network or server congestion.
  • Reducing the load on Halo Connect systems, which may help resolve the issue quicker if it is due to our cloud systems.

The optimal exponential backoff strategy for your integration will depend on your use case and requirements, but we are happy to discuss options with you. Contact Support if you have any question.

Version: 25.1028.7355