Migrating to Version 2.4.0 of the Semantic Workbench

24/02/2026

This section covers breaking changes and required actions when upgrading to version 2.4.0 of the Semantic Workbench. If you are performing a fresh installation, refer to Semantic Workbench Installation and Upgrade.

1. Deployment Model Change

The Semantic Workbench no longer uses standalone download scripts or WAR file deployments. It is now deployed as a cloud-native application using Docker containers orchestrated by a Helm chart on Kubernetes

Note

While the recommended installation method is via the public Helm chart, legacy support for WAR file deployments remains available. However, standalone download and uninstall scripts have been officially deprecated and removed from the distribution.

Required Actions (Helm and Kubernetes approach)

Provision a Kubernetes cluster (version 1.32+) if not already present
Install Helm (version 3.18+) and kubectl
Follow the installation steps in the Installation and Upgrade guide to deploy the application using the Helm chart
Migrate any custom workbench.properties settings to the configuration.properties section in your Helm values file

2. Environment Variable Configuration

Core configuration values are now provided via environment variables instead of being hardcoded in a workbench.properties file. The Helm chart manages these through Kubernetes ConfigMaps and Secrets.

Migration Steps

Extract values from your existing workbench.properties file
Map them to the corresponding configuration.properties keys in your Helm values file
For sensitive values (client secrets, passwords), use configuration.propertiesOverrides.existingSecret to reference a Kubernetes Secret

Property Mapping:

Old Property (`workbench.properties`)	New Helm Value (`configuration.properties`)
`poolparty.url`	`POOLPARTY_URL`
`poolparty.license.path`	`POOLPARTY_LICENSE_PATH` (auto-configured via `license.mountPath`)
`keycloak.url`	`KEYCLOAK_URL`
`keycloak.realm`	`KEYCLOAK_REALM`
`spring.security.oauth2.client.registration.ppt.clientId`	`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTID`
`spring.security.oauth2.client.registration.ppt.clientSecret`	`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTSECRET`
`spring.datasource.url`	`SPRING_DATASOURCE_URL`

3. API Endpoint Changes

The recommender API endpoint path has been updated as follows:

Old Endpoint	New Endpoint
`/recommender/api/recommend`	`/GraphSearch/api/recommend`

Required Action:

Update any external clients or scripts that directly call this endpoint
Note
Internal application calls are automatically updated.

4. Database File Name Change

The default database file name has been updated for consistency:

Old Name	New Name
`sqlite_recommender_workbench.db`	`sqlite_semantic_workbench.db`

Warning

Create a backup of your existing database file before upgrading!

Required Actions:

If using an external database: Update your database connection string using configuration.properties.SPRING_DATASOURCE_URL
If migrating Docker volumes: Ensure volume mounts point to the correct database file location

Manual migration (if necessary):

mv sqlite_recommender_workbench.db sqlite_semantic_workbench.db

5. Context Path Update

The application context path has been renamed:

Old Path	New Path
`/RecommenderWorkbench`	`/SemanticWorkbench`

Required Actions:

Update bookmarks and links to: http://your-server/SemanticWorkbench
Update reverse proxy configurations (nginx, Apache, etc.) where applicable
Update any CI/CD scripts or health check endpoints
If using the Helm chart Ingress, the context path is automatically set to /SemanticWorkbench

6. Java Version Requirement for Standalone Deployments

The minimum Java version has been upgraded.

Old Requirement	New Requirement
Java 17	Java 21 (Temurin recommended)

Required Action:

For standalone deployments: Upgrade your Java runtime to version 21 and update JAVA_HOME.
Note
Helm chart deployments are automatically handled by the container image. No action needed.

If you encounter issues after upgrading, perform a rollback:

# List release history
helm history semantic-workbench

# Roll back to a previous revision
helm rollback semantic-workbench <revision-number>

Manual Rollback:

Stop the application
Restore database backup

Revert to previous version by specifying the old image tag:

helm upgrade semantic-workbench poolparty-semantic-suite/workbench \
  --set image.tag=<previous-version> \
  -f values-override.yaml

Verify the rollback:

kubectl get pods -l app.kubernetes.io/name=semantic-workbench

In this section: