Part 1: Adding language insensitive properties in the Catalogs tool

In this lesson, you are customizing the Catalogs tool to support more UserData information that is added to the CatalogEntry noun. In this tutorial, you are adding support for catalog entry warranty details information. You can follow the same procedure for any language insensitive properties of a noun.

About this task

In this part of the tutorial, you are completing the following tasks:

Updating the WebSphere Commerce schema to store new information.
Customizing the catalog service to include new information as user data in the CatalogEntry noun.
Adding custom queries to a custom query template file.
Customizing Management Center UI and customizing store UI with <wcf:getData> tag.

Procedure

Update the wc-query-MyCompanyCatalogEntry-get.tpl query template file to add data to the CatalogEntry noun. The wc-query-MyCompanyCatalogEntry-get.tpl query template file contains the following information:
- A symbol definition section that defines the tables included in the query template. In this tutorial you are including the CATENTRY, CATENTDESC, XWARRANTY, XCAREINSTRUCTION database tables in the symbol definition section.
- Definition of a new association SQL statement that seeks the new custom data.
- Definition of a new access profile MyCompany_All, which extends the default CatalogEntry Summary access profile: IBM_Admin_Summary.
  Note: IBM_Admin_ prefixes as used in the access profile IBM_Admin_Summary are intended to be used by admin/Management Center services calls. Access profiles that do not follow the new naming conventions continue to function correctly, as compatibility is maintained with earlier versions. It is recommended, however, that they are followed for existing access profiles, and when you change future access profiles.
The data service layer tutorial that you completed as a prerequisite before you began this tutorial uses a simple query template to add new data. In this tutorial, you are updating a Management Center query that displays catalog entries. Depending on how the query is defined by using associated queries, you might have to extend the access profile and add an associated query.
1. Open the WebSphere Commerce Developer.
2. In the Enterprise Explorer view, navigate to WC > xml > config > com.ibm.commerce.catalog-ext.
3. Open the wc-query-MyCompanyCatalogEntry-get.tpl file for editing.
4. Locate the following code:
```
BEGIN_XPATH_TO_SQL_STATEMENT
name=/CatalogEntry[CatalogEntryIdentifier[(UniqueID=)]]+MyCompany_All
base_table=CATENTRY
sql=
SELECT
CATENTRY.$COLS:CATENTRY$,
CATENTDESC.$COLS:CATENTDESC$,
XWARRANTY.$COLS:XWARRANTY$,
XCAREINSTRUCTION.$COLS:XCAREINSTRUCTION$
FROM
CATENTRY
LEFT OUTER JOIN XWARRANTY ON (CATENTRY.CATENTRY_ID = XWARRANTY.CATENTRY_ID)
LEFT OUTER JOIN CATENTDESC ON (CATENTDESC.CATENTRY_ID = CATENTRY.CATENTRY_ID AND 
CATENTDESC.LANGUAGE_ID = $CTX:LANG_ID$)
LEFT OUTER JOIN XCAREINSTRUCTION ON (CATENTRY.CATENTRY_ID = XCAREINSTRUCTION.CATENTRY_ID 
AND XCAREINSTRUCTION.LANGUAGE_ID = $CTX:LANG_ID$)
WHERE
CATENTRY.CATENTRY_ID IN (?UniqueID?) AND
CATENTRY.MARKFORDELETE = 0
END_XPATH_TO_SQL_STATEMENT
```
5. Replace it with the following code:
```
BEGIN_ASSOCIATION_SQL_STATEMENT
name=MyCompanyWarrantygetCatalogEntryDetailsByParentCatalogGroupId
base_table=CATENTRY
additional_entity_objects=true
SQL=
SELECT
CATENTRY.$COLS:CATENTRY$,
CATENTDESC.$COLS:CATENTDESC$,
XWARRANTY.$COLS:XWARRANTY$,
XCAREINSTRUCTION.$COLS:XCAREINSTRUCTION$
FROM
CATENTRY
LEFT OUTER JOIN XWARRANTY ON (CATENTRY.CATENTRY_ID = XWARRANTY.CATENTRY_ID)
LEFT OUTER JOIN CATENTDESC ON (CATENTDESC.CATENTRY_ID = CATENTRY.CATENTRY_ID 
AND CATENTDESC.LANGUAGE_ID in ($CONTROL:LANGUAGES$))
LEFT OUTER JOIN XCAREINSTRUCTION ON (CATENTRY.CATENTRY_ID = XCAREINSTRUCTION.CATENTRY_ID 
AND XCAREINSTRUCTION.LANGUAGE_ID in ($CONTROL:LANGUAGES$))
WHERE
CATENTRY.CATENTRY_ID IN ($ENTITY_PKS$) AND
CATENTRY.MARKFORDELETE = 0
END_ASSOCIATION_SQL_STATEMENT
```
6. Extend the default access profile IBM_Admin_Summary in the profile definition. Add the following code at the bottom of the wc-query-MyCompanyCatalogEntry-get.tpl file:
```




BEGIN_PROFILE
name=MyCompany_All
extends = IBM_Admin_Summary
BEGIN_ENTITY
associated_sql_statement=MyCompanyWarrantygetCatalogEntryDetailsByParentCatalogGroupId
END_ENTITY
END_PROFILE
```
  Where:
  
  name
  
  Specify the name of your custom profile, for example MyCompany_All.
  
  extends
  
  Specify which default access profile you are going to extend, for example IBM_Admin_Summary.
  
  associated_sql_statement
  
  Specify the new associated SQL statement for fetching your custom data for example, MyCompanyWarrantygetCatalogEntryDetailsByParentCatalogGroupId.
  
  Note: To define a new access profile, see Access profiles. You do not have to copy all associated queries that are defined in the default CatalogEntry Details access profile, such as IBM_Admin_Summary. By following the proceeding steps, both the existing catalog entry data and the new custom data are returned.
