Upgrading Omniscope to a latest version

This article describes best practice for upgrading Omniscope to a latest version, both for desktop and production server installations.

We recommend installing a "Rock" build on production servers, or you can pick the last "Preview" for newest features.

TABLE OF CONTENTS

• Upgrade Policy & Compatibility
• Windows: Upgrade process summary
• Linux: Upgrade process summary
• What to back up
  • 1. Project Files & Server Config
  • 2. Internal Application Data
  • 3. Custom System Configurations
• Fixing report data

Upgrade Policy & Compatibility

• Standard Upgrades: The process is designed to be "install-on-top." Omniscope maintains backward compatibility, meaning files created in older versions will work seamlessly in the new version. However, for production environments, you should always back up managed data folders and configurations before proceeding.
• Downgrade Warning: While we endeavour to support downgrades, it's not always supported and can result in corrupted projects. 
• Rollback Requirement: If a downgrade is necessary, you must restore the backups created before the upgrade. We recommend retaining these backups until you have fully verified the stability of the new version..

Windows: Upgrade process summary

This method ensures that custom security configurations are preserved and that a clean rollback is possible if the new version encounters environment-specific issues.

1. Graceful Shutdown:

   • If running as a Service: Open services.msc and Stop the "Omniscope" service.

   • If running Interactively: Right-click the blue Omniscope icon in the system tray and select Exit.

2. Snapshot/Backup Environment (see "What to back up" section below).

3. Execute Installer: Run the new Omniscope .exe installer.

   • Note: Ensure you install into the exact same directory as the current version (e.g., C:\Program Files\Visokio Omniscope or the local AppData path). The installer will manage overwriting the binaries while leaving your data intact.

4. Restore Security Configurations:  If you previously added custom SSL/TLS certificates to the Java keystore, copy your backed-up cacerts file back to: <Install_Dir>\x64\lib\security\cacerts.

5. Service Restart: Start the Omniscope service (or relaunch the application).

6. Functional Verification:  Log in to the Admin Web App.

   • Open and "Refresh" a sample of key workflows and dashboards to ensure the data engine is responding correctly.

7. Data Engine Maintenance: If dashboards show errors after a major version jump, navigate to Admin App > Data Engine and Storage > Fix all tables. This will rebuild the report cache from the underlying execution data.

8. Retention: Retain the version-specific backup created in Step 2 until the next successful upgrade cycle.

Rollback Path

If the upgrade fails:

1. Stop the Omniscope service.

2. Uninstall the new version via Control Panel.

3. Reinstall the previous version's installer.

4. Restore the AppData\Local\Visokio and omniscope-server folders from your backup to ensure the configuration state is reverted.

5. Restart the service.

   
   

Linux: Upgrade process summary

This method uses folder renaming instead of deletion to ensure an instant rollback path if needed.

1. Stop the Service: Gracefully shut down the Omniscope process (e.g., sudo systemctl stop omniscope or your specific init script). See Linux installation page for more details.

2. Backup Environment (see "What to back up" section below).

3. Stage New Version: Extract the latest .tgz file into a new, separate folder (e.g., visokio-omniscope-NEW) to avoid mixing old and new binaries.

4. Migrate Configurations: Copy any custom configurations from your old installation folder to the new one:

   • Custom Launch Script: Re-apply changes to _launch.sh.

   • SSL Certificates: If you use a custom cacerts file, copy it to visokio-omniscope-NEW/x64/lib/security/cacerts.

5. Swap Directories : Rename the folders to activate the new version.

   • Rename the current live folder: mv visokio-omniscope visokio-omniscope-OLD

   • Rename the new folder to live: mv visokio-omniscope-NEW visokio-omniscope

6. Start & Verify: Start the Omniscope service. Monitor the logs to ensure a clean startup and verify that workflows/dashboards load correctly.

7. Data Engine Check: In rare cases (usually only when downgrading), report data may need to be rebuilt. If a report fails to display, go to Admin App > Data Engine and Storage > Fix all tables.

8. Retention: Keep the visokio-omniscope-OLD folder and your backups until the next scheduled upgrade.

Rollback Path: If any issues arise, simply stop the service, delete the new folder, and rename visokio-omniscope-OLD back to its original name. You’ll be back online in seconds.

What to back up

Before upgrading, IT should take a snapshot or manual copy of the following three core components:

1. Project Files & Server Config

This is the most critical data. It contains your workflows and global settings.

• Path: <USER_HOME>/omniscope-server/

• Includes:  The /files/ subdirectory (all .iox project files and their .data execution folders).

  • The config.xml file (global server permissions and configurations).

2. Internal Application Data

This contains user profile data and report caches.

• Windows: %LOCALAPPDATA%\Visokio (typically C:\Users\<user>\AppData\Local\Visokio)

• Linux: /home/<username>/.visokioappdata

• Mac: /Users/<username>/Library/Application Support/Visokio

3. Custom System Configurations

If your environment uses custom SSL certificates or specialized launch parameters, back up these specific files from the Installation Directory:

• SSL Certificates: <install_dir>/x64/lib/security/cacerts (if you added trusted certs to the Java keystore).

• Linux Launch Script: visokio-omniscope/_launch.sh (if modified for memory allocation or environment variables).

Pro Tip for Linux: To ensure a 100% safe rollback, we recommend backing up the entire visokio-omniscope installation folder before deleting it for the upgrade.

Fixing report data

If there has been a major update of 'monetdb', the columnar database used by default for reports, Omniscope should automatically handle the update. If there are problems, the report data can be rebuilt from scratch (this will take some time) from the execution data that will also be kept within the sharing folder ".data" folders. 

See this article for advice on data engine problems; in particular follow Section D for advice on how to let Omniscope fix your tables.