Upgrading to V12

This page describes the on-premise upgrade procedure to CAP V12 from an existing V11 installation (zip distribution). The procedure is a safe, reversible "copy HOME across" upgrade that preserves all of your existing credentials, repositories, user accounts, credential vaults, JDBC drivers, content, and configurations.

On first boot, V12 automatically re-encrypts all stored credentials with the new Phase 3 data-at-rest encryption scheme. A second, per-Agent migration of the Agent-side metadata key file runs automatically the first time each Programmable Data Agent loads its rules. Both migrations are transparent and require no action from you beyond following the upgrade procedure below.

Overview

The upgrade process consists of five phases:

1. Stop the running V11 Console

2. Prepare the new V12 distribution alongside the existing V11 install

3. Copy the V11 HOME directory content into the V12 install

4. Copy V11 configuration overrides (SSL certs, JDBC drivers, custom web.xml)

5. Start V12 and verify the automatic credential migration

The entire process typically takes 15 to 30 minutes depending on the size of your HOME directory.

After the upgrade, your V12 Console will continue to receive V11 update content until you explicitly opt in to V12 content. See "Switching to V12 update content" below for that step. This is intentional: it lets you run the V12 binaries against your existing V11 rules and content, and schedule the V12 content switch at a time that suits your environment.

Prerequisites

Before starting:

• A full backup of the existing V11 installation directory (the entire install, not just HOME)

• The V12 distribution zip file

• Approximately the same amount of disk space as your current V11 install

• Administrative access to the host (ability to stop and start the Console service)

Pre-upgrade checklist

Work through this checklist before proceeding with the upgrade:

1. Record the current V11 build number for reference. It is displayed in the Console UI footer and is also visible in the directory name under HOME/Applications/console/ (for example B21150).

2. Take a complete backup of your V11 install directory. Copy the entire install directory (including HOME) to a safe location.

3. Identify any customizations you have made to the V11 install directory outside HOME/ (the entire HOME/ folder is copied wholesale in Step 2, so its contents are automatically preserved):

   • SSL certificates and jetty-ssl-context.xml in server/etc/

   • Custom JDBC driver jars in server/lib/ext/jdbc/

   • Any modified web.xml files

   • Custom magic.properties files

4. Confirm the V11 Console is stopped cleanly. If running as a service, stop it through standard service controls. If running interactively, use the Console UI shutdown or close the terminal session cleanly.

5. Confirm there are no active Derby lock files. With the Console stopped, the files HOME/Data/Coop/db.lck and HOME/Data/Coop/dbex.lck are sentinels left by Derby on clean shutdown and are safe to leave in place. Confirm the Console is not still running in another process.

The upgrade procedure

Step 1: Unzip the V12 distribution

Unzip the V12 distribution to a new directory alongside (not over the top of) your V11 install. For example:

/opt/cap/CAP-Console-11.0     <-- existing V11 install
/opt/cap/CAP-Console-12.0     <-- new V12 install (fresh unzip)

Do not start V12 at this stage.

Step 2: Copy HOME content from V11 to V12

Your HOME/ directory contains all of your customer-owned state: rule repositories, rulesets, configurations, credentials, user accounts, audit history, content files, test data, trace data, Case Managers, and more. The V12 distribution ships with a minimal HOME/ that needs to be replaced with your V11 HOME/ content.

The procedure is: copy the V11 HOME/ wholesale into V12, then restore the V12 distribution's HOME/Applications/ folder (which contains the V12 webapp binaries, not customer data). Add or remove any agent webapps that do not match between the V11 and V12 layouts.

# Save the V12 distribution's fresh Applications folder (V12 webapp binaries)
mv /opt/cap/CAP-Console-12.0/HOME/Applications /tmp/v12-applications

# Replace V12 HOME with V11 HOME content
rm -rf /opt/cap/CAP-Console-12.0/HOME
cp -R /opt/cap/CAP-Console-11.0/HOME /opt/cap/CAP-Console-12.0/HOME

# Restore the V12 Applications folder
rm -rf /opt/cap/CAP-Console-12.0/HOME/Applications
mv /tmp/v12-applications /opt/cap/CAP-Console-12.0/HOME/Applications

# Remove stale Derby lock files from the copied data
find /opt/cap/CAP-Console-12.0/HOME -name "*.lck" -delete

What the HOME subdirectories contain

For reference, copying the whole HOME/ preserves the following. Every item below is customer-owned state that must carry forward to V12.

