Loading customer segment members by email address with the Data Load utility

You can create a customer segment that business users can manage in the Marketing tool by loading a list of email addresses.

Note: To help create customer segments more quickly, you can copy campaigns and other marketing objects from one store or instance into another. For example, to help set up a test environment or a new store. For more information, see

About this task

The MemberGroupMemberMediator business object mediator is enhanced so that you can load a CSV input file that includes only a list of email addresses. Load the input file to create a customer segment or add members to an existing customer segment. For example, if customer segments need to be merged, you can combine the email addresses for the customers in those segments and then load the email addresses.

The Data Load utility resolves the member unique ID for existing members in the database by comparing the email address in the input file with the email addresses for the existing members. The utility then adds the members to the existing customer segment or creates a new segment to include the members.

Note: The Data Load utility resolves member IDs by comparing the email address in the input file with the email addresses of registered customers in the store.

As a best practice, load the customer segment member data in your production environment to ensure that the member data in the database is up-to-date. By loading the data in the production environment, you can also ensure that the members have a registered customer role in the store organization. If you want to copy a customer segment from your production environment to your staging environment, use the customer segment copy utility. For more information, see Copying customer segments from the production environment to the staging environment.

HCL Commerce Enterprise If you want to load members into a customer segment or create a customer segment in an extended site store, ensure that the members have a registered customer role in the store organization. If you want to load the customer segment members into an asset store, ensure that the user has a customer role in one of the extended site store organizations. When the Data Load utility checks the registered customer role for a store organization, the utility checks all of the parent stores in the organization hierarchy.

Procedure

Create the input file for loading your customer segment data.
1. Go to the following directory, which contains a sample input file for loading member group member data:
  - On a command line, go to the WCDE_installdir\samples\DataLoad\Member\CustomerSegment directory.
  - Open a command line in the Utility Docker container. Change to the utilities_root/samples/DataLoad/Member/CustomerSegment directory.
  For information about entering and leaving containers, see Running utilities from the Utility server Docker container.
2. Create a backup of TestCustomerSegment.csv input file.
3. Rename the sample file so that the file name is the name for the customer segment. The Data Load utility compares the file name of the input file with the names of the customer segments in the database. If the name does not exist in the database, the Data Load utility creates the customer segment. The file name of the input file, excluding the file extension, is used as the name of the customer segment.
4. Open the input file for editing.
5. Replace the list of sample email addresses with the email addresses that you want to add to the customer segment. Include one email address per line. Do not add any column headings, or other columns into the file.
6. Save and close your input file.
Create the Data Load utility configuration files that you need to load your member group member data.
1. Go to the following directory, which contains the sample configuration files for loading member group member data:
  - utilities_root/samples/DataLoad/Member
  - WCDE_installdir\samples\DataLoad\Member
2. Create a backup of the wc-dataload-env.xml environment configuration file.
3. In the CustomerSegment directory, create a backup of the following configuration files:
  
  wc-loader-customer-segment-email.xml
  
  The business object configuration file.
  
  wc-dataload.xml
  
  The data load order configuration file.
Optional: Open the business object configuration file (wc-loader-customer-segment-email.xml) for editing and configure the settings for loading your customer segment data.
1. In the <_config:DataReader> element, ensure that the following column configuration is included. This configuration indicates that the email addresses in the CSV input file are the values for the column "email".
```
<_config:DataReader 
 className="com.ibm.commerce.foundation.dataload.datareader.CSVReader" 
 firstLineIsHeader="false" useHeaderAsColumnName="false" >
  ...
  <_config:Data>
    <_config:column number="1" name="email" />
  </_config:Data>
</_config:DataReader>
```
2. In the <_config:BusinessObjectBuilder> element, ensure that the value of the packageName attribute is com.ibm.commerce.member.facade.datatypes.MemberPackage and that the value of the dataObjectType attribute is MemberGroupType.
3. In the <_config:BusinessObjectMediator> element, ensure that the value of the className attribute is com.ibm.commerce.member.dataload.mediator.MemberGroupMemberMediator and that the value of the componentId attribute is com.ibm.commerce.member.
4. In the configuration for mapping the unique ID of users to include in the customer segment, configure the MemberGroupMemberValueHandler value handler. Ensure that the value handler is configured to support the use of email addresses to resolve the unique ID
  Your MemberGroupMemberValueHandler value handler configuration must include the following configurable parameter to enable this support:
```
<_config:Parameter name="email" value="email" />
```
  This email parameter indicates that the Data Load utility is to retrieve and use the input file email addresses to resolve the unique ID values for users. The value for this configurable parameter, email, must match the column name that you configured in the data reader configuration. With this configuration, the Data Load utility passes the email addresses in to the SQL to resolve the unique ID. The parameter is supported for use with only the MemberGroupMemberValueHandler value handler.
  You can also include or configure the following optional configurable parameter, which controls how the Data Load utility uses the email addresses to resolve the unique ID.
  
  emailCaseSensitive
  
  Optional. Indicates whether the email address is case-sensitive. The parameter is supported for use with only the MemberGroupMemberValueHandler value handler. You can set the following values for this property:
  
  true
  
  The Data Load utility does not convert the email address to lowercase characters. By setting this value for the parameter, the SQL to resolve the unique ID can complete quicker, but fail to resolve some ID values correctly for existing member group members. If you know that the email addresses in your input file that also exist in the database are the same case, set this value to improve performance.
  
  false
  
  The Data Load utility uses the English, en_US, locale to convert the email address to lowercase characters. After the utility converts the email address, the utility passes the email address into the SQL for use in resolving the unique ID. The default value.
  The Data Load utility might not successfully compare email addresses between the input file and the database when the email addresses include non-ASCII characters that have different letter cases.
  
  checkEmailFlag
  
  Optional. Indicates whether the Data Load utility compares the email addresses in your input file against only the primary email address for member group members. The parameter is supported for use with only the MemberGroupMemberValueHandler value handler. You can set the following values for this property:
  
  0
  
  The Data Load utility compares the input file email addresses to only the primary email address of a user to resolve the unique ID. The default value.
  
  -1
  
  The utility compares the email address in the input file with all of the email addresses in the address book for a member group member. If a member has one email address that matches the address in the input file, the ID for the member returns so that the member data can be updated or removed.
  
  By default, the sample configuration file includes these optional parameters with the email parameter to control how the utility uses email addresses to resolve the unique ID.
