Migration from v1.8 to v1.9

Overview

Version 1.9 continues to use Flyway for all database schema changes introduced in v1.8. Existing v1.8 installations are already under Flyway control, so no baseline properties are required for this upgrade: all pending migrations are applied automatically on the first startup.

The main change that requires attention during migration is how the task notification e-mail body is configured: it now points to an HTML template file instead of holding the message text directly in okmflow.properties.

Migration steps for existing v1.8 installations

1. Download OKMFlow 1.9 from https://download.openkm.com/pro/tools.
2. Stop Tomcat and replace the okmflow.war archive.
3. Review $TOMCAT_HOME/okmflow.properties:
   • If task.notification.body or task.notification.overdue.body were customized with inline text, they must be converted. Starting with v1.9, these properties point to an HTML template file instead of holding the text directly:

     # Before (v1.8)
     task.notification.body=A workflow task has been assigned
     
     # After (v1.9)
     task.notification.body=file:/path/to/custom-task-assignment-body.html

     Move the previous text into an HTML file on disk and point the property to it with a file: prefix, or remove the override entirely to fall back to the new bundled default template (a friendlier, better formatted notification e-mail).

   • task.notification.subject keeps working as before (a plain text/FreeMarker string). A new, equivalent task.notification.overdue.subject property is now available to customize overdue task notifications independently of assignment notifications.
   • Optionally enable the new purge jobs to keep the database from growing indefinitely. All are disabled by default, so no action is required to preserve the current v1.8 behavior:

     # Delete ended process instances (and their tasks, variables and logs)
     # older than the retention period
     process.instance.purge.enabled=false
     process.instance.purge.cron=0 0 3 * * *
     process.instance.purge.retention.days=90
     
     # Delete process instance audit log rows older than the retention period
     process.instance.log.purge.enabled=false
     process.instance.log.purge.cron=0 0 2 * * *
     process.instance.log.purge.retention.days=90
     
     # Delete variable audit log rows older than the retention period
     variable.log.purge.enabled=false
     variable.log.purge.cron=0 0 2 * * *
     variable.log.purge.retention.days=90

4. Start Tomcat. Flyway applies all migrations after v1.8 automatically, including the new activity log table for workflow variable changes and the indexes added to improve performance on large installations.

Fresh installations

New installations do not require any manual migration steps. Flyway detects an empty database and applies all migrations in order.