Running data migration
Data migration is a two-phase process in which you have to migrate the transaction data, and then the history data.
- 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 theyfs.api.history.disable
property to True. - Bring up your application server.
- Migrate your history data.
- Use the
customer_overrides.properties
file to set theyfs.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.
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.