Register the custom access profile on the client side.
In this step, you configure the Management Center client to get the Warranty data.

To register the custom access profile on the client side, create a custom configuration file, get-data-config.xml. The get-data-config.xml file configures how the Management Center retrieves the data from the server with the foundation tag library <wcf:getData>. The extension version of this file in the com.ibm.commerce.catalog-ext directory overrides the original definition.
The GetData tag configuration tag is configured by the WebSphere Commerce getData action. This action searches for configuration files that are named get-data-config.xml in the WEB-INF/config directory. The configuration files must adhere to the following rules:
- The root element is get-data-config.
- Each component has one configuration file that is used with the getData action.
- Base component configuration file locations are in the following directory: LOBTools > WebContent > WEB-INF > config > base > component. Where component is a directory that is unique to the component.
- Client extension locations are in the following directory: LOBTools > WebContent > WEB-INF > config > component-ext. Client extensions are loaded after base component configurations.
In the get-data-config.xml file, you must specify the expression builder and the access profile information. The access profile is MyCompany_All. An expression builder is a helper class, or a template, declared in the WebSphere Commerce get-data-config.xml file. It is used by the getData tag in a JSP file to construct an XPath expression that retrieves data.
1. Determine the service URL name. To find the service URL name, you enable tracing in the Management Center.
  1. Open the WebSphere Application Server administrative console. Right-click your test server: select Administration > Run administrative console.
  2. Expand Troubleshooting and select Logs and Trace.
  3. Choose Server1.
  4. Select Change Log detail Levels
  5. Enable trace, com.ibm.commerce.lobtools.*=all, in either the Configuration or Runtime tab:
    - Configuration tab
      The log messages display after you restart the server. When the server restarts, BOD message display without re-enabling trace in the administrative console.
    - Runtime tab
      The log message display without restarting the server. After you restart the server, trace must be re-enabled, otherwise the log message is not displayed.
    Note: The preceding line must be terminated with a colon.
  6. Save the change.
  7. Open Management Center with logging enabled:
    - https://host_name:8000/lobtools?logger.display=true where host_name is the host name for your development environment.
    For more information about logging in Management Center, see Enabling Management Center client-side logging and tracing
  8. Click Management Center Tools > Logging and Tracing.
  9. In the Logging and Tracing dialog, set the following options:
    - In the Default Log Level field select CONFIG.
    - Click Enable.
    Trace is enabled. Do not close the Logging and Tracing dialog
  10. Open the Catalogs tool in Management Center, navigate to a product display page.
  11. Click Send Now in the Logging and Tracing panel.
  12. Open WCDE_installdir\wasprofile\logs\server1\trace.log to view the trace log file. The service URL is /cmc/GetCatalogGroupChildren-CatalogEntry.
2. Determine the controller JSP file.
  1. In the Enterprise Explorer view, navigate to LOBTools > WebContent > WEB-INF and open the following file:
    - struts-ibm-tools.xml
    - struts-ibm-catalog.xml
  2. Search for the following code:
