Halo Connect & D4W/D4Web

Halo Link can be used with Dental4Windows (D4W), D4W Cloud and Dental4Web (D4Web) from Centaur Software to easily connect integrators to practice databases with less overhead.

For security reasons, this page obscures some details of how the systems work. Please seek the appropriate documentation from Centaur Software 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 only a quick reference guide.

Term	Definition	More info
On-premise or on-prem server	A PC or server, and the software running on it, which can be physically accessed by practice staff and/or an integrator.
Cloud server	A server running in the cloud which can not be physically accessed by practice staff and/or an integrator.
Practice server(s)	A server or set of servers which support one or more practices, on which the D4W database and Halo Link are installed.
Multiple installations via tenanting	D4W Cloud and D4Web operate in a multi-tenant environment with logically isolated databases sharing a common server cluster. This means there can be multiple database instances on one server. This will often be referred to as "multiple installations" or "multi-installation".	See Server setups.
PMS ID	A unique identifier assigned by PMS software that represents a practice in some way.	See Identifiers.
Centaur Customer Reference Number (CRN)	Centaur's unique identifier for a D4W/D4Web practice. This is used by Halo Connect as the PMS ID for D4W/D4Web. When one D4W/D4Web database serves multiple practice branches, Halo Connect uses the parent CRN of the main practice.	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 D4W database.	See Identifiers.
Link GUID	A unique identifier for each Halo Link instance.	See Identifiers.

In the Halo API reference, the practiceManagementSiteId for a D4W/D4Web practice is the Centaur CRN.

Basics

Supported server setups

Halo Connect supports:

Dental4Windows, installed once on an on-premise server
Dental4Web or D4W Cloud hosted in a multi-tenant Cloud environment.

Halo Link only has to be installed once in a multi-tenanted environment. It will handle routing queries appropriately using Centaur CRNs and Halo GUIDs.

graph LR
    HC[Halo Cloud APIs]

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

    subgraph Primary practice server
        Z1[D4W database]
        Z2[D4W database]
        HL1["Halo Link"]
        HL1 <--> Z1
        HL1 <--> Z2
    end

    HC <--> HL1

    subgraph Practice computers
        subgraph Staff computer
            Z1 <--> C1[PMS Client]
        end
        subgraph Staff computer
            Z1 <--> C2[PMS Client]
        end
    end

    subgraph Practice computers
        subgraph Staff computer
            Z2 <--> C3[PMS Client]
        end
        subgraph Staff computer
            Z2 <--> C4[PMS Client]
        end
    end

Centaur Software 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 Centaur Software and the practices.

Enabling integrators: Integrators can only connect to a practice via Halo Connect if they have been enabled by Centaur.
Data access: Integrators can only access the database components authorised by Centaur.

Halo Connect has its own access and authorisation systems which build on D4W/D4Web's systems, and do not replace any of D4W/D4Web's own systems.

Identifiers: Centaur CRNs, Halo GUIDs, and Link GUIDs

Identifier	Description	Stability	Found in...
Centaur Customer Reference Number (CRN)	Centaur's unique identifier for a D4W/D4Web practice. Each D4W/D4Web database can have one parent CRN plus multiple local CRNs for each non-parent location.	Unlikely to change.	D4W/D4Web 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 D4W/D4Web 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

A practice's CRN can be found in the user interface under:
- D4W: Help > About > Technical Support
- D4Web: System Information > About > Technical Support
The CRN displayed will be for the local practice. The parent CRN can be found at the parent practice.
Integrators can trade PMS IDs such as the Centaur CRN for Halo GUIDs using the Get Halo GUIDs API endpoint.
If a server only has one D4W database installed, it will have:
- One Link GUID
- One Halo GUID
- One parent Centaur CRN
- Possibly multiple local Centaur CRNs, one for each branch location
If a multi-tenanted setup, it will have:
- One Link GUID, as Halo Link only needs to be installed once
- Multiple Halo GUIDs, one for each database
- Multiple parent Centaur CRNs, one for each database
- Possibly multiple local Centaur CRNs, one for each branch location

Halo Connect only uses parent CRNs, not local CRNs

Halo Link identifies D4W/D4Web databases by only one CRN -- the parent CRN. If a database serves multiple branch practices, the CRN used is that of the parent practice. Local CRNs other than the parent CRN are not used.

Branch practices may want to record the CRN of their parent practice for when talking to integrators.
Integrators will want to ensure they receive the parent practice's CRN, not that of a branch practice. Attempting to trade a branch CRN for a Halo GUID will fail.
For help identifying your parent CRN, please call Centaur Support on 1300 855 966.

Handling multiple Halo Link instances: authoritative vs non-authoritative

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.

For practices: See the Halo Link server configurations page for more information about authoritative and its implications for server changes.
For integrators: See the Halo Cloud overview for more information about handling changes to a practice's authoritative Halo GUID.

For practices

Enabling integrations

Halo Link does not give integrators access to any practice data until they are enabled by the Centaur technical support team.

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

D4W: a practice's CRN is available in the D4W UI. Go to the Help menu, then the About dialog, and it is listed as "Customer Reference #" under “Technical Information”.
D4Web: a practice's CRN is available in the D4Web UI. Go to System Information in the hamburger menu, then the About dialog, and it is listed as "Customer Reference #" under “Technical Information”.

When a single D4W/D4Web database serves multiple practices, each receives a separate "local" CRN from Centaur. However, Halo Connect only uses the CRN of the parent practice. Please ensure you're giving integrators the correct CRN. If you have any questions, please contact us or call Centaur Support on 1300 855 966.

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.

Staging

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.
Halo Link will generate a fake Centaur CRN for test versions of D4W/D4Web, as the CRNs of test instances are not unique. The fake Centaur CRN is the first eight characters of the corresponding Halo GUID and can be found in Halo Link's logs.

Production

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 a testing instance of D4W/D4Web, such as a demo database or de-identified database.

To connect to a testing instance of D4W/D4Web, Halo Link must be set to Stage.
To connect to a non-testing instance of D4W/D4Web, Halo Link should be set to Production.

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

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

For onboarding practices, see the section above on Finding your Centaur CRN and the gotchas around main and branch practices.
For connecting to development machines, see the section below on Fake Centaur CRNs for demo copies of D4W/D4Web for more information on working with demo and de-identified copies of D4W/D4Web.

Secondary identifiers

Centaur CRNs are the primary identifier Halo Connect uses for D4W/D4Web 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 D4W/D4Web, 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 Centaur CRNs for demo copies of D4W/D4Web

Demo and de-identified copies of D4W/D4Web do not have a unique CRN. When Halo Link connects to such a database, it will instead assign the database a fake Centaur CRN.

The fake Centaur CRN is the first eight characters of the corresponding Halo GUID.

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

A fake Centaur CRN can be used with the Get Halo GUID endpoint. The endpoint will not accept non-unique demo CRNs.