Upgrading the Host OS¶

This runbook covers applying Windows Server updates and rebooting the Application Server (and, when in scope, the SQL Server) in a self-hosted GRC-ITSM deployment. The goal is to patch and reboot cleanly without data loss, without leaving the Halo WebApp down, and without the DB Integrator throwing a "Decryption check failed" error on the way back up.

Scope and prerequisites¶

Pre-flight checklist¶

Work through this before stopping any services:

• Change request approved and inside the agreed maintenance window
• VM snapshot taken of the host(s) being patched
• Current SQL backup taken (if the SQL Server is in scope)
• WebApp folder path confirmed: «CONFIRM: WebApp path -- e.g. C:\Halo\Production or C:\Halo\WebApp»
• IIS site name and app pool name confirmed: «CONFIRM: IIS site + app pool names»
• Integrator scheduled task name(s) and exe folder confirmed: «CONFIRM: integrator Scheduled Task name(s) + exe folder -- may be more than one»
• Whether the API certificate is installed on the Application Server confirmed: «CONFIRM: API certificate installed on the Application Server»
• Users notified of the outage window

Procedure¶

1. Announce and drain users¶

Notify your agents and end users that GRC-ITSM will be unavailable for the window. Confirm no critical interactive work is in progress before proceeding.

2. Stop the Halo IIS site and app pool¶

Remember there is no Halo Windows service -- stopping Halo means stopping the IIS site and its application pool.

Import-Module WebAdministration

# «CONFIRM» these names against the deployment
$siteName    = 'CONFIRM-HaloSiteName'
$appPoolName = 'CONFIRM-HaloAppPool'

Stop-Website     -Name $siteName
Stop-WebAppPool  -Name $appPoolName

Get-Website         -Name $siteName    | Select-Object Name, State
Get-WebAppPoolState -Name $appPoolName | Select-Object Value

3. End and disable the integrator scheduled task(s)¶

The DB Integrator is not a Windows service. It is an executable run on a Windows Scheduled Task on the Application Server (and it can also run interactively as a GUI app via its Processing / Integrations tabs). There may be more than one integrator task. End any running instance, then disable the task(s) so they do not fire during the reboot. If the DB Integrator GUI is open, close it.

The integrator executable is often relocated, so the reliable way to locate the task(s) is to match on the Action's execute path. Adjust the match pattern if the deployment uses a different executable name.

# Find scheduled tasks whose action runs an *Integrator* executable.
# «CONFIRM»: adjust the -like pattern if the exe name differs in this deployment.
$integratorTasks = Get-ScheduledTask | Where-Object {
    $_.Actions.Execute -like '*Integrator*'
}

$integratorTasks | Select-Object TaskName, TaskPath, State

# End any currently running instance, then disable each task.
foreach ($task in $integratorTasks) {
    Stop-ScheduledTask    -TaskName $task.TaskName -TaskPath $task.TaskPath
    Disable-ScheduledTask -TaskName $task.TaskName -TaskPath $task.TaskPath
}

4. If the SQL Server is also being patched, mind the ordering¶

When both hosts are patched in the same window, bring the Halo WebApp down (steps 2-3) before the SQL Server is taken offline, and bring SQL back before restarting the WebApp. Halo cannot start cleanly against an unavailable database.

5. Apply updates and reboot¶

Apply the approved Windows updates to the host and reboot. If both hosts are in scope, complete the SQL Server first (or per your agreed ordering), confirm SQL is back, then proceed with the Application Server.

6. After reboot: confirm Halo is back up¶

1. Confirm the IIS site and app pool started. The Halo site normally auto-starts with the W3SVC service after a reboot. If it did not, start it manually (reverse of step 2):

   Import-Module WebAdministration
   Start-WebAppPool -Name 'CONFIRM-HaloAppPool'
   Start-Website    -Name 'CONFIRM-HaloSiteName'
   
   Get-Website -Name 'CONFIRM-HaloSiteName' | Select-Object Name, State
   

2. Confirm Backend Services are enabled. In the application, go to Configuration > Advanced Settings > Backend Services and confirm the Event, Incoming, Outgoing, and Scheduling services are enabled. These are application toggles, not services.msc entries.

3. Re-enable the integrator scheduled task(s) disabled in step 3:

   # Re-enable the same tasks disabled before the reboot.
   $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
   

Verification¶

Confirm the platform is fully healthy before closing the change:

1. Load the application URL and confirm the login screen renders.

2. Hit the API info endpoint to confirm the WebApp and API are responding:

   «CONFIRM: base URL»/api/instanceinfo
   

3. Clear the cache with Ctrl+F5 after logging in. Unlike an ordinary browser refresh, Ctrl+F5 also clears the server-side cache (per On-Prem Upgrade -- Troubleshooting, s3), so prefer it here.

4. Confirm the integrator runs on its next scheduled fire (or trigger it manually via Task Scheduler > select the task > Run, or via the DB Integrator GUI's Processing tab). Confirm it completes without a "Decryption check failed" error. If that error appears, the API certificate is likely missing -- see the note in step 3.
5. Confirm Backend Services processing -- e.g. that incoming mail is being processed and scheduled tickets fire.

Rollback¶

If the host fails to come back cleanly, or Halo will not start after the reboot:

1. Revert the VM snapshot taken in the pre-flight checklist. This is the primary rollback for a host-OS change.
2. If the SQL Server was patched and the database is suspect, restore from the backup taken in pre-flight.
3. After reverting, repeat the verification section to confirm the rolled-back state is healthy.
4. Re-enable the integrator task(s) if the revert left them disabled.

Escalation¶

If you cannot resolve an issue within the maintenance window, escalate to the role/queue owners rather than attempting open-ended fixes inside the outage:

Related runbooks¶

• Upgrading Halo -- reuses the IIS-stop and integrator-disable steps from this page before swapping in new application files.
• On-Prem Maintenance overview -- topology and the full list of «CONFIRM» environment values.