Skip to content

Halo Connect & Zedmed

For security reasons, this page obscures some details of how Zedmed works. Please see the Zedmed documentation for clarification.

Jump to...

Definitions Basics For practices For integrators

Definitions

Many of the following terms are explained in more detail elsewhere in these docs. The following is only a quick reference guide.

Term Definition More info
On-premise or on-prem server A PC or server, and the software running on it, which can be physically accessed by practice staff and/or an integrator.
Cloud server A server running in the cloud which can not be physically accessed by practice staff and/or an integrator.
Practice server(s) A server or set of servers which support one or more practices, on which the Zedmed database and Halo Link are installed.
Multiple databases Zedmed software includes a pair of databases. This setup will often be referred to as "multiple databases" or "multi-database". See Multiple databases.
Multiple installations Zedmed software can be installed multiple times on the same server. This is how Zedmed's cloud-hosted product works. This will often be referred to as "multiple installations" or "multi-installation". See Server setups.
PMS ID A unique identifier assigned by PMS software that represents a practice in some way. See Identifiers.
Zedmed Database ID Zedmed's unique identifier for a Zedmed database (or databases, if backups are taken) belonging to one practice. This is used by Halo Connect as the PMS ID for Zedmed. See Identifiers.
Halo Cloud Halo Connect's collection of API products. Halo Cloud overview
Halo Link Halo Connect's local agent which connects to PMS databases to enable communication with Halo Cloud. Halo Link overview
Halo GUID A unique identifier for each PMS database a Halo Link instance is connected to, such as a Zedmed database. See Identifiers.
Link GUID A unique identifier for each Halo Link instance. See Identifiers.

In the Halo API reference, the practiceManagementSiteId for a Zedmed practice is the Zedmed Database ID.

Basics

Supported server setups

Halo Connect supports both single installation and multiple installation setups, on both cloud and on-premise servers.

Halo Link only has to be installed once on servers with multiple Zedmed installations. It will handle routing queries appropriately using Zedmed Database IDs and Halo GUIDs.

graph LR
    HC[Halo Cloud APIs]

    I1[Integration 1] <--> HC
    I2[Integration 2] <--> HC
    I3[Integration 3] <--> HC
    I4[Integration 4] <--> HC

    subgraph Server
        Z1[Zedmed 2]
        Z2[Zedmed 1]
        HL1["Halo Link"]
        HL1 <--> Z1
        HL1 <--> Z2
    end

    HC <--> HL1

    subgraph Practice computers
        subgraph Staff computer
            Z1 <--> C1[PMS Client]
        end
        subgraph Staff computer
            Z1 <--> C2[PMS Client]
        end
    end

    subgraph Practice computers
        subgraph Staff computer
            Z2 <--> C3[PMS Client]
        end
        subgraph Staff computer
            Z2 <--> C4[PMS Client]
        end
    end

For practices: A valid INI file is required

Halo Link uses Zedmed's INI file to identify all the Zedmed databases installed on a server. If the INI file is invalid or missing, Halo Link may not connect to the database(s) correctly.

To install Halo Link on a different server to that which has the Zedmed database(s), please contact support to discuss how to do this.

Zedmed controls integrator access

Halo Connect's products allow integrators to run queries on practice servers, but we do not control which practices integrators can connect to or what data integrators can access. Access control remains with Zedmed and the practices.

  • Enabling integrators: Integrators can only connect to a practice via Halo Connect if they have been enabled by that practice within the Zedmed UI.
  • Data access: Integrators can only access the database tables and stored procedures Zedmed have given them access to.

Halo Connect has its own access and authorisation systems which build on Zedmed's systems, but these do not replace any of Zedmed's own systems.

Identifier Description Stability Found in...
Zedmed Database ID Zedmed's unique identifier for a Zedmed database belonging to one practice. Unlikely to change. Zedmed UI
Link GUID A unique identifier for each Halo Link instance. Unlikely to change for a given Halo Link install. Halo Link logs and registry
Halo GUID A unique identifier for each Zedmed database a Halo Link instance is connected to. Created when Halo Link is installed. Re-created if Halo Link is reinstalled. Halo Link logs and registry
  • Backup copies of a Zedmed database will have the same database ID.
  • Integrators can trade PMS IDs such as the Zedmed Database ID for Halo GUIDs using the Get Halo GUIDs API endpoint.
  • If a server only has one Zedmed database installed, it will have one of each of the above identifiers.
  • If a server has multiple Zedmed databases installed, it will have:
    • One Link GUID, as Halo Link only needs to be installed once.
    • Multiple Zedmed Database IDs, one for each database.
    • Multiple Halo GUIDs, one for each database.