Path	Contents	Impact if lost
HOME/Data/	Derby databases: Coop (users, PDAs, credential vaults, JDBC drivers, log adaptors, audit log), config, and any extension-specific databases	Total loss of user accounts, Agent definitions, credentials
HOME/Console/repositories/	Ruleset repositories with full change history	Total loss of rule development history
HOME/Console/rulesets/	Active ruleset XML files	Loss of running rule configurations
HOME/Console/configurations/	Deployed configuration files per Agent	Loss of Agent deployment state
HOME/Console/catalogues/	Rule catalogue definitions	Loss of custom rule organization
HOME/Console/content/	Web content files served by rules	Loss of content deployed to Agents
HOME/Console/data/	Data files used by rules	Loss of rule data inputs
HOME/Console/testdata/	Test data for rulesets	Loss of ruleset test fixtures
HOME/Console/tracedata/	Captured trace data	Loss of debugging captures
HOME/Console/performance/	Performance capture data	Loss of performance baselines
HOME/Console/casemanagers/	Case manager configurations	Loss of Case Manager state
HOME/Console/protocols/	Custom protocol definitions	Loss of Multi-Protocol customizations
HOME/Console/roles/	Custom user roles	Loss of access control configuration
HOME/Console/rules/	Cached rule definitions	Regeneratable, but slow on first use
HOME/Console/backups/	Console's own ruleset backups	Loss of undo/restore history
HOME/Console/console/	The Console Agent's runtime state: ActiveRules.xml, metadata, global.properties	Console Agent becomes inoperable
HOME/Console/consolex/	The ConsoleX Agent's runtime state (introduced in base image May 2021)	ConsoleX Agent becomes inoperable
HOME/Console/temp/	Transient working files	None - safe to skip
HOME/<AgentName>/	One directory per Programmable Data Agent (e.g. TestServer1, StressTest1, LocalProxy, MPServer1, plus any custom Agents). Each contains that Agent's ActiveRules.xml, metadata, and runtime state	Agent becomes inoperable
HOME/Applications/	Not customer data. Contains the Console webapp binaries shipped with the distribution. This is why the procedure above restores the V12 Applications folder after copying the V11 HOME.	N/A - replaced by V12 distribution

If you prefer to copy subdirectories individually rather than using the wholesale approach above, ensure you include every subdirectory under HOME/ except HOME/Applications/ and the various temp/ folders. Forgetting any of them will result in lost repository history, lost rulesets, or inoperable Agents.

Step 3: Copy V11 configuration.properties to V12

The configuration.properties file contains your mail server, proxy, and master console settings. It lives inside the webapp directory, which has a version-specific name.

Locate the V11 file (the build number in the path depends on your V11 version, e.g. B21150):

/opt/cap/CAP-Console-11.0/HOME/Applications/console/B21150/WEB-INF/classes/configuration.properties

Copy it to the corresponding V12 location (the V12 build number is different, e.g. B30000):

cp /opt/cap/CAP-Console-11.0/HOME/Applications/console/B21150/WEB-INF/classes/configuration.properties \
   /opt/cap/CAP-Console-12.0/HOME/Applications/console/B30000/WEB-INF/classes/configuration.properties

Step 4: Preserve V11 customizations

Copy any customizations you identified in the pre-upgrade checklist:

• SSL certificates and modified jetty-ssl-context.xml from the V11 server/etc/ into the V12 server/etc/

• JDBC driver jars not shipped with the V12 distribution, from CAP-Console-11.0/server/lib/ext/jdbc/ into CAP-Console-12.0/server/lib/ext/jdbc/

• Modified web.xml files (if you adjusted Jetty session ID cookie flags or similar) into the corresponding V12 webapp WEB-INF/ directory

• magic.properties overrides into the corresponding V12 webapp WEB-INF/classes/ directory

Step 5: Update service wrappers

If you previously installed V11 as a Windows service or a Linux systemd service, update the service definition to point to the new V12 installation directory. The typical pattern is:

1. Stop the existing V11 service

2. Uninstall the existing V11 service

3. Install a new V12 service pointing at the V12 directory

4. Ensure the service script is executable:

   chmod 755 /opt/cap/CAP-Console-12.0/server/bin/tomorrow.sh

Alternatively, if you prefer to preserve the service name and path, you can rename the V12 install to match the original path:

mv /opt/cap/CAP-Console-11.0 /opt/cap/CAP-Console-11.0.backup
mv /opt/cap/CAP-Console-12.0 /opt/cap/CAP-Console-11.0

Either approach works. The important thing is that your service wrapper launches the V12 binaries against the V12 HOME directory.

Step 6: Start V12

Start the V12 Console. Watch the startup log (by default server/logs/stderrout-YYYY_MM_DD.log).

What happens on first boot

