Skip to content

Installation

This page details the recommendations, requirements, and steps for installing Halo Link on a practice server or in a integration development environment.

For specific details regarding how Halo Link interacts with different PMS solutions, please see the relevant guides:

Recommendations

  1. Halo Link should be installed on the same server as the PMS database unless installation in another location is required.
    • To install on a secondary server, configure the Database Hostname as appropriate during installation.
  2. Halo Link should not be installed on practice staff workstations or other practice computers.
  3. Halo Link should ideally only be installed once per PMS database instance. The number of practices or locations connected to the database does not matter. If a group of practices share a PMS database, they will also share a single Halo Link installation.

    Server migrations and backup servers

    If you run multiple databases for a single PMS license or are migrating servers, please read:

System requirements

Halo Link requires the following:

Minimum requirement Notes
Bp Premier version October 2022 Data Update. Recommended: July 2023 Data Update.
.NET Framework .NET Framework 4.8 .NET Framework and .NET Core appear to be the same, but are different products. Installing .NET 6.0 won't satisfy the requirement of .NET Framework 4.8.
Microsoft Windows Any Microsoft Windows Server version supported by Microsoft Full support: Microsoft Windows Server 2022 and 2019. Security support: Microsoft Windows Server 2016.
Clock drift <60 seconds To fix clock drift >60 seconds, open PowerShell with Admin Privilege and resync the clock by running w32tm /resync.
Firewall/antivirus See Security requirements below See Security requirements below

Security requirements

Antivirus & Malware detection

To prevent Halo Link being falsely detected as malware, add the Halo Link installation and update directories to the antivirus's ignore/approve lists.

For the Halo Link Service:

C:\Program Files (x86)\Halo Connect\Halo Link

For the Halo Link Updater:

C:\ProgramData\Halo Connect\Halo Link

Halo Link requires the following URLs to be whitelisted by the server's firewall or proxy:

For the Halo Link Service:

https://am-haloapi-prod-001.azure-api.net   
https://api.haloconnect.io/
wss://wps-haloapi-prod.webpubsub.azure.com

For the Halo Link Updater:

https://prodhalolinkrelease.blob.core.windows.net
https://downloads.haloconnect.io/

Proxy server configuration

Halo Link is specifically designed for installation on servers within private networks, positioned behind routers and firewalls. However, Halo Link does not explicitly support proxy servers, and as a result, does not have a specific configuration option for proxy server settings.

It can be implicitly configured since Windows or the .NET framework provide solutions depending on your network configuration.

Proxy server configuration workarounds (click to expand)

HaloLinkService.config File:

This method allows for specific configuration but may be susceptible to updates. It is recommended for testing before transitioning to a more permanent location. The configuration file is located at:

C:\Program Files (x86)\Halo Connect\Halo Link\HaloLinkService.config
Add the following configuration element to the XML:

<system.net>
<defaultProxy>
 <proxy proxyaddress="http(s)://<proxyhost>:<proxyport>" />
</defaultProxy>
</system.net>

Machine.Config for .NET:

This option covers all .NET applications and persists through product updates. Locate the Machine.Config file at:

%WINDIR%\Microsoft.NET\Framework|Framework64[version]\Config\machine.config
Commonly found here:
C:\Windows\Microsoft.NET\framework\v4.0.30319\config\machine.config
Add the following configuration element to the XML:

<system.net>
<defaultProxy>
<proxy proxyaddress="http(s)://<proxyhost>:<proxyport>" />
</defaultProxy>
</system.net>

Setting WinHTTP Proxy with netsh:

This method sets proxy settings for all Windows Services, offering robust persistence through application and .NET updates. Use the following command based on your system architecture and Windows version:

For 64-bit Windows:

C:\Windows\sysnative\netsh.exe winhttp set proxy http(s)://<proxyhost>:<proxyport>
For 32-bit Windows:

C:\Windows\syswow64\netsh.exe winhttp set proxy http(s)://<proxyhost>:<proxyport>
References:

Proxy Configuration: Element (Network Settings) - .NET Framework | Microsoft Learn

Configuration Files: Configuring Apps using Configuration Files - .NET Framework | Microsoft Learn

NetSH WinHTTP: Netsh Commands for Windows Hypertext Transfer Protocol (WINHTTP) | Microsoft Learn

Further examples: Thick Client Proxying - Part 8 - Notes on Proxying Windows Services

Installation prerequisites

To install Halo Link, you will need either:

  • A Bp Premier installer which includes Halo Link, or
  • The appropriate Halo Link installer for the PMS solution you wish to connect to.

