Staged upgrade from release 9.3 or later

If you are running version 9.3 or later of Sterling™ Order Management System Software, you could migrate to Sterling Order Management System Software release 10.0 through a staged rollout upgrade approach by migrating the transaction and history data.

About this task

Perform the following migration steps to migrate Sterling Order Management System Software from Release 9.3 or later to Release 10.0 in a staged rollout upgrade mode.

Note: In this topic, <INSTALL_DIR_OLD> refers to the previous version environment.

Process to be performed before history and transaction migration

Procedure

Set USE_OLD_INDEX_CHANGE_HANDLER=false property in the 9.5 environment in the <INSTALL_DIR_OLD>/properties/sandbox.cfg file.
Run the setupfiles script.
Navigate to the <INSTALL_DIR>/Migration/9.5 directory.
Run the following command:
${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> -f buildmigration.xml -logfile <logfile> -Dtarget=copyextensions migrate.

The copy extensions target moves some of the extension files to the <INSTALL_DIR_OLD>/extensions/global/entities directory.
Run the following command:
```
${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> -f 
buildmigration.xml -logfile <logfile> -Dtarget=initupgrade migrate
```
This command performs the following tasks:
- Compares the entity XML files from the previous release with the entity XML files in Release 9.5.
- Generates the alter scripts for shard migration.
  The *.done files created in the 9.5 status folder for the task initupgrade task are:
- history_ant_upgradepreparation.xml.done
- transaction_ant_upgradepreparation.xml.done
If the initupgrade command fails for a reason other than an Invalid Index Definition error and you have to restart this task, run the following commands:
- ```
${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> 
-Druntime.old=<INSTALL_DIR_OLD> -f buildmigration.xml -logfile 
<logfile> -Dtarget=clean-up-for-rerun migrate
```
- From the <INSTALL_DIR>/COM/Migration/9.5/COM_Add-in directory:
```
${ANT_HOME}/bin/ant -f ycdmigration.xml -Druntime=<INSTALL_DIR> -Druntime.old
=<INSTALL_DIR_OLD>
-DYANTRA_RUNTIME_NEW=<INSTALL_DIR>
-Dtarget=clean-up-for-rerun migrate -logfile <logfile>
```
This command deletes the /history and /transaction subfolders located in the <INSTALL_DIR>/Migration/9.5/database/scripts/<db version> directory. This command also deletes the extensions that were copied by running the copyextensions target.
- You must change the value of the onerror attribute from "abort" to "continue" in the Migration/9.5/ant_premigration_process.xml file before running the clean-up-for-rerun target.
- After running the clean-up-for-rerun target, you must perform the copyextensions task and the initupgrade task again.
If you are using Oracle, after running initupgrade successfully, modify the generated scripts located in the <INSTALL_DIR>/Migration/9.5/database/scripts/oracle directory to use the correct tablespace. This includes scripts in the /history and /transaction subfolders located in the this directory. For text search indices, the scripts are located in the <INSTALL_DIR>/Migration/9.5/database/scripts/oracle directory.
If you are running an upgrade in sharded mode, perform this step to delete stale records from the PLT_DB_COLONY_POOL table and the PLT_DB_POOL table:
${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> -f buildmigration.xml -logfile <logfile> -Dtarget=delete-stale-colony-pool migrateHere, old runtime is the 9.5 environment .

The *.done file created in the 9.5 status folder for the delete-stale-colony-pool task is ant_deletecolonypools.xml.done.
To enhance system performance, you can modify the following properties in the <INSTALL_DIR>/Migration/9.5/buildmigration.properties file:
- yfs.upgrade.no.of.threads.for.tablealters
  This property determines the number of threads that are used to process alter scripts. By default, this value is set to 6. For example, if 10 alters are generated by initupgrade and yfs.upgrade.no.of.threads.for.tablealters is set to 6, 6 threads will process the 10 alters.
- yfs.upgrade.no.of.colonies.in.parallel.for.tablealters
  This property determines the number of colonies that are processed in parallel by the threads running alter scripts. This property is used only for sharded mode. By default, this value is set to 1. For example, if this value is set to 2 and yfs.upgrade.no.of.threads.for.tablealters is set to 6, 6 threads will run for colony1, and 6 threads will run for colony2.

Migrating history data

Procedure

If you set the yfs.apply.sql.manually property to Y in the <INSTALL_DIR>/Migration/9.5/buildmigration.properties file, you must manually apply the following DDLs, before running the alter-history-tables target:
- <INSTALL_DIR>/Migration/<previous version directory>/database/scripts/<dbtype>/history/alters.sql
- <INSTALL_DIR>/Migration/<previous version directory>/database/scripts/<dbtype>/history/uniqueindexadds.sql
- <INSTALL_DIR>/Migration/<previous version directory>/database/scripts/<dbtype>/history/indexadds.sql
- <INSTALL_DIR>/Migration/<previous version directory>/database/scripts/<dbtype>/history/uniqueindexdrops.sql
- <INSTALL_DIR>/Migration/<previous version directory>/database/scripts/<dbtype>/history/indexdrops.sql
- <INSTALL_DIR>/Migration/<previous version directory>/database/scripts/<dbtype>/history/seq.sql
where <previous version directory> corresponds to the location of the previous version directory and <dbtype> corresponds to the database type (Db2 or Oracle). As a part of this step, indexes are created.
Run the following command:

${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> -f buildmigration.xml -logfile <logfile> -Dtarget=alter-history-tables-sr -Dnonuniqueindex=Y migrate
This command also adds all the unique indexes and nonunique indexes. If nonunique indexes are not to be installed, then the argument -Dnonuniqueindex=Y should not be passed.
This command performs applies all the database changes that includes new tables, changes tables, unique and non unique indexes. This information is used later when doing the actual upgrade so as to minimize the time. This command then uses the size information available and performs all the alterations to the history tables. After this, the history tables will have new columns and data. Values in the history tables are trimmed for those data types that have been changed in the newer version.
The *.done file created in the 9.5 status folder for the task alter-history-tables are :
- history_ant_altertables.xml.done
- history_ant_installuniqueindexes.xml.done
- history_ant_installnonuniqueindexes.xml.done
If you encounter an error when altering history tables, fix the cause of the error and perform the previous task of altering history tables once again. Before executing the task, change the value of the onerror attribute from "abort" to "continue" in the <INSTALL_DIR>/Migration/9.5/history/ant_altertables.xml file.
The onerror attribute specifies how to proceed when an error occurs during the execution of one of the statements. The valid values are:
- Continue - Indicates that on encountering an error, proceed with the task of altering other tables.
- Abort - Indicates that on encountering an error, do not proceed with the task of altering other tables.
  To install upgrade typechanges, run the following sql script:
  
  <INSTALL_DIR>/Migration/9.5/database/scripts/<DB_TYPE>/history/upgrade_typechanges.sql
  
  If you are upgrading in sharded mode, you must run the SQL script for the shard that corresponds to the respective TableType. For example, if you are installing upgrade typechanges for the transaction TableType, run the following sql script:
  
  <INSTALL_DIR>/Migration/9.5/database/scripts/<DB_TYPE>/history/TRANSACTION/upgrade_typechanges.sql
To perform the dbclassgen to Release 9.5, run the following command. However, if you have run the dbclassgen target as part of the transaction migration you can skip this step.

${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> -f buildmigration.xml -logfile <logfile> -Dtarget=dbclassgen migrate

This command regenerates the dbclasses and updates the entities JAR.The *.done file created in the 9.5 status folder for the dbclassgen task is ant_dbclassgen.xml.done.

Migrating transaction data

Procedure

Run the following alter-transaction-tables command : ${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> -f buildmigration.xml -logfile <logfile> -Dtarget=alter-transaction-tables-sr -Dnonuniqueindex=Y migrate.
This command also adds all the unique indexes and nonunique indexes. If nonunique indexes are not to be installed, then the argument -Dnonuniqueindex=Y should not be passed.
The *.done file created in the 9.5 status folder for the task alter-transaction-tables are :
- transcation_ant_altertables.xml.done
- transcation_ant_installuniqueindexes.xml.done
- transcation_ant_installnonuniqueindexes.xml.done
Run the following command to install upgrade typechanges :<INSTALL_DIR>/Migration/9.5/database/scripts/<DB_TYPE>/transaction/upgrade_typechanges.sql

Note: If you are upgrading in sharded mode, you must run the sql script for the shard that corresponds to the respective TableType. For example, if you are installing upgrade typechanges for the transaction TableType, run the following sql script:
<INSTALL_DIR>/Migration/9.5/database/scripts/<DB_TYPE>/transaction/TRANSACTION/upgrade_typechanges.sql
Run the following command to regenerate dbclasses : ${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> -f buildmigration.xml -logfile <logfile> -Dtarget=dbclassgen migrate

Run the following command to migrate the transaction data:

${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD> 
-f buildmigration.xml -logfile <logfile> 
-Dtarget=upgrade-transaction-tables migrate

From the <INSTALL_DIR>/COM/Migration/9.5/COM_Add-in directory:

${ANT_HOME}/bin/ant -f ycdmigration.xml -Druntime=<INSTALL_DIR>
-Druntime.old=<INSTALL_DIR_OLD> 
-DYANTRA_RUNTIME_NEW=<INSTALL_DIR>
-Dtarget=upgrade-transaction-tables 
migrate -logfile <logfile>

Note: As part of the transaction data migration, only the factory defaults are upgraded.

Run the following command to optionally drop the unused history columns while upgrading:


${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD>
 -f buildmigration.xml -logfile <logfile> -Dtarget=run-transaction-drop migrate

Results

Once you have completed the staged upgrade, configure the agents and properties that are required for the new version. For more details, refer Configuring agents and Configuring properties.