```
<_config:mapping xpath="IncludedPerson[0]/UniqueID" value="uniqueId" >
  <_config:ValueHandler className="com.ibm.commerce.member.dataload.config.MemberGroupMemberValueHandler">
    <_config:Parameter name="email" value="email" />
    ...	
    <_config:Parameter name="checkEmailFlag" value="0" valueFrom="Fixed" />
    <_config:Parameter name="emailCaseSensitive" value="true" valueFrom="Fixed" />
  </_config:ValueHandler>
</_config:mapping>
```
5. In the data mapping configuration for the file, ensure that you include the configuration mapping for the member group usage.
  By default the sample configuration file configures the member group usage to be "GeneralPurpose", which indicates that the group is a customer segment.
```
<_config:mapping xpath="Usage[0]" value="GeneralPurpose" valueFrom="Fixed"/>
```
6. Add any configurable properties that you want to use to control how the Data Load utility loads your customer segment data.
  For example, you can include one or more of the following properties, which are intended for loading customer segment members.
  
  replaceAllExistingMembers
  
  Indicates whether the Data Load utility replaces the existing users in the customer segment with the users in the input file. This property is supported only for use with the MemberGroupMemberMediator business object mediator. You can set the following values for this property:
  
  true
  
  The Data Load utility deletes all existing users from the customer segment before the utility loads new users.
  
  false
  
  The Data Load utility does not replace existing users. The default value.
  
  ignoreNonExistUsers
  
  Indicates how the Data Load utility is to handle loading email addresses when a user ID cannot be resolved or created for the address. This property is supported only for use with the MemberGroupMemberMediator business object mediator. You can set the following values for this property:
  
  true
  
  When the email address cannot be resolved to a user ID, the Data Load utility ignores the error and does not load the email address. The utility then continues with the load operation. When the load completes, the utility includes the list of email addresses that could not be resolved.
  Note: If you turn on the -Dcom.ibm.commerce.member.dataload.level=FINE trace, all unresolved email addresses are logged within the wc-dataload.log file.
  
  false
  
  When the email address cannot be resolved to a user ID, the Data Load utility throws an exception. The default value.
  
  customerSegmentNameIsFileName
  
  Indicates whether the file name of the input file, excluding the file extension, is also the name of an existing customer segment. This property is supported only for use with the MemberGroupMemberMediator business object mediator. You can set the following values for this property:
  
  true
  
  The Data Load utility uses the file name as the name for the customer segment. If the customer segment name exists in the database, the utility can add or replace members for the customer segment. If the customer segment does not exist, the utility creates the customer segment member group. The created segment includes the file name as the segment name and description. If you are loading a file that includes only customer email addresses, you must set the value to be true.
  
  false
  
  The file name must be an existing customer segment name. If the customer segment does not exist, the utility does not create the customer segment member group.
  If you set the value to be false and the customer segment doesn't exist, the Data Load utility throws an error during the load process that the customer segment member group is not specified. The default value.
  
  For example, the following code snippet configures the enabling of the preceding properties:
```
<_config:BusinessObjectMediator 
 className="com.ibm.commerce.member.dataload.mediator.MemberGroupMemberMediator" 
 componentId="com.ibm.commerce.member" >
  <_config:property name="replaceAllExistingMembers" value="true" />
  <_config:property name="ignoreNonExistUsers" value="true" />
  <_config:property name="customerSegmentNameIsFileName" value="true" />
</_config:BusinessObjectMediator>
```
7. Save and close the configuration file.
Open the data load environment configuration file (wc-dataload-env.xml) for editing and update the configured settings to match your environment settings.
Open the data load order configuration file (wc-dataload.xml) for editing and configure the settings to load your customer segment data.
1. In the <_config:DataLoadEnvironment> element, ensure that the value of the configFile attribute identifies the environment configuration file. If the file is not in the same directory as the data load order configuration file, include the relative path to the file.
2. In the <_config:LoadItem> element, ensure that the value for the name attribute is CustomerSegmentEmail and that the value for the businessObjectConfigFile attribute identifies the business object configuration file. If the file is not in the same directory as the data load order configuration file, include the relative path to the file.
3. In the <_config:DataSourceLocation> element, ensure that the value of the location attribute identifies the input XML file that you are loading. If the file is not in the same directory as the data load order configuration file, include the relative path to the file.
4. Save and close the configuration file.
Run the Data Load utility.
Verify that the customer segment data is loaded by reviewing the data load summary report.
For more information about the location and contents of this summary report, see Verifying the results of the data load.
- You can also verify that the customer segment data is loaded by comparing the contents of your input file with the customer segment data in your HCL Commerce database. Ensure that the data within your input file exists within the appropriate database tables.
- If you created a customer segment, verify that you can view the newly loaded customer segment in the Marketing tool.