To request a Halo Link installer, contact our Support team.

If installing using the Halo Link MSI or via the command line, you may need the following information:

Field Default Description
Database Hostname Bp Premier: .\BPSINSTANCE The database server and instance name in the format <SQLServerName>\<InstanceName>
Environment Production Command line only as of version 23.829. See below for more information.

Setting the environment

Halo Link can be installed such that it targets either a Production or Staging environment.

  • Production is designed for live practice servers. This is the default.
  • Staging is designed for integrators developing and testing their integrations.

For practices and IT providers, environment does not need to be changed as live practice servers should use Production, as per the default.

For integrators, the recommended way to install Halo Link is via the command line, as it is the easiest way to specify Staging.

Environment & installing via Bp Premier

When installed via Bp Premier, there is no option to set Halo Link's environment. Integrators needing a Staging instance of Link should first install Halo Link manually.

Installing a Bp Premier update on a machine which already has Halo Link installed should not change which environment it targets.

Advanced environment configuration (click to expand)

When deciding which environment to use during installation, Halo Link will:

  1. If installed via the command line and the ENVIRONMENT parameter is supplied, the installer will use the supplied value.
  2. If ENVIRONMENT isn't supplied or Halo Link is installed via a different method, the installer will check the registry for an existing environment value and if it exists, the installer will use that.
  3. If neither of the above exist, the installer will default to Production.

How to set the environment to Staging

Explicitly setting the environment should only be required the first time Halo Link is installed. Subsequent re-installs or updates on the same server should respect the previously selected environment.

To set the environment to Staging for a new installation of Halo Link, either:

  1. Install via the command line and set ENVIRONMENT to Staging, or
  2. Add the necessary value to the registry before installation, then install via any of the methods detailed below. Setting the registry can be done by running the following PowerShell script:
    $registryPath = "HKLM:\SOFTWARE\WOW6432Node\Halo Connect\Halo Link"
    If (-NOT (Test-Path $registryPath)){
        New-Item -Path $registryPath -Force | Out-Null
    }
    Set-ItemProperty -Path $registryPath -Name "Environment" -Value "Stage"
    Write-Host "Updated Registry."
    

Installation options

There are three options for installation:

For Bp Premier customers, installing a Bp Premier Data Update or Service Pack will automatically install Halo Link.

Limitations:

  • Installing Halo Link via Bp Premier does not allow for configuration of Database Hostname or Environment.

Installation steps:

  • See the Bp Premier documentation for installation instructions.

Notes:

  • If Halo Link was already installed on the server, the Bp Premier installer will re-install Halo Link using the bundled version.
  • If the bundled Halo Link version is older than the latest version, Halo Link will install then immediately update.
  • If Halo Link was already installed on another server, the Bp Premier installer will also install it on the same server as the Bp Premier database. Due to the restrictions around authoritative servers, the newer installation of Halo Link will be marked non-authoritative. Integrators will continue to communicate with the database via the older authoritative Halo Link installation. See the documentation on authoritative servers for how to change which server is authoritative.

Limitations:

  • Installing via installation wizard does not allow for configuration of Environment.

Installation steps:

  1. Download the Halo Link .msi file from the provided download URL.
  2. Find the .msi file and double-click the file to run it.
  3. Follow the installation wizard's prompts.
Screenshots of installation process (click to expand)

halo-link-install-01.png

halo-link-install-02.png

The following step has been removed in version 23.829:

halo-link-install-03.png

halo-link-install-04.png

halo-link-install-05.png

halo-link-install-06.png

halo-link-install-07.png

Limitations:

  • N/A.

Installation steps:

  1. Download the Halo Link .msi file from the provided download URL.
  2. Open a new command prompt as an Administrator.
  3. Use the msiexec command to run the .msi file with the appropriate parameters. See the Microsoft msiexec docs for the full list of available parameters.
    1. Use /i to specify a normal installation.
    2. Specify the path to the .msi file
    3. Choose a display option.
    4. Specify the Halo Link required fields if necessary:
      • DATABASE_HOSTNAME
      • ENVIRONMENT

Recommended display options:

Parameter Description
/qf Default. Full installation wizard UI.
/qr Reduced installation wizard UI that skips action steps.
/qb or /passive Basic UI with only a progress bar.
/qn or /quiet No UI.

Command example:

msiexec /i C:\path\to\halolink.latest.msi /quiet /qn
    DATABASE_HOSTNAME=<SQLServerName>\<InstanceName> 
    ENVIRONMENT=<"Production"|"Stage">

Prev: Halo Link introduction Next: Updating Halo Link