Configuration migration

Configuration options for the TM1 Server and TM1 Admin Server, including custom encryption certificate stores, must be manually ported from a Planning Analytics 2.1.7 or earlier deployment to your Planning Analytics 2.1.8 and later installation.

You should save configuration information for the following components prior to uninstalling Planning Analytics 2.1.7 or earlier and then manually apply the configuration settings to your new installation.

TM1 Server configuration

To save configuration for a TM1 Server, copy the tm1s.cfg file in the data directory for each server in your Planning Analytics 2.1.7 or earlier environment. You can then refer to the settings to configure a new server or paste the tm1s.cfg file into the data directory of a new server.

TM1 Admin Server configuration

To save configuration for a TM1 Admin Server in Planning Analytics 2.1.7 or earlier, open Cognos Configuration and click on TM1 Admin Server.

Configuration settings are shown on the Properties panel. Record the settings.

Cognos configuration showing TM1 Admin Server settings

You can also download the configuration settings to a file. While TM1 Admin Server is selected, click File > Export as.

After installing Planning Analytics 2.1.8 or later, you can configure the new TM1 Admin Server by applying your saved settings to the config.tm1admsrv.json file, located in the <install_dir>/bin64 directory.

SSL configuration

Any custom SSL certificates will need to be migrated to the new installation.

Save a backup of the <install_directory>\bin64\ssl directory from the Planning Analytics 2.1.7 or earlier installation. You might need to refer to the information in this directory after upgrading.

Review the tm1s.cfg files and the TM1 Admin server configuration in Cognos Configuration; either of these locations might point to keystore and stash (.kdb and .sth) files that contain SSL certificates. Make note of the location of these files so you can apply them to the new installation.

The TM1 Admin Server in Planning Analytics 2.1.7 or earlier uses Cognos Configuration to point to a keystore (.kdb) and stash (.sth) file that contains encryption certificates. Custom certificates may have been applied by either of these manners:

  • Custom certificates were added to the default keystore file (\bin64\ssl\ibmtm1.kdb). In this case, the Key database location property in Cognos Configuration points to the default ibmtm1.kdb file and Key database password location property points to the default ibmtm1.sth file, both in the <install_dir>\bin64\ssl\ directory. These files must be copied outside of the TM1 installation directory before uninstalling.

    After installing Planning Analytics 2.1.8 or later, the keystore and stash file should be placed in the <install_dir>\bin64\ssl\ directory of the new installation. The new TM1 Admin Server configuration file (config.tm1admsrv.json) will point to the same files in the <install_dir>\bin64\ssl\ directory by default. If these files are placed in another directory, then the TM1 Admin Server configuration file must be updated to point to the file location.

    The Server certificate property in Cognos Configuration identifies the certificate in the keystore file that is used for encryption. Make note of this property value and apply it to the tm1AdminKeyLabel property in the config.tm1admsrv.json.

    The keylabel, keyfile, and keystashfile properties in the tm1s.cfg file should be reviewed to confirm that they are accurately set to the correct values and locations after upgrading to Planning Analytics 2.1.8 or later.

  • Custom certificate keystore and stash files were created to store encryption certificates and Cognos Configuration is pointing to these files. In this case the Key database location and Key database password location properties will point to files other than the default ibmtm1.kdb and ibmtm1.sth. The custom .kdb and .sth files should be copied outside of the TM1 database installation directory before uninstalling Planning Analytics 2.1.7 or earlier.
  • After installing Planning Analytics 2.1.8 or later, the custom .kdb and .sth files should be placed in the correct location (for example, <install_dir>\bin64\ssl\ ) in the new TM1 Server installation.

    The Server certificate property in Cognos Configuration identifies the certificate in the keystore file that is used for encryption. Make note of this property value and apply it to the tm1AdminKeyLabel property in the config.tm1admsrv.json.