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.
Multiple databases Bp Premier includes a pair of databases. This setup will often be referred to as "multiple databases" or "multi-database". See Multiple databases.
PMS ID A unique identifier assigned by PMS software that represents a practice in some way. See Identifiers.
Bp Site ID Bp Premier's unique identifier for a Bp practice. This is used by Halo Connect as the PMS ID for Bp Premier. 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 Bp Premier database. See Identifiers.
Link GUID A unique identifier for each Halo Link instance. See Identifiers.

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.

Identifier Description Stability Found in...
Bp Site ID Best Practice's unique identifier for the Bp Premier license given to a practice. Unlikely to change. Bp 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 Bp Premier 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
  • If a practice has multiple Bp Premier databases using the same license, such as in the case of server migrations or backup serves, those databases would have the same Bp Site ID.
  • Integrators can trade PMS IDs such as the Bp Site ID for Halo GUIDs using the Get Halo GUIDs API endpoint.
  • Only one Bp Premier database can exist on a given server, therefore Bp Premier practices should only have one of each of the above identifiers.

Developer licenses

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

Server configurations and changes

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.

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

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.

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.

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 is the first eight characters of the corresponding Halo GUID and can be found in Halo Link's logs.
  • Your application should connect to the staging URL for the relevant Halo Cloud API.
  • Halo Link instances installed on developer and test machines must be set to Stage.
  • 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 to Stage.
  • To connect to a non-developer instance of Bp Premier, Halo Link should be set to Production.

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

Integrators are given a staging subscription for Halo Connect products during onboarding. Once you are happy with your integration, contact us to work through the process of getting a production subscription. Best Practice Software also have their own requirements for switching to production. Please contact them to discuss those requirements.

Exchanging Bp Site 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 Bp Site IDs). The Halo GUID can be found in the return data under practiceMetadata.practiceManagementSiteId.

Secondary identifiers

Bp Site IDs are the primary identifier Halo Connect uses for Bp 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 Bp Premier, 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 Bp Site IDs for Bp developer licenses

Copies of Bp Premier using a developer license do not have a unique Bp Site ID. When Halo Link connects to such a database, it will instead assign the database a fake Bp Site ID.

The fake Bp Site ID is the first eight characters of the corresponding Halo GUID.

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

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

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.1029.3843