Skip to content

Halo Connect & Bp Premier

For security reasons, this page obscures some details of how Bp Premier works. Please see the Bp Premier 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 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 Bp Premier database and Halo Link are installed.
Bp Site A practice or group of practices running Bp Premier using one license. See below.
PMS ID A unique identifier assigned by PMS software that represents a practice in some way.
Bp Site ID Bp Premier's unique identifier for a Bp Site. This is used by Halo Connect as the PMS ID for Bp Premier. See below.
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, such as a Bp Premier database. Link

In the Halo API reference, the practiceManagementSiteId for a Bp Premier practice is the Bp Site ID.

Basics

Halo Link is bundled with Bp Premier Data Updates and Service Packs, and is installed when Bp Premier is installed or updated. For practices, this simplifies the process of installing Halo Link, and therefore the process of enabling integrations.

See the Halo Link installation guide for more information.

Please note that:

  • Halo Link's requirements must still be met for it to be installed, even if installing via Bp Premier.
  • If you uninstall Halo Link, it will likely be reinstalled next time you install or update Bp Premier.

Bp 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 Bp, and works the same as it did before Halo Connect. Specifically:

  • Enabling integrators: Integrators can only connect to a practice via Halo Connect if they have been enabled by that practice in the 3rd party integrations screen in Bp Premier.
  • Data access: Integrators can only access the database tables and stored procedures Bp have given them access to.

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

Bp Site IDs and Halo GUIDs

A Bp Site ID and a Halo GUID are not the same.

A Bp Site ID is a unique identifier for a Bp Site, allocated by Bp Premier, which can refer to one or more clinics or locations using the same Bp Premier licence. A site could also have one or more servers running Bp Premier. For example, in the case of a live production server and a backup server. These servers would have the same Bp Site ID.

A Halo GUID is a unique identifier for a single Halo Link installation.

If a practice is running multiple servers or has done a server migration since first installing Halo Link, that practice has most likely installed Halo Link multiple times. This would have resulted in multiple different Halo GUIDs being assigned to that practice, and linked to its singular Bp Site ID.

For integrators:

Bp Site IDs and Halo GUIDs work slightly differently in staging and production. This impacts how the Get Halo GUID endpoint should be used in staging as well. See the For integrators section below for more information.

For example:

graph TB
    subgraph Practice
        direction BT
        subgraph Primary server
            direction BT
            BP1[Bp Premier: Site ID 1234]
            HL1[Halo Link: Halo GUID abcd]
            HL1 --> BP1
        end
        subgraph Secondary server
            direction BT
            BP2[Bp Premier: Site ID 1234]
            HL2[Halo Link: Halo GUID wxyz]
            HL2 --> BP2
        end
    end

Each Halo Link instance is given its own unique identifier -- what we call a Halo GUID. For Bp Premier, we associate Halo GUIDs with a Bp Site ID, in order to detect when one practice is running multiple installations of Halo Link which are connected to multiple Bp Premier databases which use the same Bp Premier license. To prevent data degradation and backup corruption, we restrict integration access for each practice to only one Halo Link instance, and therefore to only one Bp Premier database for that practice. This should be the database which the Bp Premier clients used by practice staff connect to.

We call this Halo Link instance the authoritative Halo Link instance, and has the following implications:

  • When migrating practice servers, please notify Halo Connect so we can update which Halo Link instance is designated as authoritative. See the documentation about making changes to practice servers for more information about server migrations.
  • When integrators receive a 403 Forbidden error from querying a site that previously worked, this is likely because the site's authoritative Halo Link instance changed and the query was sent to a now-non-authoritative Halo Link instance which rejected it. See the Halo Cloud overview for more information on handling such situations.

See the Halo Cloud overview for more information about authoritative vs non-authoritative Halo Link instances.

Handling "locations"

Bp Premier has a concept of multiple "locations" belonging to one "practice" -- that is, multiple locations using one Bp Premier license and database. These locations often belong to the same business entity.

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

For practices

Finding your Bp Site ID

Your Bp Site ID can be found in Bp Premier. Select Help > About from the main Bp Premier screen. Your Site ID is displayed in the bottom left of the screen. It should be an integer with no leading zeroes. For example: 12345.

Enabling integrations

Halo Link does not give integrators access to any of your data until you enable them in the 3rd party integrations screen in Bp Premier.

