Sample: Extracting marketing data

This sample demonstrates how to extract marketing data from the WebSphere 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. We can then use the Data Load utility to load the extracted data into another WebSphere Commerce instance or store to quickly copy marketing data between instances or stores.

Before beginning

Ensure that you complete the following tasks:

• Verify that the store that we 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. We can specify the store in the environment configuration file. The sample configuration files used to configure the Data Extract utility are in the following directory and subdirectories:

• (Linux) utilities_root/samples/DataExtract/Marketing

• (Developer) WCDE_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. To export data into XML formatted files, we 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 the WebSphere Commerce instance. These variables include the following information:

• Business context variables, including the store identifier, catalog identifier, and the default language and currency for the 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. We 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. We 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. We 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. We 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 the environment. All of the sample configuration files used in this sample include values for a default WebSphere Commerce Developer environment that uses an Apache Derby database. If the environment settings are different, change the configured values in these files to match the environment. For more information about updating an environment configuration file, see
   Configure and running the Data Extract utility.

3. (Developer) On a command line, go to the WCDE_installdir\bin directory.

4. (Linux) Open a command line in the Utility server Docker container. 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

   • (Developer) dataextract ..\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:

• (Linux) utilities_root/samples/DataExtract/Marketing/output

• (Developer) WCDE_installdir\samples\DataExtract\Marketing\output

Verifying results

1. Go to the directory that you configured as the output directory. If we did not configure an output directory, go to the following directory:

   • (Linux) utilities_root/samples/DataExtract/Marketing/output

   • (Developer) WCDE_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

We can load your extracted data into another WebSphere 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.

Related concepts
Overview of the Data Extract utility