Upgrading Halo¶

This runbook covers upgrading the Halo application version on the Application Server of a self-hosted GRC-ITSM deployment. GRC-ITSM runs on a Halo core, so this is how you move your instance to a newer Halo release. The upgrade replaces the files in the WebApp folder and runs a database upgrader; it does not touch the host OS.

1. Version selection¶

Halo offers up to three version channels on the Halo Self Service Portal (https://support.haloservicedesk.com/). Choose based on your stability/feature trade-off (per On-Prem Upgrade, s2).

2. Prerequisites¶

Take a backup¶

Take a current database backup (and ideally a VM snapshot of the Application Server) before proceeding. If the upgrade fails, this is your rollback point. «CONFIRM: backup / snapshot location + owner»

Verify SQL compatibility level¶

Halo requires JSON support (OPENJSON, Transact-SQL), so SQL Server 2016+ with compatibility level >= 130 is mandatory. When upgrading to Halo v2.220 or later, raise the level to >= 140 (per s1 and s2).

Check the current level:

SELECT name, compatibility_level
FROM sys.databases
WHERE name = 'YourDatabaseName';

Raise it if it is below the required level:

ALTER DATABASE YourDatabaseName
SET COMPATIBILITY_LEVEL = 130;

ALTER DATABASE YourDatabaseName
SET COMPATIBILITY_LEVEL = 140;

Ensure the new (NHServerless) services are enabled if crossing the deprecation threshold¶

If you are upgrading to a version that requires the new event services (NHServerless, which replaced NHServer), they must be set up and enabled first. These are application toggles under Configuration > Advanced Settings > Backend Services -- not services.msc entries. If you skip this and the target version no longer supports NHServer, upgrader.exe will fail (see Troubleshooting).

Version-gated installer steps¶

Depending on the version you are upgrading from (and to), one or more additional installers are required before running upgrader.exe (per s2). Present these to whoever runs the upgrade:

3. Pre-flight checklist¶

• Target version and channel chosen (Stable for production)
• Current Halo version recorded (to determine version-gated steps)
• Database backup taken; VM snapshot taken
• SQL compatibility level verified (>= 130, or >= 140 for v2.220+)
• New (NHServerless) Backend Services enabled if the target version requires them
• nhdweb zip downloaded from the Self Service Portal onto the Application Server
• WebApp folder path confirmed: «CONFIRM: WebApp path»
• IIS site / app pool names confirmed: «CONFIRM: IIS site + app pool names»
• Integrator scheduled task name(s) confirmed (in case of file-lock during drag-drop): «CONFIRM: integrator Scheduled Task name(s)»
• Custom web.config headers (HSTS, Referrer, permissions policies) located and copied for the root, api, auth, and portal folders
• Change request approved and inside the maintenance window: «CONFIRM: maintenance window + change-approval owner»

4. Procedure¶

Step 1 -- Download and extract on the Application Server¶

Download the chosen version's nhdweb zip from the Self Service Portal (https://support.haloservicedesk.com/haloversions) onto the Application Server, then extract it there. The files must be extracted before you can drag and drop them.

Step 2 -- Stop the Halo IIS site¶

Stop the Halo IIS site (and app pool). This is the same shutdown step documented in Upgrading the Host OS, step 2 -- there is no Halo Windows service.

Import-Module WebAdministration
Stop-Website    -Name 'CONFIRM-HaloSiteName'
Stop-WebAppPool -Name 'CONFIRM-HaloAppPool'

Step 3 -- Preserve custom web.config headers¶

Step 4 -- Drag the upgrade files into the WebApp folder¶

In the extracted folder, select all files (Ctrl+A), then drag and drop them directly into the WebApp folder.

Step 5 -- Run version-gated installers¶

Run any installers identified in Prerequisites > Version-gated installer steps, in this order, before running upgrader.exe:

1. If from a version before 2.88: run vc_redist.x64.exe (placed in InstallFiles).
2. If from a version before 2.50: run UpgraderOld.exe.
3. If from before 2.130 to after 2.130: install dotnet-hosting-6.0.21-win.exe.

Step 6 -- Run upgrader.exe¶

Run upgrader.exe from within the Halo (WebApp) files and follow the steps in the console. When it finishes, the application should close. If you are unsure whether it completed, re-run upgrader.exe -- it should report that you are up to date.

Step 7 -- Restart the IIS site¶

Restart the Halo site on IIS, then re-enable the integrator task(s) if you disabled them in step 2:

Import-Module WebAdministration
Start-WebAppPool -Name 'CONFIRM-HaloAppPool'
Start-Website    -Name 'CONFIRM-HaloSiteName'

# Re-enable the integrator scheduled task(s) if they were disabled before the drag-drop.
# «CONFIRM»: adjust the -like pattern if the exe name differs in this deployment.
$integratorTasks = Get-ScheduledTask | Where-Object {
    $_.Actions.Execute -like '*Integrator*'
}

foreach ($task in $integratorTasks) {
    Enable-ScheduledTask -TaskName $task.TaskName -TaskPath $task.TaskPath
}

$integratorTasks | Select-Object TaskName, TaskPath, State

5. Verification¶

1. Check the version in the About window. Navigate to the Halo instance and open the About window (the bottom option of the ? menu, top right). Confirm it shows the new version.
2. Clear the cache. If the version has not changed or you see irregularities, press Ctrl+F5. Ctrl+F5 also clears the server-side cache, so prefer it (per On-Prem Upgrade -- Troubleshooting, s3). The upgrade guide (s2) also mentions Shift+F5 and logging out and back in, but Ctrl+F5 is preferred because it clears the server-side cache.
3. Confirm the agent portal loads on login. If it does not, check the API info: append /api/instanceinfo to the base URL.
4. Confirm the integrator runs without errors and is on the same version as the DB and WebApp (the integrator is bundled with the upgrader files; if it was relocated it is not auto-updated -- per s5).

6. Troubleshooting¶

Derived from On-Prem Upgrade -- Troubleshooting (s3) and DB Integrator -- Troubleshooting (s4).

«CONFIRM: base URL»/api/instanceinfo?clear_cache=true

C:\Windows\System32\config\systemprofile\AppData\Local\IronSoftware

7. Rollback¶

If the upgrade fails and cannot be resolved within the window:

1. Restore the database backup taken in the prerequisites.
2. Revert the Halo version by restoring the previous WebApp files (or revert the VM snapshot of the Application Server). Re-apply your preserved custom web.config headers if you restored individual files.
3. Restart the IIS site and re-enable the integrator task(s).
4. Run the Verification section against the restored version to confirm it is healthy.

8. Escalation¶

Escalate to role/queue owners rather than improvising fixes inside the outage:

Related runbooks¶

• Upgrading the Host OS -- canonical reference for the shared IIS-stop and integrator-disable steps, and for OS patching/reboots.
• On-Prem Maintenance overview -- topology and the full list of «CONFIRM» environment values.