Altair Panopticon Visualization Server Installation and Reference Help - Migration to Panopticon Visualization Server Version 2021.0 from Versions 17 or Older

Migration to Panopticon Visualization Server Version 2021.0 from Versions 17 or Older

These instructions assume that:

q you have an existing 17 or older server version installed and want to migrate the content to a new installation of the 2021.0 server.

q you want to keep running the old server with its content intact for a while.

We also show how keep the new server updated with changes made to workbooks on the old server.

All of the server content is stored in its application data <appdata> folder, the path of which is set in the DatawatchVDDAppData context environment property. For example, in Tomcat this would be in <tomcat_home>/conf/catalina/localhost/panopticon.xml or similar.

NOTE	Two Panopticon web applications should never share the same <appdata> folder, ensure that the new server is pointed at its own initially empty folder.

Some of the content can simply be copied from the old server to the new one, while some are now stored in a new format and need to be converted. The workbooks themselves can be migrated any number of times, essentially resetting the workbooks on the new server.

1. Copy All Content

Start by copying all files from the <old_appdata> to the <new_appdata>. You can selectively copy some files again later to keep the old and new server in sync (e.g., copy over a new set of workbook bookmarks). This completes the migration of the following:

q License file - The server will not start without a valid <appdata>/DatawatchLicense.xml. In 2020 you also have the option to use Altair units licensing instead of the XML file.

q Properties file - The set of properties in <appdata>/Panopticon.properties that the server understands changes between releases. The first time you start it, it will add new properties and remove old ones.

q Data table templates - These are stored as EXD files in <appdata>/Datatables/.

q Global caches / data extracts - The definition of a data extract (formerly "global cache") is stored in an EXG file in <appdata>/GlobalCaches/. Keep in mind that this will only make the definition available on the new server, you still need to refresh it to populate it with data.

q Bookmarks - Workbook bookmarks are stored as a pair of DBK and DBM files in a subfolder below <appdata>/Bookmarks/ with the same name as the workbook they belong to.

q Themes - Each theme is stored as a THM file in <appdata>/Themes/. The Light.thm and Dark.thm are standard and will be automatically created on the new server the first time it starts, so only copy those if you have modified them.

q Scheduled tasks - All scheduled tasks are in SCH files in <appdata>/Schedule/.

q Alerts - Alerts are stored per user, as ALT files in <appdata>/UserData/<username>/Alerts/.

q Sounds - These are sound files that can be used in alerts. If you have added any, they are in <appdata>/Sounds/.

2. Delete Old Content

Some content are specific to the server instance and/or is temporary in nature. Delete the following to avoid conflicts:

q Statistics - Delete the <appdata>/Statistics/ folder, the numbers collected only apply to the old server.

q Cached data - Delete the <appdata>/CacheData/ folder, the new server will create new caches as needed.

q Tokens - Delete the <appdata>/Tokens/folder, it holds authentication tokens for logged in users, and are server specific.

3. One Time Conversion

The format for some content has changed, and it will be converted to the new format when the server starts the first time. This conversion only happens if the new content format doesn't exist in the <appdata>, but the old format does. To repeat the conversion, you need to delete the new file and restart the server. Converting workbooks is covered in the next section.

q Server parameters

These are server-side parameters that override workbook parameters. In the old server, there was a global set of parameters in <old_appdata>/DefaultParameters.xml, and then you could also have parameters that applied to a particular workbook folder and were stored in <old_appdata>/Workbooks/<path_to_folder>/DefaultParameters.xml.

The 2020 server does not distinguish between global and folder parameters, and stores them all in a single place, in <new_appdata>/Parameters.json.

If the <appdata>/Parameters.json doesn't exist when the new server starts, it will create it, and if it finds <appdata>/DefaultParameters.xml and/or <appdata>/Workbooks/**/DefaultParameters.xml, it will import these into the new file.

4. Workbooks and Data Files

Workbooks and their change history are stored in a very different format in a repository inside the <appdata>/.repository/ folder. This enables web authoring and content synchronization in a cluster among other things.

Before version 2020, all workbooks were stored as individual EXW files in <appdata>/Workbooks/, and the folder structure in there was also reflected in the web UI. Every time a workbook was updated, a backup was placed in <appdata>/Archive/ which lets you go back to an earlier version by clicking the clock icon on the workbook's thumbnail in the web UI.

