# 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//` | 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//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: ``` 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//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//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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tomorrowx.com/cap/product-reference/installation-and-configuration/upgrading-to-v12.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.