Example: Propagating filtered promotion data to the production database

Use the following example code to help you understand how to use a staging filter configuration file and command-line parameters to configure the stagingprop utility. By using a staging filter configuration file, we can publish only the data that matches a custom staging filter condition. In this example, the stagingprop utility is configured to publish only promotion data included within a specific promotion folder.

Use this example to help you create staging filters that can filter the data to be published by any parameter, such as store ID or category. By using staging filters, we can promote data to production whenever you need to publish a specific set of data between regular large staging operations.

When you filter the objects to propagate, you reduce the impact to site performance from the stagingprop process by reducing the amount of data that is being propagated. To filter the data to be propagated, we can configure the utility with a staging filter configuration file that defines how the utility processes data. When you run the stagingprop utility, we can then use command-line parameters to specify the configuration XML file and the object that is to be filtered. See Filtering data for the stagingprop utility to propagate.

Before beginning

Ensure that you complete the following tasks:

• In the authoring or staging environment, use Management Center to create or change promotions and add the promotions into a promotion folder. When we save the changes for the promotions, you create a record for the promotions within the STAGLOG database table. This record identifies that the records are changed and ready to be propagated to the production environment.

• In Management Center, view the list of all promotion folders in the store. Configure the columns that display in the list to display the folder Unique ID value. Record the ID for the promotion folder that includes the promotions to propagate to the production environment. This example uses an ID of 10001.

• In the production environment, ensure that any catalog or marketing assets associated with the promotions to publish are available.

• In the staging environment, update the database triggers for the database. Manually run the promotionFilterByFolderTriggers.sql script file to generate the triggers on the relevant table. We need to complete this task only once for a table. These triggers replace the existing database triggers on the staging environment for the certain promotion tables.

About this example

This example demonstrates how to use a staging filter to propagate only the new and changed promotions included within a specific promotion folder. This example uses a sample staging filter configuration file to define the SQL that the stagingprop utility uses to select the data to be propagated. This SQL also defines how the utility propagates the data. This configuration file overrides the default stagingprop utility behavior during the propagation phase of the staging operation. This override causes the utility to retrieve and use the SQL that is defined within the configuration file. The utility uses the SQL to propagate the filtered data. In this example, the promotions within a specified folder. This sample configuration file, promotionFilterByFolder.xml, is in the following directory

• utilities_root\components\foundation\samples\Staging\Promotion

Note: Only the promotions that are within the specified folder when you run the stagingprop utility are propagated to production. When the stagingprop utility runs with the sample promotionFilterByFolder.xml file, the utility only creates or changes the promotions in the production environment. No promotions are deleted. To remove an active promotion in production, use the Promotions tool to deactivate the promotion.

To specify that the stagingprop utility is to use a staging filter configuration file, we must include the parameter -filterconfigfile in the command line when you run the utility. The value for the parameter must be the file path and name for the configuration file.

To identify the specific set of data to be filtered, we can either identify the data set within the configuration file, or include a substitution parameter, {customfilterparametername}, in the configuration file. If you use the substitution parameter, we can then include the -customfilter% parameter in the command line when you run the stagingprop utility. The value of the two parameters must match so that the value for the parameter can be passed from the command line into the SQL that is defined in the configuration file. In this example, the custom filter parameters {customfilterfolderid} and -customfilterfolderid are used. We must specify the folder ID of the folder that includes the promotions to propagate as the value for the -customfilterfolderid parameter in the command line. After running the stagingprop utility to propagate filtered data, we must update the database triggers for the staging tables. Since only certain records are propagated, we must override the default database triggers to indicate that only the records for the filtered data are propagated. The SQL file, promotionFilterByFolderTriggers.sql, includes the SQL database triggers that you run in this example. is in the following directory:

• utilities_root\components\foundation\samples\Staging\Promotion\dbtype

Where dbtype is the database for the environment. SQL triggers are available for both the DB2 and Oracle databases.

Procedure

1. Open the Utility server Docker container.

2. Enter the following command to run the stagingprop utility with the appropriate staging filter parameters and values:

   • (DB2) ./stagingprop.sh -scope _all_ -sourcedb staging_database_name -sourcedb_user user -sourcedb_passwd password -destdb production_database_name -destdb_user user -destdb_passwd password -dbtype db2 -log log_file_name -customfilterfolderid 10001 -filterconfigfile ../components/foundation/samples/Staging/Promotion/promotionFilterByFolder.xml

   • (Oracle) ./stagingprop.sh -scope _all_ -sourcedb staging_database_name -sourcedb_user user -sourcedb_passwd password -destdb production_database_name -destdb_user user -destdb_passwd password -dbtype oracle -log log_file_name -customfilterfolderid 10001 -filterconfigfile ../components/foundation/samples/Staging/Promotion/promotionFilterByFolder.xml

3. Review the log file for the stagingprop utility to ensure that the staging process successfully completed. The log file is in the following directory:

   • (Linux) utilities_root/logs

4. In our production or target environment, verify that the new and changed promotions are available in Management Center.

Related tasks
Filtering data for the stagingprop utility to propagate
Creating a staging filter configuration XML file

Related reference
stagingprop utility