Introduction

Halo Link is a local agent that connects a Practice Management System (PMS) database to the Halo Connect Cloud APIs. This allows integrations to connect to a practice's PMS database via Halo's APIs, instead of installing their own agent directly on the practice's server.

Jump to...

Definitions Basics For practices For integrators

Supported PMSs

Halo Link currently works with the following PMS software:

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.
PMS ID	A unique identifier assigned by the PMS provider that represents a practice in some way.
Halo Cloud	Halo Connect's collection of API products.	Link
Halo Link	Halo Connect's local agent which connects to PMS databases to enable communication with Halo Cloud.
Halo GUID	A unique identifier for each PMS database a Halo Link instance is connected to.	Link
Authoritative Halo Link instance	The singular Halo Link instance integrations are allowed to connect to for a given practice.	Link
Non-authoritative Halo Link instance(s)	Any other Halo Link instances that integrations are not allowed to connect to.	Link

Basics

Halo Link acts as a bridge between PMS databases and Halo Cloud, allowing integrators to query practice databases without needing to develop, install, and maintain their own local agent. It works for all combinations of:

On-prem vs cloud servers
Single database vs multi-database PMS systems
Single instance vs multiple instance PMS installations

See Server configurations for more information about configuring Halo Link on various server setups.

Server configuration examples

On-prem practice serverMulti-instance PMS cloud server

graph LR
    I1[Integration A]
    I2[Integration B]
    I3[Integration C]

    H1(Halo APIs)

    I1 <--> H1
    I2 <--> H1
    I3 <--> H1

    subgraph Practice
        subgraph PS [Practice server]
            S[(PMS DB)]
            H2(Halo Link agent)
            H2 <--> S
        end

        subgraph Practice computers
            subgraph Staff computer
                S <--> C1[PMS Client]
            end
            subgraph Staff computer
                S <--> C2[PMS Client]
            end
            subgraph Staff computer
                S <--> C3[PMS Client]
            end
        end
    end
    H1 <--> H2

graph LR
    I1[Integration A]
    I2[Integration B]
    I3[Integration C]

    H1(Halo APIs)

    I1 <--> H1
    I2 <--> H1
    I3 <--> H1

    subgraph PMS cloud server
        H2(Halo Link agent)
        H2 <--> S1[(PMS DB 1)]
        H2 <--> S2[(PMS DB 2)]
        H2 <--> S3[(PMS DB 3)]
    end

    H1 <--> H2

    subgraph P3[Practice 3]
        subgraph Staff computer
            S3 <--> C5[PMS Client]
        end
        subgraph Staff computer
            S3 <--> C6[PMS Client]
        end
    end

    subgraph P2[Practice 2]
        subgraph Staff computer
            S2 <--> C1[PMS Client]
        end
        subgraph Staff computer
            S2 <--> C2[PMS Client]
        end
    end

    subgraph P1[Practice 1]
        subgraph Staff computer
            S1 <--> C3[PMS Client]
        end
        subgraph Staff computer
            S1 <--> C4[PMS Client]
        end
    end

Limitations

Halo Link currently does not:

Interact with front-end PMS software such as the UI clients practice staff use. Halo Link 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 Link builds on top of existing PMS authorisation and authentication systems.
Enable queries to be fanned out over multiple practices. Queries can only be sent to one practice at a time.

Authentication and authorisation

Halo Connect leverages the existing authentication and authorisation systems of the PMSs we integrate with, and adds additional systems on top.

Integrators must onboard with the PMS provider as usual and receive the required access and credentials
Practices enable and disable integrations as usual, and disabled integrations can not communicate with the practice database via Halo Connect.

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.

PMS IDs, Halo GUIDs, and Link GUIDs

There are a few identifiers you may need to know about when using Halo Connect systems.

Identifier	Description	Use
PMS ID	A unique identifier assigned by the PMS provider to each practice.	Given by practices to integrators to identify their practice with Halo Connect systems.
Link GUID	A unique identifier for each Halo Link instance.	Used to identify Halo Link instances, usually by Halo Support.
Halo GUID	A unique identifier for each PMS database a Halo Link instance is connected to.	Used by integrators to route queries to the right practice.

