Preparing a Planning Analytics version 11 database for migration to TM1 Database 12

Prior to migrating a TM1 Database 11, you must perform some environment and database maintenance to ensure a clean migration.

About this task

The TM1 Database 12 Migration Utility must be run on the machine that hosts the Planning Analytics version 11 database. This is mandatory and is required to preserve any locale information and to avoid loss of model objects.

Procedure

  1. Ensure that you have free disk space at least 2.5 times the size of the original TM1 Database 11 and enough RAM to load it on the machine used to run the migration.
  2. To make sure that all cube changes are up to date, shut down the TM1 Database 11 prior to migration. Alternatively, if you want to perform a migration while the version 11 database is running, perform a SaveDataAll to materialize any in-memory changes to the respective cube files.
  3. Ensure that the database's Tm1s.cfg configuration file exists and refers to the correct database directory. The configuration file must contain a DatabaseDirectory=<path> line, where <path> is the path to the actual data files relative to the Tm1s.cfg file.

    If you have any other directories outside of the database directory that you want to include as part of migration, move them into the database directory. Otherwise the migration utility will ignore those directories.

  4. Ensure that process data source files are accessible on the machine where you will run the migration tool.

    Processes are migrated even if the data source files are not accessible to the migration tool, but if the data source file is inaccessible, the process does not run during migration. A warning is issued if this occurs. After the migrated database is loaded into TM1 Database 12, you can modify the process to run successfully using either of these options:

    • Upload the data source file via the REST API to ~/Contents('Files')/Contents), and modify the process data source location accordingly
    • Modify the process to use a valid URL to the data source file's remote location
  5. Delete or repair views that refer to elements that no longer exist.
  6. Load the data into a recent TM1 Database 11 and explicitly save data to ensure that feeders are written out in the latest format.
  7. Optionally, choose which Planning Analytics clients are migrated to TM1 Database 12 and change their names to align with the new authentication framework.
    1. In the }ClientProperties control dimension, add a member named CloudID.
    2. In the }ClientProperties control cube, for each client that you wish to migrate, add its new TM1 Database 12 name to the CloudID cell.

      If you complete these steps, then only the clients for which you have defined a CloudID name in the }ClientProperties cube are migrated. Their private views and subsets are migrated under the specified CloudID names. Clients without a defined CloudID names are not be migrated.

      If you don't add the CloudID element to the }ClientProperties dimension, then all clients and their private objects are migrated with their original names.

      Note that if you provide a CloudID name for the Admin client, its private objects are migrated to the new name.

  8. If a dimension with multiple hierarchies has the same leaf element defined with conflicting element types in different hierarchies, resolve the conflicts so that the element type is consistent in all hierarchies.

    If the conflicts are not resolved, the dimension is not be migrated and the migration tool stops after the first such dimension is encountered.

    Here's an example of an error that occurs where an element is encountered twice in a dimension, once as a Numeric type and once as a Consolidated type.

    error   2022-12-09T20:19:15.560Z   Element's type conflicts with previously encountered element.   dimension, organization:By VP   element, VP3   prior dimension, organization:Leaves   prior element, VP3   prior type, N   service, tm1-i-0-d-0-0   type, C   version, 12.0.0-beta.5   TM1.Migration
error   2022-12-09T20:19:15.560Z   Dimension organization:By VP was rejected: ValidateNewElement failed for 1 element   name, organization:By VP   service, tm1-i-0-d-0-0   type, Dimension   version, 12.0.0-beta.5   TM1.Migration
error   2022-12-09T20:19:15.562Z   Dimension organization was rejected: Unable to load dimension due to a problem with hierarchy organization:By VP   name, organization   service, tm1-i-0-d-0-0   type, Dimension   version, 12.0.0-beta.5   TM1.Migration
error   2022-12-09T20:19:15.562Z   ServerLoad: Could not load body for dimension.   dimension, organization   message, Unable to load dimension due to a problem with hierarchy organization:By VP   service, tm1-i-0-d-0-0   type, loading   version, 12.0.0-beta.5   TM1.Migration
error   2022-12-09T20:19:15.563Z   Server load failed: Could not create initial server objects.   server, tm1-i-0-d-0   service, tm1-i-0-d-0-0   version, 12.0.0-beta.5   TM1.Migration

    In this example, the VP3 element had originally been defined as a Numeric type in organization:Leaves but is defined again in organization:By VP as a Consolidated type, which is a conflict. This must be repaired in organization:By VP in the TM1 Database 11.