Upgrade to 2.9

Recommendations

To upgrade a Casewhere deployment to 2.9, you must be, at least, running a 2.6-series release.

Before upgrading Casewhere, always test your application in a staging environment before deploying the upgrade to your production environment. It would be best if you also backup your production database before upgrading.

If you are deploying Azure App Service using Kudu Zip Push Deploy, you don't have to modify the web.config files manually, only need to update the keys in the Configuration / Application Settings.

Information! If you are replacing the old web.config with the new one, then you can ignore all update it steps in the section below.

All the settings in this document are described in the configuration settings reference.

Upgrade versions

The following changes must be applied in the described order.

2.9.0.0 - 01/08/2025

Remove the "session:" prefix from the session constraint setting

The session constraint setting is now named the same in all sites. Open the web.config in Casewhere.Configuration.Web and Casewhere.Hangfire and rename the key below:

	<!-- Before -->
	<add key="session:AcceptableDeviationSeconds" value="3" />

	<!-- After -->
	<add key="AcceptableDeviationSeconds" value="3" />

Casewhere.Worker.Api already uses AcceptableDeviationSeconds and does not need to be changed.

Default is 3 seconds if the key is missing. If your identity provider and your Casewhere servers are not time-synchronized, consider raising the value, for example to 15 seconds.

2.9.1.0 - 03/10/2025

There is no change in configuration.

2.9.2 - 26/10/2025

There is no change in configuration.

2.9.3 - 29/10/2025

There is no change in configuration.

2.9.4 - 19/11/2025

There is no change in configuration.

2.9.5 - 01/12/2025

There is no change in configuration.

2.9.6 - 10/12/2025

Update the binding redirect of the text encoding library

Casewhere Admin now uses a newer HTML parser for the data class document editor. Open the web.config in Casewhere.Configuration.Web and update the binding redirect below:

<runtime>
	<assemblyBinding>
		<dependentAssembly>
			<assemblyIdentity name="System.Text.Encoding.CodePages" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
			<bindingRedirect oldVersion="0.0.0.0-6.0.0.0" newVersion="5.0.0.0" />
		</dependentAssembly>
	</assemblyBinding>
</runtime>

If the binding redirect is not updated, Casewhere Admin fails to start with an assembly load error.

2.9.6.1 - 11/12/2025

There is no change in configuration.

2.9.6.2 - 13/12/2025

Support SSL offloading for the worker site

When SSL is terminated on a load balancer or reverse proxy, the worker site receives the request as HTTP but must build HTTPS URLs for the browser and for the identity provider. Casewhere now forces HTTPS on those URLs, so no configuration is required for that part.

If the worker site should call the API over an internal address instead of the public one, you can add the optional setting below to the web.config file in the Casewhere.Web.CaseWorker project.

	<add key="ApiEndPointInternal" value="http://api-internal.casewhere.com/api/v0.1/" />

If the key is missing, ApiEndPoint is used, which is the previous behaviour.

2.9.6.3 - 10/01/2026

Friendly error page

Instead of a raw server error, the worker site and the Worker API now show a friendly error page. To enable and customize it, add the following settings to the web.config file in the Casewhere.Web.CaseWorker and Casewhere.Worker.Api projects.

	<add key="DefaultErrorTitle" value="Oops! Something went wrong." />
	<add key="DefaultErrorMessage" value="We could not complete your request because of an unexpected error. Please try again. If the problem continues, contact support." />

Set the texts in the language of your solution. In addition, turn on the custom error page in the web.config file in the Casewhere.Web.CaseWorker project.

	<system.web>
		<customErrors mode="On" defaultRedirect="~/error" />
	</system.web>

2.9.6.4 - 04/02/2026

There is no change in configuration.

2.9.6.5 - 26/03/2026

There is no change in configuration.

2.9.7.0 - 25/04/2026

Enable Casewhere AI

Casewhere AI lets an application developer work on the configuration with an AI assistant through an MCP server. To use it, add the following settings to the web.config file in the Casewhere.Configuration.Web project.

	<add key="ai:EnableAI" value="false" />
	<add key="ai:McpBaseUrl" value="https://mcp.casewhere.com/" />

The feature is disabled by default if ai:EnableAI is missing. ai:McpBaseUrl is the public address of the MCP server that the assistant connects to.

For an on-premise deployment, the same keys are available as placeholders in Web.OnPremise.config:

	<add key="ai:EnableAI" value="%SETTING.AI.EnableAI%" xdt:Transform="Replace" xdt:Locator="Match(key)"/>
	<add key="ai:McpBaseUrl" value="%SETTING.AI.McpBaseUrl%" xdt:Transform="Replace" xdt:Locator="Match(key)"/>

Deploy the MCP server

The MCP server is a new site, Casewhere.Configuration.Mcp. It is an ASP.NET Core application that targets .NET 9, so the .NET 9 hosting bundle must be installed on the server. It is deployed next to Casewhere Admin and points at it with the setting below in appsettings.json.

{
  "CasewhereAdmin": {
    "BaseUrl": "https://admin.casewhere.com/"
  }
}

One MCP deployment can serve several Casewhere instances, so this base URL is only the default target. See connect an AI assistant for the full setup.

Information! Casewhere AI is optional. If you do not deploy the MCP server, leave ai:EnableAI as "false" and the rest of the platform is unaffected.

