Migrating to Version 2.4.0 of the Semantic Workbench

24/04/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. This update is required for compatibility with PoolParty 10.

Note

As of PoolParty 10, the Recommender and Inference Tagging Workbench has been renamed to Semantic Workbench. This migration requires moving from old installations to a containerized deployment and performing a manual database migration.

Before beginning the migration process ensure the following prerequisites are met:

Ensure PoolParty 10 and add-ons are deployed. The Semantic Workbench service must be defined in your addons.yaml file. For more information, refer to the add-on services installation guide.
A valid license file is required (the same license used for your PoolParty 10 installation).
Before stopping the old service, backup the following files:
- Properties: /opt/poolparty/tomcat/webapps/recommender/WEB-INF/classes/application.properties
- Database: /opt/poolparty/data/workbench/sqlite_recommender_workbench.db

Stop the old Semantic Workbench service.
Configuration is now handled via environment variables in addons.yaml or a .env file, replacing the old workbench.properties.
Most variables in the addons.yaml match the PoolParty 10 .env file and do not need modification if using defaults. However, ensure the following:
- Compare your old properties with the environment section in addons.yaml for any custom overrides.
- Copy the recommender client secret from your old properties file and set it as: SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_PPT_CLIENTSECRET
The API endpoint path has been updated. External clients and bookmarks must be updated to reflect the new naming convention:
- Application URL: http(s)://<server-name>/SemanticWorkbench
- Recommender API Endpoint: /GraphSearch/api/recommend

The migration requires moving the legacy SQLite database into the new Docker named volume pp10_semantic-workbench_data. The steps for the database migration procedure are as follows:

Move the backup database to a staging area and rename it:

# Example staging path: /opt/pp_container/pp10/semantic-workbench_data/
mv sqlite_recommender_workbench.db semantic_workbench.db

Stop the service and use a temporary container to clear the new volume and inject the migrated database with the correct permissions (UID 1001):

# Stop the service
docker compose -f docker-compose.yaml -f addons.yaml down semantic-workbench

# Inject and set permissions
docker run --rm -u 0 \
    -v pp10_semantic-workbench_data:/to \
    -v /opt/pp_container/pp10/semantic-workbench_data/semantic_workbench.db:/from_db:ro \
    alpine sh -c 'rm -rf /to/* /to/.[!.]* 2>/dev/null || true; cp -a /from_db /to/semantic-workbench.db; chown -R 1001:1001 /to; chmod -R u+rwX,g+rwX,o+rX /to'

Verify the file exists in the volume before starting the service:

# Check volume content
docker run --rm -v pp10_semantic-workbench_data:/to alpine ls -la /to

# Start the service
docker compose -f docker-compose.yaml -f addons.yaml up -d semantic-workbench

In this section: