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 "daily" build depending on your appetite for new features vs stability.

The installation process itself is simply a case of installing "on top" of the previous installation. However, while we take great care to ensure upgrades are backwards-compatible (i.e. files created by the older app should be unaffected by the upgrade), for production systems you should take precautions of backing up Omniscope's managed data folders and configurations first. 

Note if you are downgrading your Omniscope installation, you must always take backups, and may need to restore previously created backups from the older version (which you should retain for some time); we do not aim for 'forwards compatibility'; it is quite possible that files created by newer versions will not be compatible with older versions, and problems may not be immediately apparent.

Windows: Upgrade process summary

1. Quit Omniscope (stop the process or service); e.g. on Windows, right-click the blue system tray icon and choose "Exit"
2. Backup files and configuration (see below).
3. Install new version "on top"
4. If you have previously modified the cacerts file (found in the backup), restore the updated file to the updated installation folder in the same location. You will find it at <Visokio Omniscope app install dir>/x64/lib/security/cacerts.
5. Start Omniscope
6. Test your workflows execute and dashboards are displayed correctly
7. Occasionally, report data must rebuild from execution data. This is only necessary in rare cases and typically only when downgrading Omniscope. See below.
8. Keep the backup until the next upgrade, should you need to rollback at a later date.

Linux: Upgrade process summary

1. Quit Omniscope (stop the process or service); See Linux installation page for more details.
2. Backup files and configuration (see below)
3. Delete current installation folder.
4. Extract the latest tgz file as mentioned in the linux installation guide (Linux installation).
5. If you have previously modified the _launch.sh file (found in the backup you have created in step 2) you would need to now re-apply those changes to the latest version.
6. If you have previously modified the cacerts file (found in the backup), restore the updated file to the updated installation folder in the same location. You will find it at visokio-omniscope/x64/lib/security/cacerts.
7. Start Omniscope as per installation guide.
8. Test your workflows execute and dashboards are displayed correctly
9. Occasionally, report data must rebuild from execution data. This is only necessary in rare cases and typically only when downgrading Omniscope. See below.
10. Keep the backup until the next upgrade, should you need to rollback at a later date.

What to back up

• Your sharing folder, typically "<USER_HOME>/omniscope-server/files/".
  This contains all your project ".iox" files, and corresponding ".data" folders adjacent to each one, containing file-specific data (execution data, for example) that Omniscope manages.
  
  
• The rest of the "<USER_HOME>/omniscope-server/" folder,
  e.g. config.xml containing the server global configuration.
  
  
• Other internal Omniscope data in your user profile:
  Windows: <USER_HOME>\App Data\Local\Visokio
  Mac: /users/<username>/Library/Application Support/Visokio
  Linux: /home/<username>/.visokioappdata
  (this includes the report data that can be rebuilt from execution data as per below)
  
  
• Linux users - it is highly recommended to backup the entire previous installation folder visokio-omniscope folder before proceeding with new installation. This is so that you can always revert back to the previous version if something goes wrong.
  
  
• Windows and Linux in corporate environments - if you previously customised the cacerts file to include some trusted certificates, you should back up and restore <visokio omniscope app install>/x64/lib/security/cacerts.

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.