Skip to content

Server configuration

When installed on the same server as the PMS database, Halo Link should run with no issues. However, more complex server setups and certain types of server modifications may impact Halo Link's connection to the PMS database. This page details what you need to know and when to contact Halo Support.

Jump to...

Definitions Switching Halo Link instances Multi-server setups Server changes quick guide

Contact us when...

  • You're migrating or restoring a server, as we may need to reconfigure Halo Link to allow integrators to query your new server. Otherwise, integrations may query the wrong server or not be able to query your practice at all.
    • For security reasons, this process requires manual intervention by Halo Support after the server changes are complete.
    • To decrease downtime, feel free to contact us ahead of time so we can be ready to restore services as quickly as possible.
  • PMS data isn't updating correctly or integrations are showing incorrect data. While this could be because of the integration, if you have recently changed something with the server or all integrations are affected, this may be due to an issue with Halo Link.
  • If you have any questions or concerns. We're happy to discuss your server setup in order to identify what you might need to watch out for, or how to include Halo Connect in your current processes.

Contact us

Definitions

Term Definition More info
Primary server The server on which a PMS database is installed and which the PMS client software connects to. Link
Secondary server(s) Any other servers used by the practice which are not a primary server, including database backups. Link
Halo Cloud Halo Connect's collection of API products for integrators. Link
Halo Link Halo Connect's local agent which connects to PMS databases to enable communication with Halo Cloud. Link
PMS ID A unique identifier assigned to each practice by a PMS vendor. Usually can be found in the PMS software's UI.
Link GUID A unique Halo Connect identifier for each Halo Link instance. Occasionally used by Halo Support.
Halo GUID A unique Halo Connect identifier for each PMS database a Halo Link instance connects to. Tied to the database's PMS ID. Used by integrators to route queries. Link

Multi-server setups

Primary vs secondary servers

When dealing with multi-server setups, we use the following definitions:

  • Primary server: The server on which a PMS database is installed and which the PMS client software used by practice staff connects to.
  • Secondary server(s): Any other servers used by the practice which are not a primary server. Some secondary servers may also have the PMS database installed, but are considered secondary because they are not connected to the PMS client software which practice staff use. For example, servers used for database backups.

We recommend installing Halo Link instance on the primary server to make maintenance easier. However, Halo Link can be installed on a secondary server by installing Halo Link via the installation wizard or command line and specifying the appropriate database hostname.

If you do want to install Halo Link on a secondary server, here are a few things to consider:

  • Increased risk of service disruptions due to connectivity issues. Any connection issues between the two servers will result in a service disruption for Halo Link, and therefore any integrations which connect to the PMS database via Halo Cloud.
  • Changes to the primary server may require updates to the secondary server. For example, if the primary server is migrated and the database hostname changes, the database hostname Halo Link is looking for will also have to be updated.
  • Installing or updating the PMS database may install Halo Link on the primary server. If this happens, the new Halo Link install on the primary server should not impact integrations. However this Halo Link instance will still use resources and bandwidth, as it will still receive updates and send heartbeats unless disabled.

Running multiple servers

When running multiple servers, whether temporarily or permanently, practices may end up with multiple instances of Halo Link running. Integrators will only be able to connect to one per practice, so please ensure your connection is configured correctly. If you have any questions or need to switch Halo Link instances then please contact Support.

When running multiple servers long term we recommend uninstalling or disabling any secondary Halo Link instances. However, please note:

  • If you uninstall Halo Link, it may be reinstalled when cloning the primary server or when installing or updating the PMS software. For example, Halo Link is bundled with Bp Premier and Zedmed.
  • If you disable the Halo Link service, it may restart itself when we release an update. Please also disable the Halo Link Updater scheduled task to prevent this.

For security and performance reasons, if a practice has multiple instances of Halo Link running, integrators can only connect to and query one of them. This prevents data loss and desync if integrators are querying multiple databases which may not be in sync, and mitigates various security risks.

Whether a Halo Link instance can be queries by integrators is decided by the following process:

  1. When Halo Link is installed it looks for a PMS database, fetches the PMS ID linked to that database, then checks whether our systems have seen that PMS ID before.
  2. If the PMS ID is new, a connection is established. Integrators will be able to query the database once enabled in the PMS software.
  3. If the PMS ID is already registered with another Halo Link instance, the new instance is quarantined. Integrator queries will continue to be routed to the old Halo Link instance.

When performing a server migration or other change that results in new Halo Link instances, practices will need to contact Halo Support to have their connection switched over to the new Halo Link instance. As a security precaution, this is a manual step.

Server changes

When upgrading, migrating, cloning, restoring, or otherwise changing the practice servers, there is a chance that Halo Link may be impacted.

Change Action required More info
Server OS upgrade No action required. Link
Server migration Install Halo Link on the new server, uninstall from old server, and send Halo Support the practice's PMS ID (e.g. Bp Site ID). Link
Server clones and restoration Uninstall unwanted Halo Link copies and restart wanted copies. Link

General guidance

As a general rule, Halo Link should not be impacted by server changes if the change only affects one server.

Complications tend to arise if the changes:

  • Affect multiple servers, such as cloning a server or restoring a backup to a new server; or
  • Affect Halo Link's registry values.

For example, cloning a server can result in two Halo Link instances with identical configurations, which can confuse our systems.

If you have any concerns or experience any issues with integrations after server changes, please contact Halo Connect Support for further assistance.

Server migrations

If a full server migration has taken place, you will need to work through the following migration guide in order to allow integrators to connect to and extract from the new server.

Step 1: Check the new server

