WebSphere Commerce Business Edition: Customizing the user registration attributes

This article describes how to customize the user registration attributes using IBM® WebSphere® Commerce 5.4 or 5.5.

Ross McKegney (rmckegne@ca.ibm.com), Software Engineer, IBM Canada

Ross McKegney is a software engineer at the IBM Toronto Lab, Ontario, Canada. He is the lead developer of the Member Management component of WebSphere Commerce.



Wesley Philip (wphilip@ca.ibm.com), Software Developer, IBM Canada

Wesley Philip is a Software Developer at the IBM Toronto Lab, Canada. He is the development owner of the Member subsystem of WebSphere Commerce.



Jacob Vandergoot (jvandergoot@ca.ibm.com), Software Engineer, IBM

Jacob Vandergoot is a software engineer at the IBM Toronto Lab, Ontario, Canada. His current responsibilities involve the Runtime Infrastructure components of WebSphere Commerce.



28 January 2004

Introduction

The tools and sample stores shipped with WebSphere Commerce Versions 5.4 and 5.5 use a subset of the possible list of user registration attributes. This article describes how to extend the store-front and tools registration pages to support additional attributes provided out of the box and how to define and use custom attributes.


Supported attributes

The list of supported attributes for the user registration flow is available from the online help by searching for "UserRegistrationAdd command" and "UserRegistrationUpdate command". The online documentation lists which attributes are mandatory, and contains a complete list of attributes provided out of the box. The out of the box attributes are fields from the following database tables:

  • USERS
  • USERREG
  • USERPROF
  • USERDEMO
  • BUSPROF
  • ADDRESS
  • MBRATTR

The store models shipped with WebSphere Commerce 5.5 and the sample stores in WebSphere Commerce 5.4 all use a subset of these attributes. If you want to customize the registration form with attributes that are not in the samples, then first check to see if what you want is already in the list of attributes provided.

If you have a specific requirement, and cannot find an attribute from the list that is suitable to map for your use, then you can create a custom attribute. You can define custom attributes without making any changes to the code by updating a database table and adding the new parameter to the URL request invoked from your JSP.


Defining custom attributes

You can define custom attributes using the MBRATTR and MBRATTRVAL tables. The MBRATTR table supports the definition of custom attribute types. The MBRATTRVAL table is where the values for these custom defined attribute types get persisted.

To define a custom member attribute, add the entry to the MBRATTR table. The fields of the MBRATTR table are:

MBRATTR_IDPrimary key of this MBRATTR table.
ATTRTYPE_IDType of the member attribute. Foreign key to ATTRTYPE table.
NAMEName of the member attribute.
DESCRIPTIONDescription of the member attribute.

Let's assume that you want to create a new attribute called "corporateemail." This is a string representing the user's internal email account. You can create the entry in the MBRATTR table as follows:

insert into MBRATTR values ((select min(mbrattr_id) - 10000 from mbrattr),'STRING',
 'corporateemail',NULL)

Now that you have the custom attribute, you can use it in the registration flow. The values for these attributes are stored in the MBRATTRVAL table:

MBRATTRVAL_IDPrimary key for this table.
STOREENT_IDThe store entity to which this attribute value for this member applies.
MEMBER_IDThe member to which this attribute value applies. Foreign key to the MEMBER table.
ATTRTYPE_IDType of the member attribute value. Foreign key to the ATTRTYPE table.
MBRATTR_IDThe attribute that this value is associated with. Foreign key to the MBRATTR table.
FLOATVALUEIf the type of the attribute value is FLOAT, this column holds the attribute value. If the type is not FLOAT, this column is NULL.
INTEGERVALUEIf the type of the attribute value is INTEGER, this column holds the attribute value. If the type is not INTEGER, this column is NULL.
STRINGVALUEIf the type of the attribute value is STRING, this column holdsthe attribute value. If the type is not STRING, this column is NULL.
DATETIMEVALUEIf the type of the attribute value is TIMESTAMP, this column holds the attribute value. If the type is not TIMESTAMP, this column is NULL.

