Tutorial: Extending a BOD service to manage UserData with the Data Service layer

In this tutorial, you customize the Catalog service to support warranty information and care instructions for Catalog Entries. This customization updates the WebSphere Commerce schema so that it stores the new information and customizes the Catalog service to include new information. The new information is included as user data in the CatalogEntry noun.
In this tutorial, you customize the Catalog service to support warranty information and care instructions for Catalog entries. You work with the WebSphere Commerce BOD programming model, the CatalogEntry noun, and the CatalogEntryDescription noun. You configure the business object mediator to populate warranty information as UserData in the CatalogEntry noun and care instruction information as attributes to the CatalogDescription noun part. You are creating a custom query template file to map an XPath expression and access profile to SQL. The template file performs the following tasks:
  1. Defines an SQL template statement that fetches data from the new tables.
  2. Associates a new access profile to the new SQL template statement.
  3. Associates an XPath expression to the new SQL template statement.

The WebSphere Commerce BOD programming model separates processing into the business logic layer and the persistence layer. The business logic layer works with logical service data objects (SDOs), which are the Java representation of nouns. The persistence layer creates, reads, updates, or deletes business objects in the WebSphere Commerce database. This separation allows adding new data to affect only the persistence layer.

The CatalogEntry noun uses the UserData element as a data extension point to add new data without changing the logical model. In this tutorial, warranty information is added to the CatalogEntry noun UserData element to demonstrate the addition of language-dependent properties. For this tutorial, a warranty applies to a specific catalog entry and consists of a number of days the warranty applies and a warranty type: either limited or comprehensive.

The Catalog description noun part supports the attributes element as a data extension point. Attributes provide the same functions as the UserData element. Product care instructions are added to the CatalogEntryDescription noun part attributes element to show the addition of language independent properties. In this tutorial, a care instruction applies to a specific catalog entry and language and consists of a text description of the instruction.

The following example CatalogEntry noun shows the customization of the CatalogEntry UserData element and CatalogEntryDescription attributes element:
<_cat:CatalogEntry catalogEntryTypeCode="ProductBean">
      <_cat:CatalogEntryIdentifier>
        <_wcf:UniqueID>10251</_wcf:UniqueID>
        <_wcf:ExternalIdentifier ownerID="7000000000000000101">
          <_wcf:PartNumber>FULO-01</_wcf:PartNumber>
        </_wcf:ExternalIdentifier>
      </_cat:CatalogEntryIdentifier>
      <_cat:Description language="-1">
        <_cat:Name>White Fabric Roll Arm Chaise</_cat:Name>
        <_cat:Thumbnail>images/catalog/FULO_01_sm.jpg</_cat:Thumbnail>
        <_cat:FullImage>images/catalog/FULO_01.jpg</_cat:FullImage>
        <_cat:ShortDescription>Plumply padded for your ultimate comfort.</_cat:ShortDescription> 
        <_cat:Attributes name="catentryId">10251</_cat:Attributes>
        <_cat:Attributes name="languageId">-1</_cat:Attributes>
        <_cat:Attributes name="careinstruction">Warranty description for the chaise.</_cat:Attributes>
      </_cat:Description>
      <_wcf:UserData>
        <_wcf:UserDataField name="warterm">30</_wcf:UserDataField>
        <_wcf:UserDataField name="wartype">LIMITED</_wcf:UserDataField>
      </_wcf:UserData>
</_cat:CatalogEntry>
The persistence layer is customized according to the following diagram:
Customization points for adding the warranty information to the CatalogEntry noun.
Note: Workspaces are not supported when completing this tutorial.

Learning objectives

After completing this tutorial, you should be familiar with the following concepts:
  • Understanding the WebSphere Commerce Data Service Layer
  • Overview of simple extension and customization tasks.
After completing this tutorial, you should be able to perform the following tasks:
  • Updating the WebSphere Commerce database with new tables and relationships.
  • Generating custom object-relational metadata that describe new tables and relationships.
  • Generating static service data objects (SDO) that provide a Java representation of the newly added tables.
  • Configuring the logical DataObject to physical DataObject mapping.
  • Creating a custom query template file to map an XPath expression and access profile to SQL.

Time required

Expect this tutorial to take one hour to complete. The tutorial takes longer if you explore concepts related to this tutorial.

Skill level

This tutorial is intended for advanced WebSphere Commerce developers responsible for creating and customizing WebSphere Commerce BOD services. To complete this tutorial you should be familiar with the following terms and concepts:
  • Web services
  • XML
  • WebSphere Commerce services
  • Relational databases
  • SQL

System requirements

Before beginning this tutorial, ensure that you complete the following tasks:

Note: Workspaces are not supported when completing this tutorial.