PMS IDs are usually found in the PMS's UI.
Integrators can trade PMS IDs for Halo GUIDs using the Get Halo GUIDs API endpoint.
Link GUIDs and Halo GUIDs can be found in Halo Link's logs and registry entries.

Logs

For instructions on how to find Halo Link's logs please see the Support pages.

Support

Please contact Support if you have any questions or concerns. Troubleshooting tips are also available.

Release notes

The Release notes contain details of all releases for both Halo Link and Halo Cloud. Look for the icon for Halo Link-specific changes.

For practices

Installation and updates

See the Halo Link installation page for general installation instructions.

For details regarding how Halo Link interacts with various server configurations, such as backup servers and servers running multiple PMS instances, see Server configurations.

No matter how many PMS databases are installed on a server, a single server should only have Halo Link installed once.

Halo Link includes an auto-updater to ensure practices always have the latest version. For more information, see Updating.

Server configurations and changes

Halo Link is designed to operate on most server configurations, however backups, migrations, and more advanced setups can require extra steps.

In particular, Halo Connect only allows integrators to talk to one PMS database per practice. This is called the authoritative server. When a Halo Link instance connects to a database that has the same PMS ID as another already-connected database, the new database is marked as non-authoritative. This can happen due to server backups and migrations as detailed in the Server configurations page.

The authoritative server should be the same server the practice staff's PMS clients talk to. If the wrong server is marked as authoritative, this may cause all integrations to query the wrong database, resulting in practice staff and customers receiving incorrect data.

For security reasons, changing which server is authoritative for a practice requires contacting Support.

Enabling integrations

Installing Halo Link does not mean integrations can automatically connect to your practice's database. To enable an integration you will need to:

Enable the integration in the PMS UI as per usual processes. See the docs for your PMS for instructions.
Give the integrator your PMS ID (the unique ID assigned to your practice by your PMS provider). They will trade this for a Halo GUID (Halo's unique ID for practices) which they can use like an address or username to send queries to the right practice.

For integrators

Environments

Halo Connect has two public environments:

Staging: for development and testing
Production: for live use with practices

Integrators who are testing or developing for Halo Connect products will be given a subscription key for staging. This restricts access to Halo Link installations which are set to Stage. This is a security precaution to prevent accidental interactions with live practice servers.

Installing Halo Link in staging requires an extra step. See the For integrators section of the Halo Link installation page for more information.

See the environments section of the Halo Cloud overview for details about moving from staging to production.

Query routing

Halo Connect systems uniquely identify practices using Halo GUIDs. This is not the same as the practice's PMS ID, which is assigned by the PMS provider.

Halo GUIDs

A Halo GUID uniquely identifies each PMS database a Halo Link instance is connected to.

This is not to be confused with a Link GUID, which uniquely identify Halo Link instances. If a server is running multiple PMS databases, the Halo Link instance installed on that server will have one Link GUID and multiple Halo GUIDs (one for each database). Both Halo GUIDs and the Link GUID are available in Halo Link's registry entries.

Because Halo GUIDs are assigned by Halo Link installations, they are tied to both the Halo Link instance and the database it is connected to. A server migration may result in Halo GUIDs changing. Server backups can also result in a practice having multiple Halo GUIDs assigned to it. See Server configurations for more information.

When different Halo Link instances connect to different PMS databases which have the same PMS ID, such as due to server backups or migrations, one database is assigned to be the authoritative server, while any others are marked non-authoritative. Integrations can only connect to authoritative servers.

See the Halo Cloud overview for more information on authoritative vs non-authoritative Halo Link instances and how they affect integrations.

Retrieving a Halo GUID

A practice's PMS ID can be traded for their Halo GUID using the Get Halo GUIDs API endpoint. See the Halo Cloud overview for more information about Halo GUID workflows.

Next: Halo Link Installation