2.9.8.0 - 10/05/2026

There is no change in configuration.

2.9.8.1 - 14/05/2026

There is no change in configuration.

2.9.8.3 - 17/05/2026

There is no change in configuration.

2.9.8.4 - 21/05/2026

There is no change in configuration.

2.9.8.5 - 25/05/2026

There is no change in configuration.

2.9.9.0 - 31/05/2026

There is no change in configuration.

2.9.10.0 - 06/06/2026

Configuration source control with Git

Casewhere can mirror the configuration to a folder on disk and use that folder as the source of truth, so the configuration can be tracked in Git and moved between environments. To enable it, add the following setting to the web.config file in the Casewhere.Configuration.Web project.

	<add key="config:ConfigFolderPath" value="C:\Casewhere\configs" />

The folder must exist and the application pool identity must be able to read and write in it. If it is a Git working directory, the Git commands in Casewhere Admin operate on it.

The feature is disabled when the value is empty or the key is missing, and the platform then behaves exactly as before.

For an on-premise deployment, the key is available as a placeholder in Web.OnPremise.config:

	<add key="config:ConfigFolderPath" value="%SETTING.Config.ConfigFolderPath%" xdt:Transform="Replace" xdt:Locator="Match(key)"/>

Important! Enable this on one environment at a time and export the configuration to the folder once before you turn on the reload direction. See enable and configure source control.

2.9.10.1 - 06/06/2026

There is no change in configuration.

2.9.11.0 - 09/06/2026

Name the MCP server per deployment

An AI assistant can be connected to several Casewhere deployments at the same time. To keep the generated assistant configurations apart, give each deployment its own MCP server name in the web.config file in the Casewhere.Configuration.Web project.

	<add key="ai:McpName" value="CasewhereProd" />

For an on-premise deployment, the key is available as a placeholder in Web.OnPremise.config:

	<add key="ai:McpName" value="%SETTING.AI.McpName%" xdt:Transform="Replace" xdt:Locator="Match(key)"/>

From this version the assistant signs in through the browser, so the long-lived token no longer has to be pasted into the assistant configuration. Manual tokens still work.

2.9.12.0 - 11/06/2026

There is no change in configuration.

2.9.12.1 - 17/06/2026

There is no change in configuration.

2.9.13.0 - 20/06/2026

There is no change in configuration.

2.9.13.1 - 23/06/2026

There is no change in configuration.

2.9.13.2 - 29/06/2026

Remove the Runtime API key from the configuration files

The key that protects the communication between the job site and the Worker API is no longer stored in the configuration files. It is now stored encrypted in the CasewhereKeys database and rotated automatically.

Remove the setting below from the web.config files in the Casewhere.Hangfire and Casewhere.Worker.Api projects, from both appSettings and secureAppSettings.

	<add key="cwjobs:RuntimeApiKey" value="..." />

For an on-premise or Azure deployment, also remove the matching transform entry from Web.OnPremise.config and Web.Azure.config, and remove the RuntimeApiKey value from your deployment settings.

The key is created on the first start after the upgrade, so no manual step is needed. If you have to change the rotation behaviour, the optional settings below can be added to the web.config file in the Casewhere.Hangfire project.

	<add key="cwjobs:RuntimeApiKey:RotationIntervalHours" value="720" />
	<add key="cwjobs:RuntimeApiKey:GraceWindowHours" value="24" />
	<add key="cwjobs:RuntimeApiKey:CacheTtl" value="60" />

CacheTtl is in seconds. Keep GraceWindowHours greater than or equal to CacheTtl plus the request timeout, so a key that is being rotated is still accepted while it is in flight.

Important! The Casewhere.Hangfire and Casewhere.Worker.Api sites must point at the same CasewhereKeys database, otherwise the job site cannot authenticate against the Worker API.

2.9.14.0 - 05/07/2026

The audit log option on an activity definition is deprecated

The Enable audit log option on an activity definition no longer has an effect. Audit logging is controlled on the data class instead. No configuration change is required, but review the activities where you relied on the option.

2.9.14.2 - 12/07/2026

Enable the server metrics API

The Worker API can expose server health metrics for an external monitoring system. The endpoints reject every request when the key is missing, so add the setting below to the secureAppSettings section of the web.config file in the Casewhere.Worker.Api project.

	<add key="monitoring:ServerMetricsApiKey" value="A long random value" />

Use a long random value and treat it as a secret. Without this key the external/v0.1/server-metrics/* endpoints are unavailable; the rest of the platform is unaffected.

Deploy the Server Monitor (optional)

To collect the same metrics from a server that does not run the Worker API, for example a database or job server, deploy the new Casewhere.ServerMonitor tool. It is a standalone application that targets .NET 9 for Windows, runs as a Windows service on Kestrel, and does not need IIS. Configure it in appsettings.json.

{
  "Urls": "http://0.0.0.0:5000",
  "Monitoring": {
    "ServerMetricsApiKey": "A long random value"
  }
}

The tool exposes GET /metrics and requires the API key on every request, either in the Authorization header or as the apiKey query parameter. Install and uninstall scripts are shipped with the tool.

2.9.14.3 - 13/07/2026

There is no change in configuration.

2.9.14.4 - 20/07/2026

There is no change in configuration.