Mapping REST resources to Business Object Document (BOD) nouns

REST services are built on top of OAGIS services. Each REST resource is mapped to a Business Object Document (BOD) noun. An XML configuration file is provided to transform between a BOD noun and REST data. The REST services framework then uses this configuration file to generate REST response data from a BOD object and construct a BOD object from REST request data.

The XML configuration files are packaged under the following directory by default: Rest.war/WEB-INF/config/bodMapping

The file names are in the following format: rest-resourceName-clientobjects.xml. They use the same schema as the Management Center.

See the following sample configuration files for more information:

The following XML snippet shows an example of the mapping between a noun and REST data map:


<!-- Product summary data -->
<_config:URLParameterGroup name="productSummary" 1 noun="CatalogNavigationView">
     <_config:IncludeURLParameterGroup urlParameterGroup="price" 2 />
     <_config:IncludeURLParameterGroup urlParameterGroup="facet" />
     <_config:IncludeURLParameterGroup urlParameterGroup="breadCrumbTrail" />
     <_config:IncludeURLParameterGroup urlParameterGroup="previewReport" />
     <_config:IncludeURLParameterGroup urlParameterGroup="suggestion" />
     <_config:IncludeURLParameterGroup urlParameterGroup="webContent" />

     <_config:URLParameter name="recordSetComplete" nounElement="/Show/@recordSetCompleteIndicator" 3
              key="false" return="true" />
     <_config:URLParameter name="recordSetTotal" nounElement="/Show/@recordSetTotal" 
              key="false" return="true" />
     <_config:URLParameter name="recordSetCount" nounElement="/Show/@recordSetCount" 
              key="false" return="true" />
     <_config:URLParameter name="recordSetStartNumber" nounElement="/Show/@recordSetStartNumber" 
              key="false" return="true" />

     <_config:URLParameter name="CatalogEntryView/productType" 4
              nounElement="/CatalogEntryView/@CatalogEntryTypeCode" 5
              key="false" 6 return="true" 7 />

     <_config:URLParameter name="CatalogEntryView/buyable" nounElement="/CatalogEntryView/@buyable" 
              key="false" return="true" />
     <_config:URLParameter name="CatalogEntryView/uniqueID" nounElement="/CatalogEntryView/UniqueID" 
              key="true" return="true" />
     <_config:URLParameter name="CatalogEntryView/partNumber" nounElement="/CatalogEntryView/PartNumber" 
              key="false" return="true" />

     ......
     <!-- UserData Section -->
     <_config:URLParameter name="x_" nounElement="/UserData/UserDataField" return="true" type="UserData" 8 />
</_config:URLParameterGroup>

Where:

1 URLParameterGroup name: The URL parameter group name. REST services base on this group and the URLParameters under it to do the mapping.
2 IncludeURLParameterGroupurlParameterGroup: Specifies a declared URL parameter group to include as part of the current URL parameter group. The URL parameter names of the included URL parameter groups will be merged to describe a complete URL parameter name to noun element or attribute mapping.
3 nounElement for Show object: The element or attribute of the Show object with which the value should be associated. To map to an element use the format nounElement="/ElementName". To map to an attribute use the format nounElement="/ElementName/@AttributeName".
4 URLParameter name: The URL parameter name. It will become a key in REST data map.
5 nounElement for noun object: The element or attribute of the noun object with which the value should be associated. To map to an element use the format nounElement="/ElementName". To map to an attribute use the format nounElement="/ElementName/@AttributeName".
6 key: Optional: The unique identifier of the noun or the complex type of the noun. The default value is false.
7 return: Optional: Specifies if the noun element should be included in the response when building the response object. The default value is false unless the value of the key attribute is true.
8 type: Optional: The data type of the noun element or attribute. If a value of UserData is specified, then the URL parameter mapping has special meaning and the URL parameter name begins with the specified name attribute. URL parameters of type UserData where the name of the element is part of the URL parameter name have special parsing behavior. The name and value are mapped to a new object, as indicated by the nounElement attribute. You can also specify the UserDataAssociation element for a more complex object mapping.

A noun might have a nested data structure. Using the XML mapping file, each noun element is mapped to a REST data attribute and the noun is converted into a Map so that REST data can be easily parsed by client applications. For most of the noun elements, they will be converted to entries in a flattened Map. However, if a noun element is a list, this data field will be converted to a List of Map. For example, with OrderItem being a list in the Order noun, REST services will automatically create List of Map for OrderItem:


