Creating a staging filter configuration XML file

You can create an XML file to configure the stagingprop utility to propagate only specific objects to the production database. When you are running the stagingprop utility, you can use the configuration file by specifying the file path as the value for the filterconfigfile parameter.

By using a staging filter configuration file, you can publish only the data that matches a custom staging filter condition. For example, you can publish only changes for a specific store, or publish changes for only the objects that are included within a specific Management Center folder or category. By using staging filters, you can promote data to production whenever you need to publish a specific set of data between regular large staging operations.

The staging filter configuration XML file defines the SQL for the utility to use to retrieve and propagate filtered data. You can use the filterconfigfile parameter when you run the utility to have the utility use the configuration file to filter the data that is being published. For more information about filtering data and using a staging filter configuration file when you run the stagingprop utility, see Filtering data for the stagingprop utility to propagate.

Procedure

Download the following sample configuration file into a temporary directory. You can use this file as a base to create your own custom configuration file.
- offerFilterByTradeposcn.xml
This file defines custom staging filters to filter offer-related data by a trading position container ID.
Go to the following directory, which contains the sample staging filter configuration XML file for use in propagating data by custom filters. If the Staging directory does not exist, create the directory.
- WC_installdir/components/foundation/samples/Staging
- WC_installdir\components\foundation\samples\Staging
- WCDE_installdir\components\foundation\samples\Staging
Create a directory within the Staging directory to include your configuration file.
For example, if you are creating a file to publish attribute data filter by store ID, you can name the directory, Attribtute-ext.
Copy the downloaded sample configuration file into the new directory and rename the file.
For example, if you are creating a file to publish attribute data filter by store ID, you can name the file attributeFilterByStore.xml.
Edit your new staging filter configuration file to define how the stagingprop utility is to filter and process data.
1. Open your new custom configuration file for editing.
  By default, the file includes multiple <FilterDefinition> configuration elements. Each element defines how the utility retrieves the filtered data from a database table. The utility publishes this data into the corresponding table in the production environment.
2. Update the filter definition elements so that the stagingprop utility retrieves only the data that you want to publish when the file is used. Each element includes a definition for an INSERT and UPDATE action. Each of these definitions is used to generate the SQL statements that the stagingprop utility uses to retrieve the data to be propagated. This SQL also defines how the utility propagates the data. By using this configuration file, you override the default stagingprop utility behavior during the propagation phase of the stagingprop operation. This override causes the utility to retrieve and use the SQL that you define within your configuration file.
  Important: Filter condition entries that contain more than one statement or OR condition must be surrounded by round brackets. For example, the following condition will fail:
```
SL.STGFILTER IN (
{customfilterstoreid}) OR SL.STGFILTER IS NULL
```
  Whereas the same condition, surrounded by brackets, will succeed.
```
(SL.STGFILTER IN ({customfilterstoreid}
) OR SL.STGFILTER IS NULL)
```
  You can define how to filter data by identifying the ID to use explicitly in the file or by including substitution parameters, {customfilterparametername}, in the definitions. When you run the stagingprop utility and identify that the utility is to use this configuration file, the {customfilterparametername} substitution parameters in the file are replaced with the value for the matching customfilter% parameter that you include in the utility command. The value for the parametername and % must match so that the value for the customfilter% parameter can be passed from the command line into the SQL that is defined in the configuration file. By using substitution parameters, you can create a configuration file that you can reuse to propagate the same types of objects by a different ID without needing to update the configuration file.
  For example, if you are filtering data by store ID, you can include the substitution parameter customfilterstoreid, in your filter definitions, where storeid replaces parametername. When you call the stagingprop utility, you can include the customfilterstoreid 10001 parameter and value. The ID value of 10001 is then included in the SQL statements instead of the customfilterstoreid substitution parameter.
3. Remove any extra configuration elements that you do not need in your file.
Save and close your file.

What to do next

You can now use your configuration file with the stagingprop utility.

For an example that uses the provided sample staging filter configuration XML file with the stagingprop utility, see Example: Propagating filtered promotion data to the production database.