Depending on the type of the attribute, the attribute value will go in the corresponding field.


Using custom attributes in the registration flow

The descriptions of the user registration commands (Add and Update) in the online help describe how to add custom attributes to the command request. Ensure that the attributes are defined in the MBRATTR table, then you can use them by adding parameters to the request in the following format:

&attributeName_storeName_action_number=value

The attributeName matches the NAME field in the MBRATTR table, the storeName is the STOREENT_ID of the store (from the STOREENT table). The action is either "a" for add, "r" for replace, or "d" for delete. The number is an attribute that you can use to store multiple values for the same attribute.

Let's look at some examples.

Example 1: corporate email

This example is the corporate email attribute created earlier. To add a corporate email value, add the following parameter:

&corporateemail_null_a_null=myemail

This creates an entry in the MBRATTRVAL table with the value myemail in the STRINGVALUE field.

Example 2: corporate email, store specific

This example uses the same attribute, but now you can store it in a store dependent way. This is useful if you want to capture different values for the same attribute, depending on the store.

&corporateemail_10001_a_nul=myemail

This again creates an entry in the MBRATTRVAL table with the value myemail in the STRINGVALUE field, but it also adds the store identifier of 10001 to the STOREENT_ID field.

Example 3: corporate email, multi-valued

This example again builds on the previous example, but it supports multiple values for the same attribute.

&corporateemail_10001_a_1=myemail&corporateemail_10001_a_2=myemail2

This creates two entries in the MBRATTRVAL table. The first storing of myemail in the STRINGVALUE field, and the second storing of myemail2 in the STRINGVALUE field.


Customizing store pages

To take advantage of some of the fields not leveraged by the out-of-the-box models, or to use custom attributes, such as those described in the previous section, the requirement for the store-front customization is purely at the JSP level. Add the additional fields to your page, and pass them to the user registration commands.


Customizing Accelerator pages

Assuming you have customized the store-front registration pages to support the attributes required by your organization, you may wish to make the same customization in the WebSphere Commerce tooling. This last section describes how to customize the Accelerator customer update wizard to support additional attributes.

The Accelerator feature is based on the WebSphere Commerce tools framework, which provides a number of reusable widgets for Web-based tools development. The customer update feature, which is what you want to customize, is implemented as a multi-panel wizard. After selecting a customer, the customer service representative (CSR) navigates through the four panels (General, Address, Contact, and Demographics) to update information about the customer. Each of these four panels is implemented as a Java Server Page, which caches the values filled in by the CSR such that the properties from all four pages are bundled and passed through to the underlying command (CSRCustomerInfoUpdateCmd) when the update is submitted. This invokes the registration update command, UserRegistrationAdminUpdateCmd.

The default implementation of the CSRCustomerInfoUpdateCmd is expecting only a subset of the attributes supported by the real registration command. If you want to define additional attributes, you either override the command or use the approach described in the remainder of this section to flag your additional properties so that they will be passed through CSRCustomerInfoUpdateCmd to UserRegistrationAdminUpdateCmd. The latter option is only available with WebSphere Commerce 5.4 Fixpack 6 or later, and WebSphere Commerce 5.5 Fixpack 3 or later. If you are using WebSphere Commerce 5.4 or 5.5 prior to these fixpack levels, contact WebSphere Commerce support to request this feature as an APAR.

To pass through your own attributes, in addition to those supported by the default Accelerator pages, add them to one of the existing property objects in the JSP, with a prefix of "ext_" in the name. The following example shows how to update the PropertyProfile.jsp to support the userProfileField1 attribute.

Figure 1 displays the default Accelerator user profile page, with the added userProfileField1.

Figure 1. Accelerator pages with an additional attribute model
Accelerator pages with an additional attribute model

The underlying JSP for this page is called PropertyProfile.jsp. To get the additional field, add the following immediately above the section where the last visit is displayed:

