Loading member group members by email address with the Data Load utility

You can load members into member groups by resolving the unique ID for a member with only the member email address. By resolving the unique ID with the email address, you do not need to include the member logon ID or distinguished name in your input file.

About this task

The MemberGroupMemberMediator business object mediator is enhanced so that you resolve the member unique ID based on the member email address. The Data Load utility resolves the 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. If an email address does not exist in the database for a member unique ID, the utility creates a new member in the database. The utility then either adds the members to the existing member group or creates a new member group to include the members.

Note: When the Data Load utility is resolving the member ID, the utility compares the input file email addresses against the addresses for only registered shoppers for the configured store ID.

As a best practice, load member data in your production environment to ensure that the member data in the database is up to date. If you do load the data in a staging environment, ensure that you propagate your changes to production.

Procedure

Create the input file for loading your member group member data.
1. Open a command-line interface in the utilities directory.
  - On a command line, go to the WCDE_installdir\samples\DataLoad\Member\MemberGroup directory.
  - Open a command line in the Utility Docker container. Change the directory to the utilities_root/samples/DataLoad/Member/MemberGroup directory. For information on entering and leaving containers, see Running utilities from the Utility server Docker container.
2. Create a backup of either the MemberGroupMember.csv or MemberGroupMember.xml input file.
3. Open the input file for editing.
4. Replace the column heading logonId with email.
  For example,
```
MemberGroupMember,,,,
memberGroupName,email,excluded,memberType,delete
```
5. Replace the sample member group and member data with the data that you want to load.
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:
  - WCDE_installdir\samples\DataLoad\Member
  - utilities_root/samples/DataLoad/Member
2. Create a backup of the wc-dataload-env.xml environment configuration file.
3. In the MemberGroup directory, create a backup of the following configuration files:
  
  wc-loader-member-group-member.xml
  
  The business object configuration file.
  
  wc-dataload.xml
  
  The data load order configuration file.
Optional: Open the business object configuration file (wc-loader-member-group-member.xml) for editing and configure the settings for loading your member data.
1. 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.
2. 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.
3. Configure the MemberGroupMemberValueHandler value handler parameters to resolve the unique ID for a user by using the user email address.
  By default, the sample configuration file is configured to resolve the member ID by the logon ID for the user.
  1. Locate the following <_config:ValueHandler> elements for including or excluding a user from being added to a member group. This configuration element controls how the Data Load utility resolves the value for the unique ID of a member (person).
```
  <_config:mapping xpath="IncludedPerson[0]/UniqueID" value="uniqueId" >
    <_config:ValueHandler className="com.ibm.commerce.member.dataload.config.MemberGroupMemberValueHandler">
      ...
      <_config:Parameter name="logonId" value "logonId" />
    </_config:ValueHandler>
  </_config:mapping>
  ...
  <_config:mapping xpath="ExcludedPerson[0]/UniqueID" value="uniqueId" >
    <_config:ValueHandler className="com.ibm.commerce.member.dataload.config.MemberGroupMemberValueHandler">
      ...
      <_config:Parameter name="logonId" value "logonId" />
    </_config:ValueHandler>
  </_config:mapping>
```
  2. Remove the logon ID parameter.
```
<_config:Parameter name="logonId" value "logonId" />
```
  3. Add the following configuration parameter for resolving the unique ID based on the email address. Add the parameter within the value handler configuration in the <_config:mapping> element for including or excluding a user from a member group.
```
<_config:Parameter name="email" value "email" />
```
    Where
    
    email
    
    Indicates that the Data Load utility is to retrieve the email address for a user from the input file for use in resolving the unique ID. The value for the parameter, which is also email, identifies the input file column that includes the data that the utility passes in to the SQL to resolve the unique ID. The parameter is supported for use with only the MemberGroupMemberValueHandler value handler.
  4. Optional. Add one or both of the following configuration parameters to the value handler configurations to control how the utility processes email addresses.
    
    emailCaseSensitive
    
    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. Set the value for the property to true when you know that the case for the email addresses in your input file and database are the same.
    
    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
    
    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. If you are adding or updating members for a member group and an input file email address does not match any address in the database, the email address is handled as a new member group member. A new unique ID generates for the email address and the Data Load utility adds the new member to the member group.
  For example, the following code snippet includes the email configuration parameter to resolve the unique ID for based on the email address for a user. The following code also includes the configurable parameters checkEmailFlag and emailCaseSensitive:
```
<_config:DataMapping>
  ...
  <_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="false" valueFrom="Fixed" />
    </_config:ValueHandler>
  </_config:mapping>
  <_config:mapping xpath="ExcludedPerson[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="-1" valueFrom="Fixed" />
    </_config:ValueHandler>
  </_config:mapping>
  ...
</_config:DataMapping>
```
4. Add any configurable properties that you want to use to control how the Data Load utility loads your member group member data.
  For example, you can include one or more of the following properties, which are intended for loading data to add or replace members in a member group.
  
  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 handles loading email addresses when a user ID cannot be resolved or created. Use this property 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 number 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.
  
  For example, the following code snippet configures the enabling of the preceding properties in the business object configuration file:
```
<_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:BusinessObjectMediator>
```
5. 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 member 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 list of <_config:LoadItem> elements, ensure that the value for name attribute for one of the elements is MemberGroupMember. Ensure that the value for the businessObjectConfigFile attribute for this load item identifies the wc-loader-member-group-member.xml business object configuration file. In the <_config:DataSourceLocation> element, ensure that the value of the location attribute identifies the input XML file that you are loading. If the files are not in the same directory as the data load order configuration file, include the relative path to the file. If you are not loading any other member data, comment out the remaining load item configurations.
3. Save and close the configuration file.
Run the Data Load utility.
Verify that the member group member data is loaded by reviewing the data load summary report.
For more information about the location and contents of this summary report, see Verify that the Data Load utility loaded the member data successfully.
You can also verify that the member data is loaded by comparing the contents of your input file with the member data in your HCL Commerce database. Ensure that the data within your input file exists within the appropriate database tables.