You will also need to provide the integrator with your Bp Site 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.

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, due to environmental differences in both Bp Premier and Halo Connect's products.

Staging

  • Developer and test machines with Bp installed are likely using Bp Premier with a developer license.
  • When using a Developer License, the Bp Site ID for that instance of Bp Premier will be 0.
  • Halo Link will generate a fake Bp Site ID if the Bp Site ID is 0, to give that installation a unique identifier. The fake Bp Site ID can be found in Halo Link's logs.
  • 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.
  • There are no restrictions or quotas applied to Halo Cloud usage in staging.

Production

  • Practice servers running Bp Premier should be using a full license.
  • The Bp Site ID for a full installation of Bp Premier will be a unique identifier and should be an integer with no leading zeroes.
  • Halo Link will use the given Bp Site ID. The Bp Site ID can be found in the Bp Premier UI.
  • 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 Bp Premier that uses a developer license.

  • To connect to a developer license instance of Bp Premier, Halo Link must be set up in staging.
  • To connect to a non-developer instance of Bp Premier, Halo Link should be set up in production.

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

Exchanging Bp Site IDs for Halo GUIDs

Halo Cloud uses Halo GUIDs to route integrator's queries. To send a query to a particular practice, you will therefore need their 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 Bp's Site ID).

Practice onboarding

When onboarding a practice running Bp Premier:

  1. Request the practice's Bp Site ID from the practice staff. See Finding your Bp Site ID for instructions.
  2. Use the Get Halo GUID endpoint to trade the practice's Bp Site ID for their Halo GUID. Always check that the practice name that is also returned matches the practice's business name, or the value they have supplied, to ensure no mistakes were made when entering the Bp Site ID.
    • Note: Some practices do not set the Practice Name field in Bp Premier to their business name. It may be worth checking their practice name when you request their Bp Site ID or, if the value that is returned from the API seems odd, checking it with the practice staff.

    Avoid mixing up practice IDs

    Halo Cloud will not let an integrator query a site where they have not been enabled, however there is still a chance that practices could be mixed up, even if you only have a small customer base. This could potentially be a significant security breach, so please take all possible steps to mitigate this risk. This includes ensuring the Bp Site ID sent to the Get Halo GUID endpoint is correct, and checking the returned practice name is also correct.

  3. We recommend storing the practice's Bp Site ID and practice name for future reference.
    • If the practice reinstalls Halo Link, such as during a server upgrade, they will be assigned a new Halo GUID which you will need to fetch. However the practice's Bp Site ID will not change, so storing it allows for immediate resolution. This could potentially even be automated, as described in the Halo Cloud overview.
    • Storing the practice name allows you to also easily re-validate the Halo GUID returned by the Get Halo GUID endpoint at a later date.
    • If the practice name changes, this may suggest a significant business change such as a clinic merger, which may affect how your application operates.

Handling Halo GUID changes

If the Halo GUID assigned to a Bp Premier practice changes, such as because of a server upgrade that required Halo Link be reinstalled, then attempting to query that practice using their old Halo GUID will return a 403 Forbidden error.

If you receive a 403 Forbidden error:

  1. First attempt to re-fetch the Halo GUID for that practice using their Bp Site ID. We recommend also checking the practice name returned by the API endpoint has not changed.
  2. If the Halo GUID has changed, attempt to query the practice using the new Halo GUID.
  3. If the Halo GUID has not changed or querying the practice does not work, please contact Support.

See the workflows detailed in the Halo Cloud overview for more information, including how to automatically handle Halo GUID changes.

Testing the Get Halo GUID endpoint in staging

To test the Get Halo GUID endpoint in staging with a Bp Premier installation running a developer license, you must use the fake Bp Site ID. The endpoint will not accept a Bp Site ID 0 due to it not being unique.

The fake Bp Site ID can be found in Halo Link's logs. The Halo GUID of a Halo Link instance can also be found in the logs or the registry, if you would like to assert that the endpoint is returning the correct value. The Halo Link registry can be found in the Registry Editor at Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Halo Connect\Halo Link.

If testing in staging against an instance of Bp Premier with a full license, the Bp Site ID found in the Bp Premier UI can be used with the Get Halo GUIDs endpoint as-is.

Accessing multiple databases with the SQL Passthrough API

Bp Premier has multiple databases. At this time, Halo Link only directly connects to the main patient data database. However, integrators can query other databases by specifying the database name within their SQL query provided.

Version: 24.326.2298