<_config:URLParameter name="orderItem/orderItemId" nounElement="/OrderItem/OrderItemIdentifier/UniqueID" key="true" return="true" />
<_config:URLParameter name="orderItem/externalOrderItemID" nounElement="/OrderItem/OrderItemIdentifier/ExternalOrderItemID" key="false" return="true" />
<_config:URLParameter name="orderItem/productId" nounElement="/OrderItem/CatalogEntryIdentifier/UniqueID" key="false" return="true" />

You can create an extension configuration file to overwrite the default data mapping. You must create a customized version of the file in a new folder, with the customized version of the file must contain only the changed properties.

The following procedure is also applicable when you generate a new REST service using the JET resource pattern. In this case, you create your own rest-resourceName-clientobjects.xml to transform between your BOD noun and REST data.

Procedure

Open WebSphere Commerce Developer and switch to the Enterprise Explorer view.
Create a custom data mapping file (rest-resourceName-clientobjects.xml), if one does not already exist:
1. Navigate to the following path:
  Rest.war/WEB-INF/config
2. In the config folder, create a new bodMapping-ext folder so the path looks like this:
  Rest.war/WEB-INF/config/bodMapping-ext
  If this folder already exists and it contains a customized version of the rest-resourceName-clientobjects.xml file, then open the file and skip to step 4.
3. Create an empty rest-resourceName-clientobjects.xml file in the Rest.war/WEB-INF/config/bodMapping-ext folder. This file is your custom rest-resourceName-clientobjects.xml file.
Add the basic XML elements required for your custom rest-resourceName-clientobjects.xml file.
Add the XML for any properties that you want to change to your custom rest-resourceName-clientobjects.xml file:
1. Navigate to the default configuration file at the following path:
  Rest.war/WEB-INF/config/bodMapping/rest-resourceName-clientobjects.xml
  Never change properties directly in this file because your changes will be overwritten with future IBM software updates.
2. Copy the XML elements for the properties you want to change from the default catalog component configuration file to your custom rest-resourceName-clientobjects.xml file.
  Even though you are copying only certain elements, you must maintain the XML hierarchy for those elements in the file.
3. Change the values for the copied properties as required.
  Adding an attribute:
```
<_config:URLParameter name="householdSize" nounElement="/PersonalProfile/HouseholdSize" key="false" return="true" />
```
  Removing an attribute:
```
<_config:URLParameter name="companyName" nounElement="/PersonalProfile/CompanyName" key="false" return="false" />
```
4. Include user data:
  UserData must have a predetermined x prefix and the URLParameter XML element must also have an attribute type="UserData". For example, in rest-cart-clientobjects.xml file, the following URLParameter is mapped to all the Userdata directly under OrderItem:
```
<_config:URLParameter name="orderItem/xitem_" nounElement="/OrderItem/UserData/UserDataField" 
key="false" return="true" type="UserData"/>
```
  If you create the following 2 key/value pairs:
```
expiration=01012012
return=30d
```
  REST services returns these 2 pieces of UserData along with other data fields in the BOD mapping file. The key is appended to xitem_ to identify the context of the UserData. You can follow this convention to get all UserData from REST services:
```
{
"xitem_expiration" : "01012012",
"xitem_return" : "30d"
}
```
  Note: UserData automatically flows to REST services as long as the BOD mapping file has a URLParameter element to return the userData.
Save and close the custom configuration file.
Test your configuration changes.
Deploy the customized file to the production environment.

What to do next

When you customize wc-rest-resourceconfig.xml file to use a different access profile, if the new access profile returns the noun with additional data fields that are not defined in the BOD mapping XML file, you must extend the BOD mapping XML file to return additional attributes in the new access profile:

Create a custom data mapping file (rest-resourceName-clientobjects.xml) under the Rest.war/WEB-INF/config/bodMapping-ext directory. This file is your custom rest-resourceName-clientobjects.xml file.

Decide the URLParameterGroup for the additional data fields. For example:


<_config:URLParameterGroup name="productSummary" noun="CatalogNavigationView">

Add additional data attributes under the URLParameterGroup.
Restart your WebSphere Commerce server for the customization to take affect.