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.
-
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.
-
Create a backup of either the MemberGroupMember.csv or
MemberGroupMember.xml input file.
-
Open the input file for editing.
-
Replace the column heading
logonId
with email
.
For example,
MemberGroupMember,,,,
memberGroupName,email,excluded,memberType,delete
-
Replace the sample member group and member data with the data that you want to load.
-
Save and close your input file.
-
Create the Data Load utility configuration files that you need to load your member group member
data.
-
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
-
Create a backup of the wc-dataload-env.xml environment configuration
file.
-
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.
-
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
.
-
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
.
-
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.
- 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>
- Remove the logon ID
parameter.
<_config:Parameter name="logonId" value "logonId" />
- 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.
- 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>
-
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>
-
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.
-
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.
-
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.
-
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.