Create a staging filter configuration XML file

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

By using a staging filter configuration file, we can publish only the data that matches a custom staging filter condition. For example, we can publish only changes for a specific store, or publish changes for only the objects included within a specific Management Center folder 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.

The staging filter configuration XML file defines the SQL for the utility to use to retrieve and propagate filtered data. We 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

  1. Download the following sample configuration file into a temporary directory. We can use this file as a base to create our own custom configuration file.

    This file defines custom staging filters to filter offer-related data by a trading position container ID.

  2. Open the Utility server Docker container.

  3. 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.

  4. Create a directory within the Staging directory to include your configuration file. For example, if we are creating a file to publish attribute data filter by store ID, we can name the directory, Attribtute-ext.

  5. Copy the downloaded sample configuration file into the new directory and rename the file. For example, if we are creating a file to publish attribute data filter by store ID, we can name the file attributeFilterByStore.xml.

  6. 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 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 we define within your configuration file.

      We 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, we can create a configuration file that we can reuse to propagate the same types of objects by a different ID without needing to update the configuration file.

      For example, if we are filtering data by store ID, we can include the substitution parameter customfilterstoreid, in your filter definitions, where storeid replaces parametername. When you call the stagingprop utility, we 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.

  7. Save and close your file.


What to do next

We 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.


Related tasks
Creating a database table filter list
Filtering data for the stagingprop utility to propagate


Related reference
stagingprop utility
Example: Propagating filtered promotion data to the production database