
HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
On Premise Upgrade - WebApp
Versions
If you wish to upgrade halo, then you have potentially 3 options for versions to upgrade to, being our current Stable, Beta, or possibly our Release Candidate at the time.
The downloads can be found on the Halo Self Service Portal: https://support.haloservicedesk.com/
The latest features will be in the Beta version but could be potentially less stable, where as Stable been in use for longer with more stable features, but none of the brand new features, and the Release Candidate being somewhere in the middle.
It is recommended that people upgrade to the security patch first. This is much quicker and does not require going NHServerless or setting up the DB Integrator. Please take a backup of your current version as well as your database before proceeding with the upgrade.
We also recommend that you take a backup of your current database, and your webapp file on its current version.
Also, please ensure you are using SQL Server 2016 onwards since an older versions of SQL Server are not supported by newer versions of Halo.
IMPORTANT
You can download the security patch on the self service portal here:
Upgrading Halo
- Download the version of halo you wish to upgrade to (they will have to login to the Halo Self Service Portal to retrieve this) https://support.haloservicedesk.com/haloversions
- Extract the nhdweb zip file once you have downloaded them on this server. This must be done before you can drag and drop the files over.
- Stop your halo site running on IIS
- Select all of these files within the extracted file (ctrl+a), then drag and drop them into your existing WebApp file. DO NOT DRAG AND DROP THESE FILES INTO ANOTHER FOLDER. This should be located in within a generic Halo folder within the C Drive. C:\Halo\WebApp.
- Note: Replacing the WebApp files with the upgrade version files will override any configuration changes made to the web.config files in the root, api, auth, and portal folder. Before performing this change, please copy any customised headers such as HSTS, Referrer, and permissions policies for future reference; alternatively, remove web.config from the upgraded version files.
- If you are upgrading from a pre 2.88 version of halo, you will need to download https://aka.ms/vs/17/release/vc_redist.x64.exe, Add it to your installfiles folder, and run the program.
- If you are upgrading from a version before 2.50, you will need to run the UpgraderOld.exe and follow the above step as well
- UPDATE - If the upgrade is from a version before 2.130 to after 2.130 you will want to install this or halo will not work: https://download.visualstudio.microsoft.com/download/pr/b50f2f63-23ed-4c96-9b38-71d319107d1b/26f8c79415eccaef1f2e0614e10cd701/dotnet-hosting-6.0.21-win.exe
- Run the upgrader.exe within halo and go through the steps given by the console. Once it is complete the application should close, but if you are unsure you can double check and re-run the upgrader.exe file and it should say you are up to date.
- Restart the site on IIS
- Navigate to your halo instance, and check in the ‘about’ window (bottom option of the ? menu at the top right) that it is showing the correct version
This might require a cache reset with SHIFT + F5, or a log in and out
Troubleshooting
If you notice any irregularities in the new version, or the version numbers don't match or haven't changed, then the first thing to do is reload and clear the cache by pressing Ctrl-F5. Unlike other browser options that clear the cache, pressing Ctrl-F5 also clears the server-side cache, so it's best to use this over your usual browser-cache clearing routine.
If after carrying out your last steps your Web App does not work, then you may be missing a .json MIME type at the server level.
Navigate to Server Level in IIS, in MIME types, and if the .json MIME type is missing then click 'Add...' and enter the values as per the screenshot below.
If you have the default deployment configuration (api and auth apps within a single site/folder) you can use the automatic upgrade, if not you must use the manual method.
Another Common Error
If the agent portal does not load up when you are trying to log back in after the upgrade, you must check you API information on your halo instance. To do so you can append api/instanceinfo to the URL i.e. https://myexamplehalo.halopsa.com/api/instanceinfo
If there are errors for an on-premise upgrade and a login loop is encountered after the upgrade from 2.126 to 2.132 then please manually create the folder as below and ensure that the user running the web application in IIS has permission to modify that folder.
C:\Windows\System32\config\systemprofile\AppData\Local\IronSoftware
This error is stating that there is a lack of permissions granted, so to bypass this we can increase the level of permissions given to the IIS_IUSRS.
NB: There may already be an IIS_IUSRS user name on list, you will just have to give the following permission to the user by clicking on the IIS_IUSRS in the user name list and then giving the "Full control" Permission:
If you head to the API folder within you halo folder, then right click on the folder and click on properties you can go to the security tab and add permissions.
Click on System and then "Edit" from here the user can be added
when you check names it should find that user, then go back to the user name list and grant the following permission for the IIS_IUSRS:
Now when you load the website, it should work as intended.
Permission error regarding the Integrator file when dragging and dropping Halo Files
When initially dragging and dropping the upgraded Halo files:
You may experience a permissions error specifically regarding the Integrator file located here:
This is due to task scheduler currently running a scheduled task, and locking itself down to prevent any tasks from being ended whilst running. You can either wait for the task to finish running or you can end the task here:
Upgrader Error - Error Incorrect Syntax near 'INDEX'...
If you the upgrader throws this error then this is an issue regarding the version of SQL Server that is being used, which is no longer supported by Halo. All on premise customers need to be SQL Server 2016 or above otherwise more recent versions of Halo will not be supported:
If this is thrown you will have to revert back to the version of Halo the client was previously on, then you can upgrade your SQL Server version to 2016 or above.
Upgrader Error - Upgrading to the net version requires the ... service to be active
For exampple:
If you have received a form of this error then there are a few things which may be causing this:
- Upgrading to the net version requires the Event service to be active - The Event Service must be enabled.
- Upgrading to the net version requires the Incoming service to be active - The Incoming Service must be enabled.
- Upgrading to the net version requires the Outgoing service to be active - The Incoming Service must be enabled.
- Upgrading to the net version requires the Scheduling service to be active - The Incoming Service must be enabled.
This refers to the following checkboxes under the Backend Services tab. This can be found within configuration > advanced settings > (Backend Services Tab)
If this is the case then you have likely tried to upgrade to a version of Halo which no longer supports NHServer and now requires the new services to be configured. If this is the case then it is easiest to upgrade to the Security patch 2.174.111 and then moving to the new services and set this up. How to access this version of Halo is detailed at the start of this guide. Also, setting up the new services is detailed further in NHServer deprecation and DB integrator guide linked at the bottom of this article.
Popular Guides
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments and Teams
- Halo Integrator
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- NHServer Deprecation User Guide
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through