Sample: Extracting marketing data

This sample demonstrates how to extract marketing data from the HCL Commerce database, such as activities, e-Marketing Spots, customer segments, content, and associated attachments. This sample uses the Data Extract utility to extract the marketing data for a specific store. You can then use the Data Load utility to load the extracted data into another HCL Commerce instance or store to quickly copy marketing data between instances or stores.

Before you begin

Ensure that you complete the following tasks:
  • Verify that the store that you are extracting data from includes marketing data. If there is no data for a specific type of marketing object, the generated output file for the object type does not include any data.

About this sample

When you run this sample, the Data Extract utility is configured to extract the marketing data for only the store that you specify. You can specify the store in the environment configuration file.

The sample configuration files that are used to configure the Data Extract utility are in the following directory and subdirectories:
  • Linuxutilities_root/samples/DataExtract/Marketing
  • HCL Commerce DeveloperWCDE_installdir\samples\DataExtract\Marketing

When you run this sample, the files extract the data for all marketing object types. The data for each object type is included in separate output files. By default, this sample extracts data into CSV formatted files. If you want to export data into XML formatted files, you can edit the sample business configuration files to use a data writer that generates XML output files.

Sample configuration files

The following configuration files are used to configure the Data Extract utility to extract data into CSV output files.
wc-dataextract-env.xml
The environment configuration file. This file includes the environment variables for your HCL Commerce instance. These variables include the following information:
  • Business context variables, including the store identifier, catalog identifier, and the default language and currency for your store.
  • Database environment settings, including the database type, name, and schema.
wc-dataextract.xml
The data extract order configuration file. This file specifies the paths to the environment configuration file and to the business object configuration files for extracting the data for each type of object. The order configuration file also identifies the order that the Data Extract utility extracts data and identifies the output files that the utility generates to include the extracted data.
wc-extract-business-object.xml
The business object configuration file. This file defines how the utility identifies the data to extract and defines the business object mediator for the utility to use to transform the extracted data. In this sample, a separate configuration file is provided for each type of marketing object. All of the sample business object configuration files configure the utility to use the following business object mediator:

com.ibm.commerce.foundation.dataload.businessobjectmediator.AssociationObjectMediator

  • Customer segments
    wc-extract-customer-segment.xml
    Configures the utility to extract the customer segments with descriptive information for only a specific store language. You can specify this language in the environment configuration file business context. This file configures the utility to extract data from the member group database tables (MBRGRP and MBRGRPDESC) since customer segments are a type of member group. The utility extracts data for only the member groups that have a usage value of -1, which indicates that the group is a customer segment. The data is included in the MemberGroup.csv output file.
    wc-extract-customer-segment-description.xml
    Configures the utility to extract customer segment descriptive information for all supported languages. The data is included in the MemberGroupDescription.csv output file.
    wc-extract-customer-segment-condition.xml
    Configures the utility to extract customer segment conditions. The data is included in the MemberGroupCondition.csv output file.
    Note: Any new line characters within the condition XML string for an object in the database are converted to a space character in the output CSV file.
  • Attachments
    wc-extract-attachment.xml
    Configures the utility to extract attachments with descriptive information for only a specific store language. You can specify this language in the environment configuration file business context. The data is included in the Attachment.csv output file.
    wc-extract-attachment-description.xml
    Configures the utility to extract attachment descriptive information for all supported languages. The data is included in the AttachmentDescription.csv output file.
    wc-extract-attachment-asset.xml
    Configures the utility to extract attachment assets. The data is included in the AttachmentAsset.csv output file.
    wc-extract-attachment-asset-language.xml
    Configures the utility to extract the attachment asset and language relationships. The data is included in the AttachmentAssetLanguage.csv output file.
  • Marketing content
    wc-extract-marketing-content.xml
    Configures the utility to extract marketing content with descriptive information for only a specific store language. You can specify this language in the environment configuration file business context. The data is included in the MarketingContent.csv output file.
    wc-extract-marketing-content-description.xml
    Configures the utility to extract the marketing content descriptive information for all supported languages. The data is included in the MarketingContentDescription.csv output file.
    wc-extract-marketing-content-attachment.xml
    Configures the utility to extract the marketing content and attachment relationship with descriptive information for only a specific store language. You can specify this language in the environment configuration file business context. The data is included in the MarketingContentAttachment.csv output file.
    wc-extract-marketing-content-attachment-description.xml
    Configures the utility to extract the marketing content and attachment relationship descriptive information for all supported languages. The data is included in the MarketingContentAttachmentDescription.csv output file.
    wc-extract-marketing-content-imagemap.xml
    Configures the utility to extract marketing content image maps. The data is included in the MarketingContentImageMap.csv output file.
  • e-Marketing Spots
    wc-extract-marketing-spot.xml
    Configures the utility to extract e-Marketing Spots. The data is included in the MarketingSpot.csv output file.
    wc-extract-marketing-spot-default-content.xml
    Configures the utility to extract the default content information for e-Marketing Spots. The data is included in the MarketingSpotDefaultContent.csv output file.
    wc-extract-marketing-spot-default-title.xml
    Configures the utility to extract the default title information for e-Marketing Spots. The data is included in the MarketingSpotDefaultTitle.csv output file.
  • Activities
    wc-extract-marketing-activity.xml
    Configures the utility to extract to extract marketing web, dialog, and email activities, and search rules. The data is included in the MarketingActivity.csv output file.
    wc-extract-marketing-campaign.xml
    Configures the utility to extract marketing campaigns. The data is included in the MarketingCampaign.csv output file.
    wc-extract-marketing-element.xml
    Extracts the marketing elements for marketing activities. The data is included in the MarketingElement.csv output file.
    wc-extract-marketing-elementnvp.xml
    Extracts the marketing element name-value pairs for marketing activities. The data is included in the MarketingElementNVP.csv output file.