For practices: Authoritative and multiple Zedmed installations

If you run multiple Zedmed installations on one server, they must share one authoritative Halo Link instance. Authoritative can not be set at the individual PMS database level. It can only be set based on the Halo Link instance.

When multiple instances of Halo Link connect to PMS databases that use the same PMS ID, one instance will be set to authoritative while the rest will be set to non-authoritative. Integrators can only query authoritative instances, so ensuring the correct instance is authoritative is key.

Practices vs clinics

Zedmed has a concept of multiple "clinics" belonging to one "practice" -- that is, multiple clinics that share one Zedmed license and database pair. These clinics often belong to the same business entity, but have different physical locations.

Halo Link and Halo Cloud operate at the practice level, not the clinic level. It is up to integrators to account for clinics in their integrations, such as by filtering database records based on clinic.

For practices

Enabling integrations

Halo Link does not give integrators access to any practice data until they are enabled in the Zedmed UI.

You will also need to provide the integrator with your Zedmed Database ID. This will allow them to fetch your Halo GUID from Halo Cloud, which they will use like an address or username to send queries to your server.

Finding your Zedmed Database ID

Your Zedmed Database ID can be found in the Zedmed UI, in the status bar at the bottom.

For integrators

Staging vs Production differences

When setting up your application and build processes, the following differences should be taken into account in the different environments.

Staging

  • Your application should connect to the staging URL for the relevant Halo Cloud API.
  • Your application will need to use your Halo Cloud staging subscription to authenticate with Halo Cloud.
  • Halo Link instances installed on developer and test machines must be set to Stage.
  • There are no restrictions or quotas applied to Halo Cloud usage in staging.

Production

  • Your application should connect to the production URL for the relevant Halo Cloud API.
  • Your application will need to use your Halo Cloud production subscription to authenticate with Halo Cloud.
  • Halo Cloud production uses quotas and rate limiting to protect our cloud services and practice servers, plus some additional security requirements.

Staging and Production can not be mixed

As a security precaution, a production instance of Halo Link will not connect to an instance of Zedmed that uses a developer license.

  • To connect to a developer license instance of Zedmed, Halo Link must be set to Stage.
  • To connect to a non-developer instance of Zedmed, Halo Link should be set to Production.

See the instructions for setting Halo Link's environment for more information.

Exchanging Zedmed Database IDs for Halo GUIDs

Halo Cloud uses Halo GUIDs to route integrator's queries. To send a query to a specific practice or development machine, you will need the corresponding Halo GUID.

To make it easier for integrators to get a practice's Halo GUID, Halo Cloud includes an API endpoint for getting Halo GUIDs from PMS IDs (such as Zedmed Database IDs). The Halo GUID can be found in the return data under practiceMetadata.practiceManagementSiteId.

Secondary identifiers

Zedmed Database IDs are the primary identifier Halo Connect uses for Zedmed practices. However, we also record a secondary piece of identification when onboarding practices. This allows integrators to check they are querying the right practice based on a combination of data points, and not just one value which could easily be copied or typed wrong.

While integrators can not query practices which have not enabled them, reducing the risk of querying the wrong practice, there is still a chance that mixing up PMS IDs could result in an integrator querying data from the wrong practice, and potentially then displaying that data to the wrong people. This could have serious repercussions, so please make use of the secondary identifier.

For Zedmed, the secondary identifier is the practice name.

This is displayed in the return data for both the Get Halo GUID and Get status endpoints. It can be found under practiceMetadata.practiceName.

Onboarding and troubleshooting

For more information on how to fetch a practice's Halo GUID and how to handle errors and Halo GUID changes, see Getting started with Halo Cloud.

Fake Zedmed Database IDs for developer license copies of Zedmed

When running Zedmed using a developer license, the database does not receive a unique Database ID. When Halo Link connects to such a database, it will instead assign the database a fake Zedmed Database ID.

The fake Zedmed Database ID is the first eight characters of the corresponding Halo GUID.

Halo GUIDs can be found in either of Halo Link's:

A fake Zedmed Database ID can be used with the Get Halo GUID endpoint. The endpoint will not accept non-unique developer license Database IDs.

Accessing multiple databases with the SQL Passthrough API

Zedmed has multiple databases. By default, Halo Link connects to the patient database.

To specify which database to query, for both immediate and async queries, include the catalogue parameter in the query's request body.

To find the specific names of the databases, check the Zedmed docs or your Zedmed instance.

Version: 24.1029.3843