Because Halo Link is bundled with some PMS software, Halo link may already be installed on your new server.

  1. Navigate to the Services application on your Windows server.
  2. To verify that Halo Link is installed, scroll down and locate "Halo Link Service" and "Halo Link Updater". If those services do not exist, Halo Link is not installed.
  3. If Halo Link is not installed, work through the system requirements and installation guide, then re-run the installer, either:
    1. A Halo Link installer
    2. A PMS installer which includes Halo Link
  4. If Halo Link is still not installed, please contact Halo Connect Support for further assistance.

Step 2: Finalise migration

  1. Uninstall Halo Link from the old server.
  2. Contact Halo Support and share the PMS ID (e.g. Bp Site ID) and name of the new server. Our team can then reconfigure Halo Link to allow integrators to query your new server.

Restoration or cloning

When a server is restored from a backup or the server is cloned, it will clone the pre-existing instance of Halo Link, creating two instances of Halo Link with the same Halo GUID. This causes a conflict between the two instances associated with the practice, which requires manual intervention by the practice to fix.

  • Clone server to a different VM

    If the server has been cloned on a different virtual machine, the unwanted copy of Halo Link will need to be uninstalled. Once it is uninstalled, the wanted copy should be restarted to open a new session and reset its connection to Halo Cloud.

  • Restore to same server

    If the server has been restored from a backup on the same server, the Halo link service will need to be stopped, then restarted. This will reset its connection to Halo Cloud.

Advanced

Authoritative vs non-authoritative

When talking about Halo Link instances which integrators can and can't connect to, we use the terms "authoritative" and "non-authoritative".

Term Definition More info
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 integrations are not allowed to connect to. Link

Each Halo Link instance assigns a unique identifier to each PMS database it connects to -- this is what we call a Halo GUID. This allows integrators to route queries to specific practice databases using their Halo GUID.

Because a Halo GUID is also linked to the PMS ID for that PMS database, which is usually based on a license, it also allows us to detect when two Halo Link instances are trying to connect to two PMS databases using the same PMS license. 

graph TB
    subgraph Practice servers
        direction BT
        subgraph Primary server
            direction BT
            PMS1["PMS Database (PMS ID 1234)"]
            HL1["Halo Link (Halo GUID abcd)"]
            HL1 --> PMS1
        end
        subgraph Secondary server
            direction BT
            PMS2["PMS Database (PMS ID 1234)"]
            HL2["Halo Link (Halo GUID wxyz)"]
            HL2 --> PMS2
        end
    end

This usually happens if:

  1. The practice has multiple servers which have the PMS database installed. This is usually due to backup systems creating duplicates of the practice's server.
  2. The practice is migrating servers and needs to temporarily run two servers to ensure uptime during the switch.

For security reasons, we restrict integration access for each practice to only one Halo Link instance, and therefore to only one PMS database. Specifically, if a new Halo Link instance appears in our systems that uses a PMS ID that is already in use, it will be automatically quarantined until we are instructed by the practice to enable it.

We use the following terminology to differentiate the Halo Link instances:

  • The authoritative Halo Link instance is the Halo Link instance connected to the PMS database which integrations should be connecting to.
  • Non-authoritative Halo Link instances are any Halo Link instances installed on other servers which integrations should not be able to connect to. These can include backup, testing, and migration servers.
Which Halo Link instance should be authoritative?

Integrations should only be connecting to the PMS database which the PMS client that practice staff use is connected to. The authoritative Halo Link instance should be the one connected to that PMS database. 

graph LR
    HC[Halo Cloud APIs]

    I1[PMS integration] --> HC
    I2[PMS integration] --> HC
    I3[PMS integration] --> HC

    subgraph Practice servers
        subgraph Primary server
            BP1[PMS database]
            HL1["Halo Link (authoritative)"]
            HL1 --> BP1
        end
        subgraph Secondary backup server
            direction LR
            BP2[PMS database]
            HL2["Halo Link (non-authoritative)"]
            HL2 --> BP2
        end
    end

    HC --> HL1

    subgraph Practice computers
        subgraph Staff computer
            BP1 --> C1[PMS Client]
        end
        subgraph Staff computer
            BP1 --> C2[PMS Client]
        end
        subgraph Staff computer
            BP1 --> C3[PMS Client]
        end
    end

Setting the authoritative Halo Link instance correctly is important to avoid:

  • Data degradation and desynchronisation due to some integrator queries going to one database and other queries going to the other database, resulting in the data in the two databases becoming different.
  • Backup corruption where a backup is meant to be a snapshot of the PMS database at a specific time, but integrator queries have caused changes since that time.
  • Incorrect data in the PMS client and/or integrations where the PMS client and/or integrations are pulling data from one database, but the other database is the one receiving updates.

For integrators: Handling 403 Forbidden errors

If an integration tries to query a non-authoritative Halo Link instance, it will receive a 403 Forbidden error. If that Halo GUID worked previously, this is likely a sign the practice has done a server migration or similar and now has a new authoritative Halo Link instance, which has a different Halo GUID.

To avoid service interruptions, integrations could automatically handle 403 errors by fetching the practice's new Halo GUID.

Which server is authoritative?

Halo Link decides whether a server is authoritative or not at installation. This is noted in Halo Link's logs.

Generally, the first installation of Halo Link for a PMS ID will automatically be set as authoritative. Subsequent installations which try to connect to a PMS database with the same ID will automatically be set as non-authoritative, whether or not Halo Link is being installed on the same server or a different server.

For Bp Premier integrators in staging...

Halo Link uses the Bp Site ID to determine if multiple Halo Link installs belong to the same "practice". When using a developer license for Bp Premier, the Bp Site ID is always 0. Because we cannot differentiate sites by Bp Site ID, all Halo Link installations in staging connected to a developer copy of Bp Premier are treated as authoritative.

Prev: Updating Halo Link Next: Halo Link log files

Version: 25.113.4249