On the first boot after upgrade, V12 performs a one-time automatic migration of your stored credentials. This migration:

• Generates a new installation-specific key file at HOME/Data/installation.key with owner-only file permissions

• Re-wraps the Console master key with the new installation key

• Re-encrypts all credential vault values, JDBC driver credentials, and RulesServer mail/proxy/encryption credentials under the new AES-256-GCM envelope

• Re-encrypts any populated mail/proxy/master-console passwords in configuration.properties

The migration is logged to the startup log with two lines:

INFO: V12 Phase 3 credential encryption migration starting...
INFO: V12 Phase 3 credential migration complete - master re-wrapped: true,
      CredentialsVault values: N1, JdbcDriver rows: N2, RulesServer rows: N3,
      global properties: N4

Typical migration time is well under a second even on installs with many credentials. The counts depend on how much of your V11 data was populated.

Per-Agent metadata key migration

Each Programmable Data Agent has its own per-Agent encryption key stored in HOME/<AgentName>/metadata. On V11 this file contains the key buried inside about 14 KB of random padding. On V12 the file format is simpler: a single version byte followed by 32 random bytes, with owner-only file permissions.

The first time each Agent's rules engine loads its configuration after upgrade, V12 detects the V11 metadata format, recovers the Agent's existing key, and rewrites the file in the new format in place. One INFO line is logged per Agent:

INFO: Migrated PDA metadata file to V12 Phase 3 format: <path>

This migration is transparent and lazy. Agents that are never started against V12 retain the V11 metadata format and keep operating through V12's legacy decrypt paths.

ActiveRules.xml credential format

