Skip to content

Halo Connect & D4W

Halo Link can be used with both D4Windows and D4Web to easily connect integrators to practice databases with less overhead.

For security reasons, this page obscures some details of how D4W works. Please see the D4W 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 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 D4W software can be installed multiple times on the same server. This is how D4W's cloud-hosted product works. 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.
D4W Customer Reference Number (CRN) D4W's unique identifier for a D4W practice. This is used by Halo Connect as the PMS ID for D4W. When one D4W 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 practice is the D4W CRN.

Basics

Supported server setups

Halo Connect supports:

  • Dental4Windows, installed once on an on-premise server
  • Dental4Web, including when installed on a cloud server running multiple instances side-by-side

Halo Link only has to be installed once on servers with multiple D4W installations. It will handle routing queries appropriately using D4W CRN 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

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

  • Enabling integrators: Integrators can only connect to a practice via Halo Connect if they have been enabled by that practice within the D4W UI.
  • Data access: Integrators can only access the database tables and stored procedures D4W have given them access to.

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

Identifier Description Stability Found in...
D4W Customer Reference Number (CRN) D4W's unique identifier for a D4W practice. Unlikely to change. D4W 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 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 D4W UI, under Help > About. The CRN displayed will be for the local practice, whether that is the main practice or a branch practice.
  • Integrators can trade PMS IDs such as the D4W CRN for Halo GUIDs using the Get Halo GUIDs API endpoint.
  • If a server only has one D4W database installed, it will have one of each of the above identifiers.
  • If a server has multiple D4W databases installed, it will have:
    • One Link GUID, as Halo Link only needs to be installed once.
    • Multiple D4W CRNs, one for each database.
    • Multiple Halo GUIDs, one for each database.

Branch practices must use the parent practice's CRN with Halo Connect systems

Halo Link identifies D4W databases by only one CRN. If a database serves multiple branch practices, the CRN used is that of the parent practice.

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

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

Enabling integrations

Halo Link does not give integrators access to any practice data until they are enabled in the D4W UI.

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

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

When a single D4W database serves multiple practices, each receives a separate CRN from D4W. 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 D4W support.

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.
  • 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 D4W CRN for testing versions of D4W, as the CRNs of test instances are not unique. The fake Bp D4W 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, such as a demo database or de-identified database.

  • To connect to a testing instance of D4W, Halo Link must be set up in staging.
  • To connect to a non-testing instance of D4W, Halo Link should be set up in production.

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

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

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

Secondary identifiers

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

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

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

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

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