Procedure

  1. Copy the sample configuration files and directories to a local directory.
  2. Edit your copy of the sample environment configuration files to set the configuration variables for your environment. All of the sample configuration files that are used in this sample include values for a default HCL Commerce Developer environment that uses an Apache Derby database. If your environment settings are different, you must change the configured values in these files to match your environment. For more information about updating an environment configuration file, see Configuring and running the Data Extract utility.
  3. HCL Commerce DeveloperOn a command line, go to the WCDE_installdir\bin directory.
  4. LinuxOpen a command line in the . Change the directory to utilities_root/bin directory. For information about entering and leaving containers, see Running utilities from the Utility server Docker container.
  5. Enter the following command to run the sample data extract order configuration for extracting the marketing data:
    • Linux./dataextract.sh ../samples/DataExtract/Marketing/wc-dataextract.xml
    • HCL Commerce Developerdataextract ..\samples\DataExtract\Marketing\wc-dataextract.xml
When the utility completes the extraction process, the utility generates the output files within the configured output directory and subdirectories. These files include data for all marketing objects that exist for the configured store. By default, the files are generated in the following output directory and subdirectories:
  • Linuxutilities_root/samples/DataExtract/Marketing/output
  • HCL Commerce DeveloperWCDE_installdir\samples\DataExtract\Marketing\output

Verifying results

  1. Go to the directory that you configured as the output directory. If you did not configure an output directory, go to the following directory:
    • Linuxutilities_root/samples/DataExtract/Marketing/output
    • HCL Commerce DeveloperWCDE_installdir\samples\DataExtract\Marketing\output
  2. Verify that the following CSV output files are generated:
    • CustomerSegment/MemberGroup.csv
    • CustomerSegment/MemberGroupDescription.csv
    • CustomerSegment/MemberGroupCondition.csv
    • Attachment/Attachment.csv
    • Attachment/AttachmentDescription.csv
    • Attachment/AttachmentAsset.csv
    • Attachment/AttachmentAssetLanguage.csv
    • MarketingContent/MarketingContent.csv
    • MarketingContent/MarketingContentDescription.csv
    • MarketingContent/MarketingContentAttachment.csv
    • MarketingContent/MarketingContentAttachmentDescription.csv
    • MarketingContent/MarketingContentImageMap.csv
    • MarketingSpot/MarketingSpot.csv
    • MarketingSpot/MarketingSpotDefaultContent.csv
    • MarketingSpot/MarketingSpotDefaultTitle.csv
    • MarketingActivity/MarketingCampaign.csv
    • MarketingActivity/MarketingActivity.csv
    • MarketingActivity/MarketingElement.csv
    • MarketingActivity/MarketingElementNVP.csv
  3. Open the output files to review the file contents.
  4. Verify that the file contents match the data in the database for the marketing objects that belong to the specified store. For more information about the data that can be in these files, see Marketing object input file definitions.

What to do next

You can load your extracted data into another HCL Commerce instance with the Data Load utility. For a sample that demonstrates how to load marketing data, see Sample: Loading marketing data. When you follow this sample, edit the load order configuration file to specify the output files that were generated by the Data Extract utility.