Existing ActiveRules.xml files carry forward with V11 credential encryption (:% prefix). V12 continues to decrypt these values via its legacy decrypt path, so every existing Agent keeps working without change. New-format (:# prefix, AES-256-GCM with random IV per field) credentials only appear in ActiveRules.xml the next time you redeploy the Agent through Console. This is an operator-controlled rollout, not an automatic migration. Agents that never redeploy stay on V11 credential format forever; Agents you redeploy pick up the new format.

The legacy V11 decryption code remains present in V12, so partial or interrupted migrations are safe: V12 can always read V11-format data via its legacy decrypt paths. If migration is interrupted, simply restart the Console and the remaining records will be migrated on the next boot.

Verifying the upgrade

After the Console starts successfully:

1. Confirm the migration log lines are present in the startup log

2. Confirm the installation.key file exists:

   ls -la /opt/cap/CAP-Console-12.0/HOME/Data/installation.key

   This file should be exactly 32 bytes with 0600 (-rw-------) file permissions on POSIX systems.

3. Log in to the Console UI as one of your existing users. All user accounts and their passwords carry forward unchanged.

4. Navigate to a Credential Vault entry and confirm values are still displayed correctly.

5. If you have RulesServer entries with encryption keys, mail credentials, or proxy credentials, confirm those Agents connect and operate as expected.

6. If your Console reaches out to an update server, confirm the update server communication is operational (this uses the encrypted license key field). At this stage your Console is still configured to receive V11 update content; the next section describes how to switch to V12 content when you are ready.

7. Restart the Console once more. The second startup should not produce any migration log lines, confirming the migration is complete and idempotent.

Switching to V12 update content

The Console upgrade procedure described above replaces the Console binaries but deliberately does not change which update content stream your Console receives. Your Coop database carries forward exactly as it was, including the existing "Version 11" Target Version, and your V12 Console continues to poll the V11 update endpoint (https://updates.tomorrowx.com/TomorrowAdmin110) until you add a "Version 12" Target Version.

Fresh V12 installations get the V12 Target Version automatically as part of first-boot seeding. Upgraded installations require this one manual step.

Adding the Version 12 Target Version

1. Log in to the V12 Console as an administrator.

2. Navigate to Configuration, then Versions.

3. Click "Create new target version" and complete the form with these exact values:

   Field	Value
   Version name	Version 12
   Version mask	12.
   Version update path	120
   Allow protocol language editing	enabled

4. Save. The Console creates three new directories on disk to hold V12 content:

   HOME/Console/rules/Version 12/
   HOME/Console/catalogues/Version 12/
   HOME/Console/protocols/Version 12/

   Your existing "Version 11" directories remain in place; no V11 content is moved or modified.

Installing the V12 bootstrap extension

The Version 12 Target Version is initially empty. Before you can deploy any V12 content, install the bootstrap extension RulesBaseFactory, which provides the V12 rules base SDK that all other V12 extensions depend on.

1. In Configuration, then Updates, trigger a check for updates. The Console queries the V12 update endpoint (https://updates.tomorrowx.com/TomorrowAdmin120) using your existing licence key.

2. Locate RulesBaseFactory in the available extensions list and install it.

3. Restart the Console after the install. On startup the Console rebuilds the Version 12 catalogue from the contents of HOME/Console/rules/Version 12/.

After this step, the V12 rule palette is populated and you can install further V12 extensions, deploy V12 repositories, and develop new content against Version 12. Your V11 Target Version remains fully usable in parallel for as long as you need it.

Migrating existing V11 content to V12

Existing repositories, rulesets, and Agents stay associated with the "Version 11" Target Version after the upgrade and continue to operate unchanged. To carry V11 content forward into V12:

1. Create a new repository in the Console with target version "Version 12".

2. Export the V11 repository (Repository, then Export) to a zip file.

3. Import the V11 zip into the new V12 repository (Repository, then Restore).

The Console rewrites the version stamp from "Version 11" to "Version 12" in the imported configuration files automatically. The original V11 repository is not modified by the import; you can run V11 and V12 versions of the same content side by side during transition.

Backup implications (important)

The V12 data-at-rest encryption scheme introduces a new file, HOME/Data/installation.key, that is required to decrypt any credentials stored in the Coop database.

Your backup procedure must be updated to include this file. A backup of HOME/Data/ without installation.key is unrecoverable; the Coop database contents cannot be decrypted without the matching installation key.

The file is 32 bytes, so including it in backups is effectively free. Typical backup strategies:

• Whole-HOME backup - if your existing backup already captures the entire HOME/Data/ directory recursively, installation.key is included automatically. Verify this on your next scheduled backup.

• Selective backup - if you back up individual files or subdirectories, add HOME/Data/installation.key to the set.

Store the installation key with the same security controls as the Coop database backup. Anyone with both the Coop backup and the installation key can decrypt the stored credentials offline.

Per-Agent metadata files

By the same principle, each Agent's HOME/<AgentName>/metadata file is required to decrypt that Agent's ActiveRules.xml. An ActiveRules.xml backup without the matching metadata file cannot be decrypted. Whole- HOME backups cover this automatically; selective backups must include HOME/<AgentName>/metadata for every Agent that is backed up.

The new V12 metadata file is 33 bytes. The V11 file is about 14 KB. Either format is equally small compared to typical backup sizes.

Troubleshooting

Migration log line not present

If the startup log does not contain "V12 Phase 3 credential encryption migration starting", one of the following has happened:

• The Console is running V11 binaries, not V12. Verify the service wrapper points at the V12 installation.

• The Console is running against a freshly created (empty) HOME. The migration only runs when V11 data is present. A fresh install skips migration because there is nothing to migrate.

• The migration has already run on a previous boot. Check for the presence of HOME/Data/installation.key. If present, migration is already complete.

Migration log reports 0 for all counts

This is normal if your V11 install had no populated credentials. A fresh V11 install from the Data.zip baseline contains only a small number of seeded credentials; all the visible counts may legitimately be zero on a lightly used install. The migration still generates the installation key and re-wraps the master so the encryption scheme is upgraded.

Migration log reports a failure

If the startup log contains "V12 Phase 3 credential migration failed", your credentials remain readable via the legacy decrypt paths and the Console will continue to operate normally on V11-format data. The migration will retry on the next boot. Contact TomorrowX support with the full log output.

Cannot log in after upgrade

User accounts and passwords are not changed by the upgrade. If you cannot log in:

• Confirm you are logging in to the V12 Console (check the build number in the UI footer)

• Confirm the HOME directory copy completed successfully. If the HOME/Data directory on V12 is empty or contains only the Data.zip baseline, your V11 data did not copy correctly. Revert to backup and repeat step 2.

• Confirm you are using a user account that existed in V11. Only seeded default accounts (admin, super, security) exist on a fresh install.

Reverting to V11

If the upgrade is not successful and you need to revert:

1. Stop the V12 Console

2. Restore your V11 installation from the backup taken in the pre-upgrade checklist

3. Start the V11 Console

Your V11 HOME directory is not modified by the upgrade procedure (only copied from), so it remains usable as-is. The V12 installation directory can be deleted and re-created from a fresh V12 zip if a retry is wanted.

After the upgrade

• Update your backup procedures to include HOME/Data/installation.key as part of any backup that covers HOME/Data/

• Store the V11 installation backup for at least one full backup cycle in case a rollback is needed

• Existing deployed Programmable Data Agents continue to run against V11 agent binaries until you choose to redeploy them against the V12 Console

Please refer to the release notes for the specific V12 build you installed for any version-specific post-upgrade steps.