Server configuration

Halo Link works best when installed on the same server as the PMS database. Installing Halo Link on any other server adds maintenance complexity, which is detailed below. Additionally, when making any changes to the configuration of a server that Halo Link is installed on or connected to, certain considerations need to be made. The following details how Halo Link handles such situations, and what needs to be considered for your server configuration.

Jump to...

Definitions Managing multiple Halo Links Multi-server setups Server changes quick guide

Contact us when...

You're migrating or restoring a server, as we may need to reconfigure the instance of Halo Link associated with your PMS ID. 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 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.	Link
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
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.	Link
Halo GUID	A unique identifier for each PMS database a Halo Link instance is connected to.	Link
PMS ID	A unique identifier assigned by PMS software that represents a practice in some way.

Managing multiple Halo Link instances: authoritative vs non-authoritative

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:

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.
The practice is migrating servers and needs to temporarily run two servers to ensure uptime during the switch.

In both cases, we restrict integration access for that practice to only one Halo Link instance, and therefore to only one PMS database. 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.

Changing which server is authoritative

When migrating or restoring a server, which Halo Link instance is authoritative will likely need to be changed. For more information on what kinds of server changes may require an authoritative change, see the Server configurations page.

For security reasons, changing the authoritative Halo Link instance for a given PMS ID is a manual process requiring human intervention. To change which server is considered authoritative for a practice, please contact us and include:

The server name
The PMS ID
The Halo GUID for the Halo Link instance which you want to make authoritative

To minimise interruptions to service, feel free to contact us ahead of any relevant server changes so we can be ready to switch over your authoritative Halo Link instance as quickly as possible once the server changes are complete. Including the server name and PMS ID will also allow us to watch for a new Halo Link instance coming online, reducing some of the back and forth.

Contact us to change the authoritative Halo Link instance for your practice

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 that practice staff use 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.

We recommend installing the authoritative 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, there are a few things that should be considered:

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 be set as non-authoritative and therefore should not impact integrations, however it still means there is an extra program on the primary server which is connected to the internet, receives updates, and sends heartbeats back to Halo Cloud every minute.
- Note: Some PMS software may be able to detect an existing instance of Halo Link. This will depend on the PMS and what checks their installer does.

Running multiple servers

Some practices run multiple servers permanently. To ensure Halo Link is running correctly and there are no service disruptions to the practice, please:

Authoritative vs non-authoritative: As above, you will need to ensure the authoritative Halo Link instance is correctly set. Whenever you make changes to either server which may affect the registry or cause Halo Link to be re-installed, cloned, or otherwise affected, please check that server's authoritative status in Halo Link's logs.
Multiple Halo GUIDs: Integrators use the Halo GUID assigned to the authoritative Halo Link instance to route queries to the correct practice. Each Halo Link instance has its own Halo GUID, including any non-authoritative Halo Link instances. So when sharing the Halo GUID with an integrator or with Halo Support, please ensure it is the Halo GUID for the correct Halo Link instance.

When running multiple servers permanently, we recommend uninstalling or disabling any non-authoritative Halo Link instances first. 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 most Bp Premier data updates and service packs.
If you disable the Halo Link service, it may restart itself when we release an update. Therefore, please also disable the Halo Link Updater scheduled task to prevent this.

Server changes

When upgrading, migrating, cloning, restoring, or otherwise changing the practice servers, there is a chance that Halo Link may be impacted. The following details when this can happen and what can be done about it.

Quick guide

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 Connect the new server's Halo GUID.	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:

Halo Link's registry values have not changed. The Halo Link installer will honour any existing registry values, so even if Halo Link must be reinstalled, as long the registry has not changed, then Halo Link will reconnect using its previous settings.
Each Halo Link instance has a unique Halo GUID. Since Halo GUIDs are used for routing queries from integrations, if two Halo Link instances have the same Halo GUID this can cause unpredictable behaviour. This is usually caused by backups or server clones which copy the Halo Link registry values and have Halo Link installed and running.

To check if Halo Link has been affected by server changes, we recommend:

Before:
- Note the Halo GUID(s) found in the Halo Link logs or registry for later for each instance of Halo Link which may be affected.
After:
- Check Halo Link's registry values exist.
- If modifying one server, check the Halo GUID is the same as before and that its logs state it is authoritative.
- If modifying multiple servers with Halo Link installed, check each has a unique Halo GUID. If the authoritative Halo Link instance should not have changed, check its Halo GUID is the same as before and that its logs state it is authoritative.
- Check the Halo Link Service is running and the Halo Link Updater service is present and set to manual, as per the screenshot below.
- Check the Halo Link scheduled updater task is running.

Server OS upgrades

Upgrading a server's operating system is unlikely to cause issues with Halo Link, as it rarely affects the registry.

If you have any concerns or experience any issues with integrations 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, 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.

Navigate to the services application on your Windows server.
To verify that Halo Link is installed, scroll down and locate "Halo Link Service" and "Halo Link Updater".
If Halo Link is not installed, work through the system requirements and installation guide, then check again. If Halo Link is still not installed, please contact Halo Connect Support for further assistance.

graph LR
    id1{"Check if 
    Halo Link is installed 
    on the new server"}
    id2[Review Halo Link requirements]
    id3[Install Halo Link]
    id4{Installed correctly?}
    id5[Contact Halo Support]    
    id1--No -->id2-->id3-->id4
    id4--No -->id5
    id6[Go to Step 2]
    id1--Yes-->id6
    id4--Yes-->id6

Step 2: Finalise migration

Uninstall Halo Link from the old server.
Retrieve the Halo GUID of the Halo Link installation on the new server.
Contact Halo Connect Support and share the retrieved Halo GUID. This allows our team to change which instance of Halo Link associated with this PMS (Practice Management Software) ID is set as authoritative, and able to be queried by integrators.

graph LR
    id6[Uninstall Halo Link from the old server]
    id7[Retrieve the Halo GUID of the new server]
    id8[Send Halo Support the new server's Halo GUID]
    id6-->id7-->id8

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.

Prev: Updating Halo Link Next: Halo Link log files