Migrating promotions built on custom promotion types

For this type of migration, you create a custom XSL template for each custom promotion type and a custom version of the Control Info configuration file. Then you run the promotion migration utility using a parameter that calls the custom Control Info configuration file. You can choose either a partial or complete migration for each promotion type.

Before you begin

Read the following topics:

Procedure

Define a custom XSL template for each customized promotion type:
- For promotion types for which you want to perform a complete migration:
  1. Create a custom XSL template based on the sample provided in the topic Sample OrderLevelPercentOff XSL template.
  2. Save the custom XSL template at the following path:
    WC_installdir/migration/optional/components/component-services/subcomponents/promotion/templates/
- For promotion types for which you want to perform a partial migration:
  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
  4. Save and close the XSL template.
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.
4. Add a new <PromotionSelect> entry for each custom promotion type that you want to migrate; then type a <MigrationType> value of either Complete or Partial.
  The following example entry indicates that the MyCustomPromotionType promotion type requires a complete migration:
```
<PromotionSelect>
   <PromotionType>MyCustomPromotionType</PromotionType>
   <MigrationType>Complete</MigrationType>
</PromotionSelect>
```
5. Add a new <TemplateMapping> entry for each custom promotion type that you want to migrate, to map the custom promotion type to its custom XSL transformation template.
  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.
6. Optionally, you can specify the delimiter for promotion codes using the <PromotionCodeDelimiter> element. The default value is ‘|'.
7. 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.
The following example shows what a complete custom Control Info configuration file contains for two custom promotion types (MyCustomPromotionType1 and MyCustomPromotionType2) that are each mapped to a custom XSL template (MyCustomPromotionTypeMigrationTemplate1.xsl and MyCustomPromotionTypeMigrationTemplate2.xsl), and both promotion types require complete migrations:
```
<?xml version="1.0" encoding="UTF-8"?>
<PromotionMigration>
<PromotionMigrationOption>
      <PromotionCodeDelimiter>|</PromotionCodeDelimiter>
      <PromotionExclusivityCannotCombineWithProductPromotionsMigrationType>
      Partial
      </PromotionExclusivityCannotCombineWithProductPromotionsMigrationType>
      <PromotionSelect>
           <PromotionType>MyCustomPromotionType1</PromotionType>
           <MigrationType>Complete</MigrationType>
      </PromotionSelect>
      <PromotionSelect>
           <PromotionType>MyCustomPromotionType2</PromotionType>
           <MigrationType>Complete</MigrationType>
      </PromotionSelect>
</PromotionMigrationOption>
<PromotionMigrationTemplates>
      <TemplateMapping>
           <PromotionType>MyCustomPromotionType1</PromotionType>
           <Template>MyCustomPromotionTypeMigrationTemplate1.xsl</Template>
      </TemplateMapping>
      <TemplateMapping>
           <PromotionType>MyCustomPromotionType2</PromotionType>
           <Template>MyCustomPromotionTypeMigrationTemplate2.xsl</Template>
      </TemplateMapping>
</PromotionMigrationTemplates>
</PromotionMigration>
```
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.
For any promotion types on which you performed a complete migration: perform any required customization to the Management Center Promotions tool to support your custom promotion type.
See Promotions customization: Management Center.