<TR>
  <TD>
      User profile field1: <INPUT size="20" type="text" 
        name="ext_userProfileField1" maxlength="254">
   </TD>
</TR>

This creates the textbox, and captures the result in the ext_userProfileField1 variable. Note that the userProfileField1 attribute is one of the parameters supported by the UserRegistrationAdminAdd command. You use the "ext_" prefix to inform the tools framework command that this is an extension attribute and it should be passed through to this command.

The next step is to update the savePanelData() function in the JSP to ensure that the value for this new variable is saved as the user navigates across panels. Insert this code snippet after the other updates to the profileInfo object:

profileInfo.ext_userProfileField1 =
    document.profile.ext_userProfileField1.value;

The profileInfo object is locally defined, and is converted by the tools framework into an XML format and passed on to the underlying command. You can implicitly define the ext_userProfileField1 field of the object, and assign to it the value captured from the field created above. When the user types data into the user profile field1 field on the form, that data is copied into the local profileInfo object.

The tools page has logic that can determine precisely what aspects of the user profile have been updated, such that unchanged data is not passed on to the registration command. You need to update this logic for any changes that might happen to the new field. Update the compare() function in the JSP:

  if (parent.get("userRegUpdated") =="false" 
      && e.type == "text" 
      && e.name == "ext_userProfileField1") {
    if (e.value !=
      "<%UIUtil.toJavaScript(registerDataBean.getUserProfileField1())%>") {
      parent.put("userRegUpdated", "true"); 
     }
  }

This code goes through each variable on the page (the object "e" that appears in this code snippet is the current attribute) and checks against the defined criteria to determine if the page has been updated. In this case, the attribute of interest has the name of ext_userProfileField1, and the value that you want to compare it against is the field1 attribute from the user profile table. It is available from the databean using the getUserProfileField1() method. If the value on the page is different from the value cached in the bean, then you know the value has been updated so set the flag for userRegUpdated to true.

If you are adding your own custom attributes, keep the following update flags in mind:

  • userProfileUpdated
  • addressUpdated
  • demographicsUpdated
  • userUpdated
  • userRegUpdated
  • certStatusUpdated (WebSphere Commerce 5.4 only)

You can also put the following XML objects in your attributes:

  • profileInfo (the one used in this example)
  • addressInfo
  • contactInfo
  • demographicsInfo

Because there is no direct mapping between the update flags and the data objects, the underlying logic passes through any extension attribute to the registration command. The one exception is that extension attributes in the addressInfo if the addressUpdated flag is set. The address updates are fairly complex operations, and you do not want to do it unless it is absolutely necessary. The updates to the other tables are relatively trivial, and pushing back the same data is not an issue.

There are a few minor changes to make to the JSP, for managing the state as the user navigates through the panes. The first one is to update the initializeState() function. This function has a decision point at the entry to determine if it is the first update, or a subsequent update. Add the following code for the state information that has already been initialized. For example, the user is navigating between panes:

  document.profile.ext_userProfileField1.value =
    profileInfo.ext_userProfileField1;

This copies the form field value into the local object.

Within the same method, also update to initialize the page for the first time:

  document.profile.ext_userProfileField1.value =
    "<%=UIUtil.toJavaScript(registerDataBean.getUserProfileField1())%>";

This is the logic that ensures that the form field picks up the value from the database on the first time into the page. Now the user can navigate between panes, and update any attribute.


Conclusion

You can do everything that has been described in this article without making changes to the registration commands. To add custom member attributes to the store front registration pages, add the new attribute definition to the database and update the JSP to pass the values to the command. To extend the Accelerator user profile pages, you can update the JSPs using the technique described.


Acknowledgements

The authors would like to thank Anthony Tjong for his inspiration and guidance in the writing of this article.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=14111
ArticleTitle=WebSphere Commerce Business Edition: Customizing the user registration attributes
publish-date=01282004