Running data migration

Data migration is a two-phase process in which you have to migrate the transaction data, and then the history data.

You can upgrade transaction data before history data in the following modes:
  • Nonsharded mode. Use the yfs.api.history.disable property to migrate transaction data before history data in nonsharded and sharded all-colony modes.
  • Sharded all-colony mode. Use the yfs.api.history.disable property to migrate transaction data before history data in nonsharded and sharded all-colony modes.
  • Sharded mode for individual colonies. Use the yfs.api.history.disable.colony.colony_id property to migrate transaction data before history data for individual colonies.

Additionally, you can use the yfs.api.history.disable property to upgrade history data before transaction data in sharded all-colony mode.

Between the time that you run your transaction data migration and your history data migration the following restrictions exist:

  • You are not able to purge any data
  • You are not able to access any history data using APIs until the history data migrations is complete.
  • You are not able to use the restoreOrder API, which moves an order from the history tables to the transaction tables. By default, Sterling Order Management System Software uses the restoreOrder API to move an order from the history table to the transaction table while creating a return for an order that has been purged to the history tables. Therefore, you are not able to create a return for a purged order until you finish your transaction data migration.

You should evaluate the impact of not being able to purge data or use the restoreOrder API, based on how your system is configured and customized.

The migration conducted for an "upgrade from version" directory is the most recent release directory. All migrations between Release 9.3 (or higher) to Release 10.0 are done from the 9.5 folder. In this case, you must see the INSTALL_DIR/Migration/9.5 folder.

For every command that is executed, log files and done files are generated in different folders depending on from which release you are migrating. For example, if you are migrating from Release 9.3, the files are generated in 9.3, 9.4, and 9.5 folders.

Migrating transaction data before history data in nonsharded and sharded all-colony modes

If you are upgrading to Release 10.0 in nonsharded mode or sharded all-colony mode and want to use the yfs.api.history.disable property to migrate transaction data before history data, follow this process:

  • Migrate your transaction data and then start the application. If you are performing a sharded upgrade, migrate the transaction data for all colonies.
  • Use the customer_overrides.properties file to set the yfs.api.history.disable property to True.
  • Bring up your application server.
  • Migrate your history data.
  • Use the customer_overrides.properties file to set the yfs.api.history.disable property to False. This step ensures the application can access the upgraded history tables.
  • Restart your application server.

Allocating memory in buildmigration.properties and ycdmigration.properties

During the upgrade process, you can pass JVM-specific JAVA and ANT arguments in INSTALL_DIR/Migration/9.3/buildmigration.properties and INSTALL_DIR/COM/Migration/9.3/COM_Add-in/ycdmigration.properties to avoid out-of-memory errors.

  • mem_java_args_sun=-Xms128m -Xmx1408m -XX:MaxPermSize=512m
  • mem_java_args_non_sun=-Xms128m -Xmx1408m
  • mem_ant_args_sun=-Xms128m -Xmx1408m -XX:MaxPermSize=512m
  • mem_ant_args_non_sun=-Xms128m -Xmx1408m

If similar out-of-memory errors are seen in other directories when doing upgrade, similar changes are required in the buildmigration.properties or ycdmigration.properties files in the kit-directories of the hops. For example, you can pass JVM-specific JAVA and ANT arguments in INSTALL_DIR/Migration/9.3/buildmigration.properties and INSTALL_DIR/COM/Migration/9.3/COM_Add-in/ycdmigration.properties to avoid out-of-memory errors for the corresponding directory.

Data migration custom document type

Factory setup changes made to document type specific entities between Release 9.3 and Release 10.0 must also be applied for custom document types. To apply the changes, you must provide the mapping between the custom document types and the system-provided document types. To provide this mapping, save the customdoctype.properties.sample file located in the INSTALL_DIR/Migration/9.5/transaction directory as customdoctype.properties. To modify the customdoctype.properties file, follow the instructions provided in the sample file.

The following tables are updated during custom document type migration:

  • YFS_Status
  • YFS_Transaction
  • YFS_Transaction_Pickup_Status
  • YFS_Transaction_Drop_Status
  • YFS_Event
  • YFS_Status_Modification_Type
  • YFS_Status_Modification

Data migration log files

The log files that are created by the ANT calls during migration may contain references to locations of other log files affected by the data migration. You must verify all the log files for any migration errors that occur when performing data migration.

Note: The log file is created in the directory from which the ANT command is executed.

For example, in a multihop upgrade when you run the following command, the upgrade-history-tables.log file is created in the INSTALL_DIR/Migration/9.5 folder:


${ANT_HOME}/bin/ant -Druntime=INSTALL_DIR 
-Druntime.old=YFS_HOME_OLD -f buildmigration.xml -logfile 
upgrade-history-tables.log -Dtarget=upgrade-history-tables 
migrate

This log file contains references to the log files that are created in the 9.4 folder. In such a scenario, the 9.4 migration folder must contain a log file named upgrade-history-tables-9.4-9.5.log, following the convention of the ANT target and hop version.