Set the repository.migrate.workbooks.path in Panopticon.properties on the new server to the absolute path to <old_appdata>/Workbooks/. If you want to migrate the entire change history to make it accessible on the new server, set repository.migrate.archive.path to the absolute path to <old_appdata>/Archive/.

NOTE

· At startup, the server retrieves various properties from a number of sources. Some are embedded within JAR-files, others are read from Panopticon.properties. The server merges these properties, and then overwrites the existing Panopticon.properties with a new version of the file. This ensures that the Panopticon.properties file will contain settings parameters that are new in the current version of the server, if the existing Panopticon.properties file was created and used with a previous version of the server. New parameters get added to the file, and parameters that have been renamed in the new version get updated.

In the procedure, some unsuitable values are also replaced, such as single backslash used as path separator, which gets replaced with escaped backslash (i.e., double backslash).

· You can add parameters manually to the Panopticon.properties file.

The first time the server starts, it will create an empty repository in <appdata>/.repository/, then scan these locations for EXW files, and import them into the repository.

Check the log file when the server has started. If an old workbook could not be migrated for some reason, the server logs this as a warning.

You can repeat this migration as many times as you like: stop the new server, delete the entire <new_appdata>/.repository/ folder, then start the new server. This provides a convenient way to keep the new server in sync with changes on the old server, assuming the old server is still in use.

NOTE

· If none of the properties are set, no migration happens.

· The <appdata>/Workbooks/ folder is not used by the 2020 server, we copied it only to migrate any folder parameters.

· If the repository already has content -- even an empty folder such as the user folder that is created the first time you log in to the server -- and the properties are set, the server skips migration and logs a warning.

When you published a workbook that used data files (e.g., CSV, Excel, XML) to an old server, the data file was also sent to the server which placed it in the <appdata>/Data/ folder. It also appended a timestamp to its file name and updated all references to it in the workbook to use the new file name.

In 2020, data files are normally stored in the repository instead, and version tracked there just like workbooks. The new server also rewrites data file references in workbooks that you publish to reflect that the file is in the repository.

The workbook migration does not move data files into the repository and rewrite workbooks that reference them. This means that for migrated workbooks (and old workbooks that you upload through the web UI) the server still expects to find the associated files in the <appdata>/Data/ folder.

5. Migrate Permission Settings

You need to manually apply workbook permissions set on the old server to the new server. The permissions model has changed significantly in 2020 with more user roles and more flexible permissions.

Migrating the permission settings of the workbooks folders involves the following steps:

5.1. Use PCLI convertpermissions to create a permissions template file that reflect the permission settings in the folders in the old <appdata>/Workbooks.

This will produce a JSON file which the new server can use as a template for automatically setting permissions on workbook folders inside the repository of the new server.

5.2. Set parameters in the Panopticon.properties file before starting the new Panopticon server, thereby instructing the server to find and apply the permissions template file. The parameters are:

repository.startup.apply.permissions.path=

repository.startup.apply.permissions.clean=false
repository.startup.apply.permissions.create=true

5.3. Stop the server and clear the value (the path) previously set on the repository.startup.apply.permissions.path parameter to avoid re-applying the template and over-writing existing settings at each server restart. This can be very important when permissions have been modified after the migration.

6. Do Not Make Changes on Both Servers

After the initial migration, you can keep the new server up to date when content changes on the old server by repeating any of the steps above. It is much harder to move content the other way, from the new server to the old. Therefore, avoid making changes (that you want to keep) on the new server until you've completely migrated and retired the old server.

7. Post-migration Cleanup

Once satisfied that the new server is running as it should, that all content has been migrated, switched users over to the new server, and are no longer using the old server, you can remove files from <new_appdata> that are no longer needed.

q <appdata>/Workbooks/ - This was really only needed to migrate folder parameters.You can delete the entire folder.

q <appdata>/Archive/ - Was never used on the new server (unless you used it as migration source). Delete the entire folder.

q <appdata>/DefaultParameters.xml - These are now in the JSON file, delete it.

q Migration properties - Clear the repository.migrate.workbooks.path and repository.migrate.archive.path in <appdata>/Panopticon.properties.