```
<action path="/GetCatalogGroupChildren-CatalogEntry" forward="/jsp/commerce/catalog/restricted/GetChildCatalogEntryForCatalogGroup.jsp" />
```
    The controller JSP file is GetChildCatalogEntryForCatalogGroup.jsp.
3. Determine which expression builder to use.
  Open the GetChildCatalogEntryForCatalogGroup.jsp file. Note the value of the expression builder, getCatalogEntryDetailsByParentCatalogGroupId:
```
<wcf:getData type="com.ibm.commerce.catalog.facade.datatypes.CatalogEntryType[] 
"var="catalogEntryChildren" expressionBuilder="getCatalogEntryDetailsByParentCatalogGroupId" 
varShowVerb="showVerb" recordSetStartNumber="${param.recordSetStartNumber}" 
recordSetReferenceId="${param.recordSetReferenceId}" maxItems="${param.maxItems}">
  <wcf:contextData name="storeId" data="${param.storeId}"/>
  <wcf:contextData name="catalogId" data="${param.catalogId}"/>
  <wcf:contextData name="langId" data="${param.languageId}"/>
  <wcf:param name="catGroupId" value="${param.parentId}"/>
</wcf:getData>
```
  The name of expression builder that you declare in the custom get-data-config.xml file is getCatalogEntryDetailsByParentCatalogGroupId.
4. Locate the IBM provided expression builder to override it.
  1. In the Enterprise Explorer view , navigate to LOBTools > WebContent > WEB-INF > config > com.ibm.commerce.catalog.
  2. Open the get-data-config.xml file.
  3. Search for the expression builder name: getCatalogEntryDetailsByParentCatalogGroupId.
```
<expression-builder>
  <name>getCatalogEntryDetailsByParentCatalogGroupId</name>
  <data-type-name>CatalogEntry</data-type-name>
  <expression-template>{_wcf.ap=$accessProfile$}/CatalogEntry[ParentCatalogGroupIdentifier[(UniqueID='$catGroupId$')]]</expression-template>
  <param>
    <name>accessProfile</name>
    <value>IBM_Admin_Summary</value>
  </param>
</expression-builder>
```
  The default access profile is IBM_Admin_Summary. You override the expression builder by changing the value of the access profile.
5. Create a custom, get-data-config.xml configuration file.
  Warranty information is added to the CatalogEntry noun UserData element. To fetch extra Warranty information from the CatalogEntry noun, create a custom configuration file that overrides the base component configuration file.
  1. In the Enterprise Explorer view, navigate to LOBTools > WebContent > WEB-INF > config.
  2. Right-click config then click New > Folder.
  3. In the Folder name field, enter com.ibm.commerce.catalog-ext
  4. Click Finish. The folder com.ibm.commerce.catalog-ext is created under the config directory.
  5. Right-click com.ibm.commerce.catalog-ext then click New > File.
  6. In the File name field, enter get-data-config.xml
  7. Click Finish. The get-data-config.xml file opens.
  8. Copy the following code to the extended get-data-config.xml:
```
<?xml version="1.0" encoding="UTF-8"?>
<_config:get-data-config 
xmlns:_config="http://www.ibm.com/xmlns/prod/commerce/foundation/config" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/commerce/foundation/config ../../xsd/get-data-config.xsd ">
  <expression-builder>
    <name>getCatalogEntryDetailsByParentCatalogGroupId</name>
    <data-type-name>CatalogEntry</data-type-name>
    <param>
      <name>accessProfile</name>
      <value>MyCompany_All</value>
    </param>
  </expression-builder>
</_config:get-data-config> 
```
    Note: In this code, the expression template is not included. This expression builder uses the access profile that you defined and the expression template from the IBM provided definition. This behavior is because you extended the expression builder and the name, getCatalogEntryDetailsByParentCatalogGroupId remains the same.
  9. You can also declare the expression builder findAllCatentriesBasicSearch. The findAllCatentriesBasicSearch ensures that your new custom data displays in the product details that return from shopper searches on your storefront. To use this expression builder, add the code for this expression builder after the code for the getCatalogEntryDetailsByParentCatalogGroupId expression builder in the get-data-config.xml file.
```
<expression-builder>
  <name>findAllCatentriesBasicSearch</name>
  <data-type-name>CatalogEntry</data-type-name>
  <param>
    <name>accessProfile</name>
    <value>MyCompany_All</value>
  </param>
</expression-builder>
```

Results

So far, you registered the custom access profile on the client side, so that client side can communicate with the server side. In the next lesson, you start customizing the client-side GUI.