Migrating promotions: partial migration

For this type of migration, you create a custom version of the Control Info configuration file to specify a partial migration for each promotion type. If you have promotions built on custom promotion types, you create a custom XSL template to transform the promotion to the new data model. Then you run the promotion migration utility using a parameter that calls the custom Control Info configuration file.

Before you begin

Read the following topics:

About this task

Use this procedure for migration if:

You use an external tool to create and edit promotions (a non-WebSphere Commerce tool) and you want to continue using that tool to create and edit promotions after you migrate; however, you want to use the Management Center to activate, deactivate, and delete promotions.
The promotions you want to migrate are based on either default or custom promotion types.

Procedure

If you have any promotions based on custom promotion types, create a custom XSL template for each custom promotion type:
1. Create an empty file for your XSL template with a suitable name, and then save it in the following path:
  WC_installdir/migration/optional/components/component-services/subcomponents/promotion/templates/
2. Copy the code from Partial migration XSL template and paste it into the file.
3. Modify the file if you have customized the runtime promotion XML for the following nodes:
  - Schedule
  - TypedNLDescription
  - PromotionCodeCue
  If you have not customized these nodes, you can use the XSL template as is.
4. Save and close the XSL template.
5. Repeat these steps for any additional promotions based on custom promotion types.
Create a custom version of the Control Info configuration file (promotionMigrationControlInfo.xml) using the same format as the default:
1. Navigate to the WC_installdir/migration/optional/components/component-services/subcomponents/promotion/config/ directory.
2. Copy the promotionMigrationControlInfo.xml file and rename the copy; this creates the custom Control Info configuration file.
  Do not change the default promotionMigrationControlInfo.xml file.
3. Open the custom Control Info configuration file.
For promotions based on default promotion types:
1. Locate the <PromotionSelect> entry for each promotion type; then change the <MigrationType> value from Complete to Partial.
  The following example is a <PromotionSelect> entry that specifies a partial migration for the promotion type OrderLevelFreeGift:
```
<PromotionSelect>
   <PromotionType>OrderLevelFreeGift</PromotionType>
   <MigrationType>Partial</MigrationType>
</PromotionSelect>
```
For promotions based on custom promotion types:
1. Create a <PromotionSelect> entry for each promotion type, and specify a Partial migration type.
  The following example is a <PromotionSelect> entry that specifies a partial migration for the promotion type MyCustomPromotionType:
```
<PromotionSelect>
   <PromotionType>MyCustomPromotionType</PromotionType>
   <MigrationType>Partial</MigrationType>
</PromotionSelect>
```
2. Create a new <TemplateMapping> entry for each custom promotion type that you want to migrate, to map the custom promotion type to the custom XSL template you created at the beginning of this procedure.
  The following example entry maps the MyCustomPromotionType promotion type to the MyCustomPromotionTypeMigrationTemplate.xsl template:
```
<TemplateMapping>
   <PromotionType>MyCustomPromotionType</PromotionType>
   <Template>MyCustomPromotionTypeMigrationTemplate.xsl</Template>
</TemplateMapping>
```
  Note: The promotion migration utility gives preference to custom templates over default templates when it runs. If a promotion type is mapped to a default template in the promotionMigrationConfig.xml file and an entry for the same promotion type also exists in the custom Control Info configuration file, the latter entry will be given preference and the default template defined in the promotionMigrationConfig.xml file will be ignored.
3. Optionally, you can specify the delimiter for promotion codes using the <PromotionCodeDelimiter> element. The default value is '|'.
Optionally, you can specify the migration type for order-level promotions built in WebSphere Commerce Accelerator that have the option "Cannot be combined with product promotions" selected. To do this, change the <PromotionExclusivityCannotCombineWithProductPromotionsMigrationType> element value to Complete. The default value is Partial.
Save and close the custom Control Info configuration file.
Stop the WebSphere Commerce Server.
Ensure that you run the promotion migration utility as the wasuser user. To do so, issue the following command:
su - wasuser_ID

where wasuser_ID is the non-root user ID created before installing WebSphere Commerce. The default WebSphere Application Server user name is wasuser.
Open a command prompt window.
Run the promotion migration utility with arguments specifying the location of any custom files, as well as the build file and the information needed to connect to a database in the server environment.
1. Call the migration script with the following command:
  - WCDE_installdir/bin/migratePromotions.bat –customControlInfoFile customFile.xml -verbose
  –customControlInfoFile
  (Optional) Indicates that you want the command to use the custom Control Info configuration file. If you created a custom Control Info configuration file earlier in this procedure, replace customFile.xml with the fully qualified path and filename of the custom Control Info configuration file. If you did not create a custom Control Info configuration file, do not specify this parameter; as a result, the migration utility uses the default Control Info configuration file (promotionMigrationControlInfo.xml).
  
  -verbose
  (Optional) Indicates that you require additional logging for use when you need to debug the command.
  Note that all logging is sent to the WCDE_installdir/logs/migratePromotions.log file.
2. Call the migration script with the following command:
  - WC_installdir/bin/config_ant.bat -buildfile WC_installdir/migration/optional/components/component-services/subcomponents/promotion/config/PromotionsMigration.xml -DinstanceName=instance_name -DdbUserPassword=database_password -DcurrentPropFile=instance.properties -DcustomControlInfoFile=customFile.xml -logfile migratePromotions.txt -verbose
  - WC_installdir/bin/config_ant.sh -buildfile WC_installdir/migration/optional/components/component-services/subcomponents/promotion/config/PromotionsMigration.xml -DinstanceName=instance_name -DdbUserPassword=database_password -DcurrentPropFile=instance.properties -DcustomControlInfoFile=customFile.xml -logfile migratePromotions.txt -verbose
  -buildfile
  (Required) Specifies the build file to use for the migration. This parameter must be followed by the path to the migration build file as shown.
  -DinstanceName
  (Required) Specifies the instance you want to migrate. When using this parameter, replace instance_name with the name of the WebSphere Commerce instance for which you are migrating the promotions.
  -DdbUserPassword
  (Required) Provides the password to use to connect to the database. When using this parameter, replace database_password with the WebSphere Commerce database user's password.
  
  -DcurrentPropFile
  (Optional) Specifies the full path and name of the database properties file. The database properties file is used when a database, other than the one specified in the instance.xml file, is to be updated. This file takes the same format as the createInstance.properties file found under the WC_installdir/instances/instance_name/properties directory. The database section in the properties file is used to acquire the parameters required for the migration utility.
  
  –DcustomControlInfoFile
  (Optional) Indicates that you want the command to use the custom Control Info configuration file. If you created a custom Control Info configuration file earlier in this procedure, replace customFile.xml with the fully qualified path and filename of the custom Control Info configuration file. If you did not create a custom Control Info configuration file, do not specify this parameter; as a result, the migration utility uses the default Control Info configuration file (promotionMigrationControlInfo.xml).
  
  -logfile
  (Optional) Specifies the location of a log file. When using this parameter, replace migratePromotions.txt with the the fully qualified path and filename of a file to contain logging information, for example, C:\logs\migratePromotions.txt. If you do not specify this parameter, then logging information is displayed in the console.
  -verbose
  (Optional) Indicates that you require additional logging for use when you need to debug the command.
This migration script calls an ANT task that loads the configuration files and the XSL template files, applies the transformations, and then saves the data to the database tables. Error conditions will be written to standard output.
(Optional) If you have a business need to view the migrated promotion in the WebSphere Commerce Accelerator, read the following document: Making migrated promotions visible in WebSphere Commerce Accelerator.