Catalog Administration Tasks

 

WebLogic Commerce Server provides administrators with command-line scripts, property files, and JSP-based administration tools accessed from a browser. The Administration Tools allow you to manage the behavior and content of your product catalog.

For catalog administration, the tasks include:

• Starting the Server

• Starting the Administration Tools

• Changing the Administrator Password

• Loading Data into the Product Catalog

• Adding Categories to the Catalog

• Adding Items to the Catalog

• Controlling the Visibility of Items in the Catalog

• Assigning Items to Categories

• Editing the Attributes for Categories and Items

• Editing the Availability of an Item

• Determining How Categories and Items are Displayed to the Web Site User

• Deleting Items or Removing Items from One or More Categories

• Removing Categories

• Moving Items from One Category to Another Category

• Defining Custom Attributes for Items

• Improving Catalog Performance by Optimizing the Catalog Cache

• Using the wlcs-catalog.properties File

Note: In this topic, the environment variable WL_COMMERCE_HOME is used to represent the directory in which you installed the WebLogic Commerce Server software.

 

---

Starting the Server

The WebLogic Commerce Server Administration Tools run as a Web application in the WebLogic Server environment. The WebLogic Commerce server must be running before you can use the Administration Tools.

When you start the server for a WebLogic Commerce Server application, you are passing WebLogic Commerce Server-specific property values (and other required values, such as the location of the Java 2 SDK) to the WebLogic Server. This information gives the server instance the context it needs to provide services to the application.

For administrators, WebLogic Commerce Server provides a StartCommerce.bat (Windows) or StartCommerce.sh (UNIX) script. Detailed instructions can be found in the chapter "Starting the Server" in the Deployment Guide.

 

---

Starting the Administration Tools

With the WebLogic Commerce server running, as outlined in the previous section, you can access the main administration screen by opening the following URL in a browser:

http://localhost:7501/tools

The above URL assumes that you are running the server on your local machine and you want to perform administration tasks on the local machine. If the WebLogic Commerce Server application is running on a remote node, you can specify the remote node name to invoke its Administration Tools. For example, if the remote node is named blues, you can use the following URL:

http://blues:7501/tools

Another option on Windows systems is to start the main administration screen by using the following Start menu path:

Start --> BEA WebLogic E-Business Platform --> BEA WebLogic Commerce Server 3.5 --> Administration Tools

A third option is to click the Administration link that appears in the top banner of most JSP templates. Figure 4-1 shows the link in an extract of the main.jsp template.

Figure 4-1 Link to Administration Tools from JSP Template

 

Before the browser can open the page, you must log into the Administrator account, as shown in Figure 4-2.

Figure 4-2 Administration Login Screen

 

WebLogic Commerce Server defines an Administrator account name for you. The default password is password (lowercase characters). See Changing the Administrator Password for a related discussion.

Following valid login credentials, the main administration screen is displayed, as shown in Figure 4-3.

Figure 4-3 Administration Tools Home Page

 

Most of the remaining sections in this chapter describe the Catalog Management tasks.

Figure 4-4 identifies the two types of links on the Catalog Management graphic.

Figure 4-4 Links on the Catalog Management Graphic

 

When you click the icon that looks like a catalog book, the main Catalog Administration screen is displayed, as shown in Figure 4-5.

Figure 4-5 Main Catalog Management Screen

 

Table 4-1 summarizes the catalog management functional areas.

Table 4-1 Catalog Management Functional Areas

Catalog Management Functional Areas	Description
Categories	You can add categories, edit the attributes for categories, move items from one category to another category, and remove categories from the product catalog.
Items	You can add items, edit the attributes for items, add custom attributes for items, and remove items from the product catalog.
Cache	You can tune the performance of your catalog by adjusting the size and time-to-live (TTL) properties for the separate, in-memory caches defined for categories and items. Balancing the cache to match your peak usage can significantly improve the satisfaction level of customers using your e-commerce Web site.

 

 

---

Changing the Administrator Password

The initial account information for the administrator account supplied with WebLogic Commerce Server is:

Username:  administrator
Password:  password

To change the password of the administrator account, follow these steps:

1. Open the Administration Tools Home Page, as described in Starting the Administration Tools. The server must be running. One way to access the Administration Tools Home Page is to enter the URL in your browser:

   http://localhost:7501/tools

2. When you are prompted to log in, enter the current password.

3. On the Administration Tools Home Page, click the User Management icon, as shown in Figure 4-6.

   Figure 4-6 User Management Icon on Main Administration Screen

   
    

4. On the User Management screen, click the underlined Users link, as shown in Figure 4-7.

   Figure 4-7 Users Link on the User Management Screen

   
    

5. On the Users screen, search for the administrator account name, as shown in Figure 4-8.

   Figure 4-8 Searching for the Administrator Account

   
    

   After you enter administrator in the Username input box, click the Search button.

6. In the Search Results screen, click the underlined administrator link, as shown in Figure 4-9.

   Figure 4-9 Administrator Link in the User Account Search Results

   
    

   Warning: Do not click the red X to the right of the account name. Clicking the red X will delete the account.

7. On the Users: administrator screen, click the Edit button, as shown in Figure 4-10.

   Figure 4-10 Edit Button on Users: administrator Screen

   
    

8. On the Users: Username screen, enter the new password twice, as shown in Figure 4-11.

   Figure 4-11 Entering the New Password

   
    

Warning: Make sure to remember the new password for the administrator account! That sounds obvious, but there is a potential "Catch-22" situation. To change the account password again, you must log into the Administration Tools, a step that requires the current administrator password. If you forget the account's password, you will have to recreate the Commerce database.

After entering the new password, click the Save button. Then click the Home button at the top of the screen to return to the main administration screen.

 

---

Loading Data into the Product Catalog

WebLogic Commerce Server provides a DBLoader program that can bulk load data into the product catalog database. While you could use the WebLogic Commerce Server Administration Tools to add new items or category data, one record at a time, this is impractical when you need to load hundreds or thousands of records. The DBLoader program is also useful when loading legacy data from an existing database into the WebLogic Commerce Server database.

You can also use a database vendor's specific loader program such as Oracle SQL Loader, or a data loader by a third-party company, to populate the product catalog database.

For details, see Using the Product Catalog Database Loader.

 

---

Adding Categories to the Catalog

You can add a new category by using either the DBLoader program, as described in Using the Product Catalog Database Loader, or by using the Administration Tools. This section explains how to use the Administration Tools.

The steps are as follows:

1. Make sure the WebLogic Commerce server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the Administration Tools Home Page, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the Create button on the Categories graphic, as shown in Figure 4-12.

   Figure 4-12 Create Button on Categories Graphic

   
    

   On the Categories screen, you can either add a new category at the current level in the catalog hierarchy, or you can click an existing category name to create a subcategory. Figure 4-13 shows the Categories screen.

   Figure 4-13 Portion of Categories Screen When the Create Button Is Clicked

   
    
    

   As you will recall from the section Catalog Hierarchy, the categories in the product catalog are organized as a hierarchy as shown in Figure 4-14.

   Figure 4-14 Product Catalog Hierarchy

   
    

   An individual item can reside in more than one category. However, categories cannot reside outside of their individual hierarchical paths. In other words, a category that resides in one path of the hierarchy cannot also reside in another path of the hierarchy.

5. To add a new category at the current level in the hierarchy, click the red and white plus sign icon on the Categories screen. If you are on the highest level of the categories hierarchy, the link text next to the plus-sign icon is: "Add a top level subcategory". For example, assume that you want to add a "Wood and Lumber" category because the electronic store will now offer different types of specialty hardwoods such as Ash. After you create the Wood and Lumber category, you will then create an "Ash" subcategory.

6. Figure 4-15 and Figure 4-16 show the top portion and bottom portion of the Create New Subcategory screen, after you click the plus-sign icon. (The screen is split into two figures for space reasons only.)

   Figure 4-15 Top Portion of the Create New Subcategory Screen

   
    

   Figure 4-16 Bottom Portion of the Create New Subcategory Screen

   
    

7. Enter the required fields, which are indicated by the asterisk (*). The required fields are:

   • Category Identifier (also the primary key of the WLCS_CATEGORY table in the Commerce database). In this example, enter Wood.

   • Category Name. In this example, enter Wood and Lumber.

   • Short Description. Enter a short description such as "hardwood, exterior, moulding, construction grade".

     You have the option of leaving the other fields blank for now because they are not required fields or primary keys in the WLCS_CATEGORY table. For more information about the category fields, see the section The WLCS_CATEGORY Database Table.

8. After you enter the field values, click the Create button to create the new category. (Or click the Back button to cancel the current create category operation.)

9. When the new category has been created, a confirmation message is displayed on the refreshed Categories screen. Figure 4-17 shows the confirmation message after creating the new category.

   Figure 4-17 Confirmation Screen After New Category Is Created

   
    

10. When you click the Back button near the bottom of the Create Category screen (not the browser's Back button), the Category screen is refreshed to include the new category. Figure 4-18 shows the new Wood and Lumber category under the catalog's top-level root.

    Figure 4-18 Newly Added Category Near Bottom of Category Screen

    
     

11. To create subcategories in a existing category, first click the red arrow to the left of the category name. For example, assume that you want to add a Hardwood subcategory under the Wood and Lumber category. To do this, click the red right-arrow next to the Wood and Lumber category. Figure 4-19 shows the updated screen.

    Figure 4-19 Updated Screen While Adding a Subcategory

    
     

    The icon next to the Wood and Lumber category changes to a red, hollow, left-facing arrow. To proceed, click the plus-sign icon that appears indented below the category. In this example, click the plus-sign icon next to the text, Add a subcategory to Wood and Lumber.

12. Figure 4-20 shows the top portion of the next screen: Create New Subcategory below Category : 'Wood and Lumber'. On this screen, we have entered data into the first three fields.

    Figure 4-20 Creating a New Subcategory

    
     

Click the Create button to create the new subcategory Hardwood under the Wood and Lumber category.

Repeat the previous steps to create additional categories and subcategories.

 

---

Adding Items to the Catalog

You can add one or more product items to an existing category by using either the DBLoader program, as described in Using the Product Catalog Database Loader, or by using the Administration Tools. This section explains how to use the Administration Tools.

After the catalog's categories and items are stored in the database, you will perform a separate set of steps to assign items to categories, as described in the section Assigning Items to Categories.

The steps are as follows:

1. Make sure the WebLogic Commerce Server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the Create button on the Items graphic, as shown in Figure 4-21.

   Figure 4-21 Create Button on Items Graphic

   
    

5. The Create New Item screen is displayed. Figure 4-22 and Figure 4-23 shows the top portion and bottom portion of the screen.

   Figure 4-22 Top Portion of the Create New Item Screen

   
    

   Figure 4-23 Bottom Portion of Create New Item Screen

   
    

6. Edit the product item fields. The required fields, indicated with an asterisk (*) next to the field name, are:

   • SKU, an acronym for Stock Keeping Unit. This is the unique identifier for the item in the catalog. It is the primary key of the WLCS_PRODUCT table in the Commerce database.

   • Item Name

   • Short Description

     You have the option of leaving the other fields blank for now because they are not required fields or primary keys in the WLCS_PRODUCT table. For more information about the product item fields, see the section The WLCS_PRODUCT Database Table.

     Note: See the section Controlling the Visibility of Items in the Catalog for important information about the Visible check box.

7. For example, assume that you need to add a new product item, an "Ash-1x3". Figure 4-24 shows the top portion of the screen as it appears when information is being added about this item.

   Figure 4-24 Adding a New Product Item

   
    

   When you add an item, make sure you add a full set of keywords that describe the item. Doing so will make it easier for the Web site users to find items in the catalog via keyword-based searches. Adding lots of descriptive keywords will also make it easier for you to find items in the Administration Tools when you want to assign them to one or more categories. You can always remove keywords later if too many keywords are returning spurious results in keyword searches.

   Figure 4-25 shows the portion of the Create a New Item screen where you can enter keywords. Type the each keyword into the left-side text box, and click the right arrow to add it to the list. If necessary, highlight an unwanted keyword in the right-side list and then click the left arrow to remove it from the list.

   Figure 4-25 Entering Keywords on the Create a New Item Screen

   
    

   Note: By default, all keywords that are entered on this administration screen are converted to lowercase characters. Because the search engine is case sensitive, this consistent conversion means that your subsequent searches for items via keyword searches should use lowercase characters. You can enter keywords in mixed case or ALL CAPS, but the keywords are stored in lowercase, by default. This behavior is set in the wlcs-catalog.properties file. For more information, see the section Using the wlcs-catalog.properties File.

8. After you enter the field values, click the Create button to create the new item. (Or click the Back button on the screen to cancel the create item operation.)

9. When the new item has been created, a confirmation message is displayed on the refreshed Item screen: The item was created.

 

---

Controlling the Visibility of Items in the Catalog

The visibility attribute of items in the product catalog is currently only applied to the results of keyword searches and query-based searches. Thus if users of your deployed Web site are browsing for an item (by clicking through the catalog's hierarchy of categories and subcategories), by default they will see the item even if you left the Visible check box unchecked.

To make an item invisible to the results of keyword searches of the catalog, in the current release you must:

• Mark the item as invisible (set or leave the Visible check box unchecked)

• Orphan the item by removing it from all categories

An uncategorized item, also known as an orphaned item, is one that has been removed from all categories, but still resides in the WLCS_PRODUCT table in the Commerce database.

For searches of the catalog, the default end-user CatalogRequest object has the showAll attribute set to false; thus invisible items are not displayed. In contrast the default administrator's CatalogRequest object has the showAll attribute set to true, ensuring that administrators can see invisible items when they perform search operations via the Administration Tools.

 

---

Assigning Items to Categories

Assuming that you have already entered categories and items in the Commerce database, either through a bulk loader program like DBLoader or through the Administration Tools, you can assign each item to one or more categories. This section shows how to use a WebLogic Commerce Server Administration Tools to make the assignments.

What if I Have a Large Amount of Data?

If you have a catalog with hundreds of categories and thousands or tens of thousands of items, making the assignments via the Administration Tools is obviously not practical. An alternative is to use the DBLoader. Create a text data input file to populate the WLCS_PRODUCT_CATEGORY table in the database. As illustrated in Figure 2-1, the WLCS_PRODUCT_CATEGORY table maps the CATEGORY_ID primary key from WLCS_CATEGORY table to the SKU primary key for the WLCS_PRODUCT table.

For related information, also see:

• The WLCS_PRODUCT_CATEGORY Database Table.

• Using the Product Catalog Database Loader.

Using the Administration Tools to Assign Items to Categories

To assign items to categories in the Administration Tools, follow these steps:

1. Make sure the WebLogic Commerce server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the underlined Categories link.

5. In the Catalog hierarchy display, click the category or subcategory into which you want to add the item.

   Note: To expand a current category and reveal its subcategories (if any), make sure you click the red arrow to the left of a category name. If you instead click the current category's underlined name, you are taken to its Edit Category screen.

6. When the category or subcategory that you want to add items to is shown in the hierarchy, click its underlined link. For example, assume that you clicked the red arrow next to the Wood and Lumber category, then clicked the underlined Hardwood link. (These sample categories were added to the catalog in the previous section, Adding Categories to the Catalog.)

7. Figure 4-26 shows the top portion of a sample Editing Category: Hardwood screen. Notice the link near the top of the display: To modify the items assigned to this category, click here.

   Figure 4-26 Sample Editing Category Screen with Modify Link

   
    

8. Click the link titled, To modify the items assigned to this category, click here. When you do, a screen is displayed that is similar to the one shown in Figure 4-27. In this particular screen, there are currently no items assigned to the Hardwood category.

   Figure 4-27 Modify Items Assigned to Category Screen

   
    

9. The Items Assigned to Category text box shows the items that are already in this category. (In this example so far, there are no items in the Hardwood category.) You can search for the item you want to add or remove via three modes: keyword, query-based, or orphaned-items ("Uncategorized Items"). The search results are displayed on the left-side text box. To add an item to the category, move the item to the right-side text box by clicking on the right arrow.

   Warning: You must click the Save button to commit any changes to the category before performing a new search or leaving this page.

10. For example, assume that you need to assign the Ash-1x3 to the Hardwood category. (This item was added to the sample data in the catalog in the section Adding Items to the Catalog.) You can search for the keywords related to the item. Figure 4-28 shows a sample Modify Items Assigned to Category screen where the ash keyword was entered, the search results found the item, and the results were displayed in the left-side Search Results box.

    Figure 4-28 Sample Keyword Search Results on Modify Items Assigned to Category Screen

    
     
     

11. To add one or more items to the current category, select it or them in the left-side text box and then click the right-arrow button. The item(s) move(s) to the right-side text box. If you moved items, remember to click the Save button near the bottom of the page before you perform another search or leave this page. If no errors occur after you click the Save button, WebLogic Commerce Server displays a confirmation message. In this example, the message was: Category `Hardwood' has been updated.

12. To find items, via the query-based search, that you want to add to the category, you can use an expression such as the following examples:

    price > 100 && price <= 300 

    name like 'A*' 

    !(price > 100) || (msrpAmount >= 300) 

    modifiedDate < now 

    When the search results are displayed in the left-side text box, use the right-arrow button to move the appropriate items into the right-side Category Items text box. If you moved items, remember to click the Save button near the bottom of the page before you perform another search or leave this page. For details about the query-based search syntax, see the section Query-Based Search Syntax.

13. To find a product item that is no longer associated with any categories in the catalog, but the item is still in the catalog, click the Search button located under the text "Search for items which are not assigned to any category".

14. Again, to add one or more items (that you located via one of the three search options) to the current category, select them in the left-side text box and then click the right-arrow button. This step will move the items to the right-wide text box. If you moved items, remember to click the Save button near the bottom of the page before you perform another search or leave this page.

 

---

Editing the Attributes for Categories and Items

You can use the catalog Administration Tools to edit the attributes for existing categories and items.

Editing Category Attributes

To edit the attributes for a category, follow these steps:

1. Make sure the WebLogic Commerce server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the underlined Categories button on the Categories graphic.

5. On the main Categories screen, you can find the category you want to modify by either:

   • Entering its category identifier in the search input box. In the sample data that comes with the catalog tables in the Commerce database, the category identifier appears in parentheses next to the category name. You can assign an identifier when you create a new category, but once created, you cannot edit the identifier. Also, categories are created sequentially. The newest category is always displayed last in the list that the end user sees on your site. Figure 4-29 shows a portion of the resulting Categories screen after we entered the category identifier hardwood in the search field and clicked the Search button. In the figure, notice how the found category name is shown in red type.

     Figure 4-29 Sample Category Search Result

     
      

   • Or you can find the category you want to modify by simply browsing through the hierarchy of categories and subcategories. You can click the solid, red, right-facing arrows to expand a category and view its subcategories.

6. When the category you want to modify is displayed, click the name of the category. For example, Figure 4-30 shows a portion of the resulting screen when we clicked the Hardwood (Hardwood) category.

   Figure 4-30 Editing Category: Chargers Sample Screen

   
    

7. On this screen, you can add, change, or remove the category's attributes. See the screen itself online for the full set of attributes that can be modified. Also see The WLCS_CATEGORY Database Table for a description of the fields.

   Warning: By design, you cannot modify the category's unique identifier. If you had to change a category identifier, you would have to delete the category itself and then create a new category with a new, unique identifier. But be careful! As noted on the administration screen, removing a category removes it and all of its subcategories. In Oracle databases, this feature is known as a cascading delete operation. This feature is currently not supported in Cloudscape.
   
   Also, product items that are associated with removed categories may be orphaned (unless they belong to another category in the hierarchy). Orphaned items are allowed to remain in the catalog, and can be reassigned later to one or more categories. The caveat here is that by deleting a category, you may be inadvertently removing many subcategories from the catalog. Check the hierarchy carefully before clicking the red X next to a category name.

8. After you edit the attributes for the category, click the Save button to commit your changes to the database. Or, to exit the screen without committing your changes, click the Back button.

Editing Product Item Attributes

To edit the attributes for a product item, follow these steps:

1. Make sure the WebLogic Commerce Server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the underlined Items button on the Items graphic.

5. On the Item Search screen, you can find the product item by either entering one of its keywords, or by entering a query-based search expression, or by searching for orphaned items. For example, Figure 4-31 shows a portion of the resulting screen after we entered the keyword hammer. The list of matching items show the value for each item's Name field.

   Figure 4-31 Sample Keyword Search Results for Product Items

   
    

6. Another search option on the Item Search screen is entering an query-based search expression such as one of the following:

   price > 10 && price <= 50 

   name like 'H*' 

   !(price > 20) || (msrpAmount >= 30) 

   modifiedDate < now 

   If more than 10 search results have been returned, you can click the underlined Next button or Previous button (if any) to read through the list. For details about the query-based search syntax, see the section Query-Based Search Syntax.

   Figure 4-32 shows the results of a search for price > 10 && price <= 50.

   Figure 4-32 Sample Query-Based Search to Find a Product Item

   
    

7. After you find the item you want to modify, click the underlined item name to edit its attributes. Figure 4-33 shows the resulting screen when we click the search result for wrench Set-9-800215.

   Figure 4-33 Sample Initial Edit Item Attributes Screen

   
    

8. Click the red and white Edit button. Figure 4-34 shows a portion of a resulting Edit Item Information screen. (Notice how the price is greater than 10 and less than or equal to 50, from the prior search that returned this as a matching item.)

   Figure 4-34 Sample Edit Item Information Screen

   
    

9. On this screen, you can add, change, or remove the item's attributes. For example, you can change the item's price, short and long descriptions, its basic inventory setting, and its visibility in the catalog. See an Edit Item Information screen online for the full set of attributes that can be modified. See the section The WLCS_PRODUCT Database Table for details about the item's fields. Also see the section Controlling the Visibility of Items in the Catalog for important related information.

10. Before you save any changes on the Edit Item Information screen, set the item's inventory status on the Item Inventory screen. For information about this setting, see the next section, Editing the Availability of an Item.

11. After you edit the attributes for the item, click the Save button to commit your changes to the database. Or, to exit the screen without committing your changes, click the Back button. If no errors occur when you save your changes, WebLogic Commerce Server displays the message "The item was updated successfully".

 

---

Editing the Availability of an Item

In the current release, WebLogic Commerce Server provides an inventory setting in its Administration Tools. The Edit Item Information screen includes a link to the inventory function. (Please see the previous section, Editing Product Item Attributes, for information about how to find an item and get to the Edit Item Information screen.)

Figure 4-34 in the previous section showed the top portion of an Edit Item Information screen, which included the link, "For inventory information, click here." Figure 4-35 shows the Item Inventory screen that is displayed when you click this link.

Figure 4-35 Sample Item Inventory Screen

 

On this screen, you can click the Yes or No option to indicate whether the specific product item is in stock. Enter a text string (which can be displayed to a user of your Web site on the item details screen) to indicate the shipping time. You can also enter additional comments about the item's inventory.

Note: In the current release, WebLogic Commerce Server does not implement an automated inventory-count calculation.

If you made any changes on the Item Inventory screen, click the Save button. Otherwise, click the Back button.

 

---

Determining How Categories and Items are Displayed to the Web Site User

You can control the format and content of category and item data that is displayed to the Web site's users by setting the Display URLs field for each category or item. The WebLogic Commerce Server catalog includes the URL of three JSPs for items and categories:

• Display JSP for a category

• Summary display JSP for an item

• Detail display JSP for an item

This approach allows, for example, the colors and layout of individual items to be controlled on as fine a grained level as necessary. Categories can be assigned different JSPs to define a "look and feel" for the category. Items can be given different layout logic that is appropriate to the item.

By simply editing the name of the display JSPs in the Catalog Management Administration Tools, you can introduce promotional text, seasonal greetings, or special offers in the catalog. The default values that appear in the Display JSP URL field on the create/edit category or item screen are read from the wlcs-catalog.properties file in WL_COMMERCE_HOME/classes. For example:

# Default JSP for Categories
catalog.category.jsp.default =/commerce/catalog/includes/category.jsp 

# Default JSPs for Product Items
catalog.item.jsp.default.summary =/commerce/catalog/includes/itemsummary.jsp
catalog.item.jsp.default.details =/commerce/catalog/includes/itemdetails.jsp 

The URL values defined in the wlcs-catalog.properties file are relative to the WLCS Web application directory. However, you can prepend any URL or URI string that you need. Although you could use fully qualified local URLs, that could introduce portability problems if you need to move the application to another server.

You can change these Display JSP defaults in wlcs-catalog.properties. You also can overwrite the defaults URLs on the Administration screen by providing a pointer to another JSP template of your own design. And you can modify the format and content of the default or customized included JSP files. The values for the Display JSP URLs are stored in the following fields in the Commerce database:

• DISPLAY_JSP_URL in the WLCS_CATEGORY table

• DET_DISPLAY_JSP_URL and SUM_DISPLAY_JSP_URL fields in the WLCS_PRODUCT table

In the catalog's master JSP files (the JSPs that contain the <jsp:include...> tags), a related design decision is made by the Web designer or programmer about the type of summary or detail pages to be presented. For example, the details.jsp template is coded to return the summary JSP for items:

<%-- Get the summary JSP from the current product item --%>
<catalog:getProperty object="<%= item %>" 
   propertyName="Jsp" 
   getterArgument="<%= new Integer(ProductItem.DETAILED_DISPLAY_JSP_INDEX) %>" 
   id="detailJsp"
   returnType="com.beasys.commerce.ebusiness.catalog.JspInfo"/>

<%-- Included the detail JSP --%>
<jsp:include page="<%= detailJsp.getUrl() %>" flush="true"/>
</catalog:iterateThroughView>
   .
   .
   .

 

---

Deleting Items or Removing Items from One or More Categories

As described earlier in this chapter, you can assign an item to one or more categories. If necessary, you could use the Administration Tools to:

• Delete the item entirely from the catalog.

• Remove the item from one category while keeping its assignment to another category.

• Remove the item, one category at a time, from all categories, creating an "orphaned item" (also called an "uncategorized item" that still resides in the database).

Caching Considerations

Whenever possible, you should perform any Catalog Management operations during non-peak Web site usage. When you delete an item or remove an item from a category, WebLogic Commerce Server will automatically remove the item record from the ProductItemCache or CategoryCache. This step ensures that subsequent Web site users get a valid view of the available, categorized items.

However, if you use an SQL tool to directly delete an item from the database (WLCS_PRODUCT database table), or remove an association between an item and a category (WLCS_PRODUCT_CATEGORY mapping database table), you should flush the caches for items and categories. Flushing these in-memory caches is an administration function. For more information about caching, see the section Improving Catalog Performance by Optimizing the Catalog Cache.

Deleting an Item from the Catalog

To permanently delete an item from the catalog database via the Administration Tools, start by finding the item via one of the provided search options:

• Keyword-based search

• Query-based search

• Uncategorized items search

The steps to delete an item are as follows:

1. Make sure the WebLogic Commerce Server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the underlined Items link.

5. On the Item Search screen, perform one of the following steps:

   1. In the Keyword input box, enter a keyword that you know is associated with the item you need to delete, and then click its Search button. For example, Figure 4-36 shows the Search results on the refreshed Item Search screen after searching for the keyword cabinet.

      Figure 4-36 Sample Search for an Item Using Cabinet Keyword

      
       

      In the Search Results list, when the item that you need to delete is displayed, click the red X icon to the right of the item name.

      Warning: When you click the red X icon, the delete operation is immediate and permanent; a confirmation screen is not displayed.

   2. Or in the Query input box, enter an query-based search, such as one of the following examples to find the item you need to delete; then click its Search button.

      price > 100 && price <= 150 

      name like 'cabinet*' 

      modifiedDate < now 

      Note: The query expression name like is case sensitive. For example, figure shows the results of a query search that used the expression: name like `cabinet*'. Had the search string been name like `Cabinet*' the search would have yielded no string matches given the sample data provided by the product. For more information about the query syntax, see the section Query-Based Search Syntax.

      Figure 4-37 Sample Query-Based Search Results Screen

      
       

      In the Search Results list, when the item that you need to delete is displayed, click the red X icon to the right of the item name.

      Warning: When you click the red X icon, the delete operation is immediate and permanent; a confirmation screen is not displayed.

   3. Or click the Search button next to the text: Search for items which are not assigned to any category. Figure 4-38 shows the search results when you click this option. The layout of the text and results has been modified in the figure to fit into this document.

      Figure 4-38 Sample Search Results for Uncategorized Items

      
       
       

      In the Search Results list, when the item that you need to delete is displayed, click the red X to the right of the item name.

Warning: When you click the red X icon, the delete operation is immediate and permanent; a confirmation screen is not displayed.

Removing an Item from One or More Categories

The process to remove an item from one or more categories is similar to the process of assigning items to categories, which is explained in the section Using the Administration Tools to Assign Items to Categories.

For a given item, you can remove it (unassign it), one category at a time. If you remove the item from all categories, it remains in the Commerce database and is flagged as an uncategorized item, also known as an orphaned item.

Removing an item from one or more categories is different than deleting the item entirely from the database. If you need to delete an item entirely, see the section Deleting an Item from the Catalog.

The steps to remove an item from a category are covered in the following procedure. Due to their similarity, the sample screens that would duplicate the ones shown in the section Using the Administration Tools to Assign Items to Categories are not repeated here.

Note: To remove an item from a particular category, you must know in advance the name of the category to which the item is currently assigned. As the administrator, if you do not have this information, run the catalog's Web application and browse through the hierarchy of categories to find the item. If necessary, check with the development team to confirm that you are about to remove the item from the correct category (because the item can be associated with more than one category).

1. Make sure the WebLogic Commerce Server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the underlined Categories link.

5. In the Catalog hierarchy display, click the category or subcategory from which you want to remove the item.

   Note: To expand a current category and reveal its subcategories (if any), click the red arrow to the left of a category name. If you instead click the current category's underlined name, you are taken to its Edit Category screen.

6. When the category or subcategory name is shown in the hierarchy, click its underlined link.

7. On the Editing Category: <category name> screen, click the following link: To modify the items assigned to this category, click here.

8. Figure 4-39 shows a sample screen. In this example, assume that we need to remove one of the pneumatic hammer items from the following category:

   Root --> Hardware --> Storage and Cabinets --> Cabinets

   Figure 4-39 Removing an Item from a Category

   
    
    

   On the screen, the second item in the Items Assigned to Category text box has been highlighted, and the cursor is hovering over the left arrow.

9. Click the left arrow to remove the item from the category.

10. Click the Save button near the bottom of the screen to make the change. Or click the Back button near the bottom of the screen (before clicking the Save button) to cancel any updates you made on the screen.

If you need to remove an item from more than one category, you must do so one category at a time. After removing the item from the first category, repeat steps 4 through 9 to remove the item from the next category.

 

---

Removing Categories

To remove a category, find the category or subcategory via the Administration Tools and click the red X icon to the right of the target category or subcategory name. When you click the red X icon, you are prompted for a confirmation before the deletion starts.

Warning: Removing a category removes it and all of its subcategories (if any). In Oracle databases, this feature is known as a cascading delete operation. Cascading deletes are not supported currently in Cloudscape.

Also, product items that are associated with removed categories may be orphaned (unless they belong to another category in the hierarchy). Orphaned items are allowed to remain in the catalog, and can be reassigned later to one or more categories. The caveat here is that by deleting a category, you may be inadvertently removing many subcategories from the catalog. Check the hierarchy carefully before clicking the red X next to a category name

To remove a category from the catalog's hierarchy, follow these steps:

1. Make sure the WebLogic Commerce Server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click the underlined Categories button on the Categories graphic.

5. On the main Categories screen, you can find the category you want to modify by either:

   • Entering its category identifier in the search input box. In the sample data that comes with the catalog tables in the Commerce database, the category identifier is a letter of the alphabet followed by the category name.

   • Or by browsing through the hierarchy of categories and subcategories. Click the solid, red, right-facing arrows to expand a category and view its subcategories.

     Figure 4-40 shows a portion of the resulting Categories screen after searching for the category identifier hardwood. Notice how the found category name is shown in red type.

     Figure 4-40 Sample Category Search Result

     
      

6. When the category you want to remove is displayed, click the red X icon to the right of the category name. Be aware that:

   • Deleting a category removes it and all of its subcategories (if any). In Oracle databases, this feature is known as a cascading delete operation. This operation is not currently supported in Cloudscape.

   • Product items that are associated with deleted categories may be orphaned unless they belong to another category. Orphaned items will remain in the catalog, and can be reassigned later to one or more categories. Remember that by deleting a category, you may inadvertently remove many subcategories from the catalog. Check the hierarchy carefully before clicking the red X next to a category name.

 

---

Moving Items from One Category to Another Category

To move an item from one category to another category:

• Assign the item to the other category, as described in the section Using the Administration Tools to Assign Items to Categories.

• Remove the item from an existing category, as described in the section Removing an Item from One or More Categories.

 

---

Defining Custom Attributes for Items

You can define a property set that establishes custom attributes for an item. For a given item, a custom attribute that you define can be used in addition to the default attribute that was set by WebLogic Commerce Server in the Product Catalog database tables.

Warning: The default Product Catalog attributes that are provided by WebLogic Commerce Server (based on Dublin Core) are retrieved in a single SQL statement (from a single database table) and are cached. However, custom attributes typically require a single SQL statement (which involves multiple database tables) and are not cached. For optimal performance, BEA recommends that the use of custom attributes be minimized and that the catalog developer maps new custom attributes onto the default Dublin Core attributes. For related information about the category and item caches, see the section Improving Catalog Performance by Optimizing the Catalog Cache.

WebLogic Commerce Server uses the existing product architecture for defining property sets and assigning values to custom attributes. Both items and categories implement the ConfigurableEntity interface, allowing property sets to be used to define custom attributes for items and categories. At run time, these properties can be accessed or modified using the standard getProperty or setProperty interfaces of ConfigurableEntity.

The property set editor was introduced with an earlier release of WebLogic Personalization Server. Now the property set editor extends support to a new class of Property Set for the WebLogic Commerce Server catalog, and the product provides administrative tools that allow the custom attributes of categories and items to be edited. These tools are based on the familiar user interface for editing the custom attributes of groups and user (respectively).

You therefore have a number of options for customizing the WebLogic Commerce Server Product Catalog:

• Property Set Definition

  Defining Property Sets for custom attributes is a run-time operation that you can perform without having to restart the server. Domain-specific catalog attributes that cannot be mapped onto the metadata provided in the WebLogic Commerce Server schema (which is based on the Dublin Core standard) can be added to a Property Set for the catalog.

• Service Provider Interfaces

  The functional areas of the WebLogic Commerce Server Product Catalog can be unplugged (either individually or as a whole) to customize the behavior or data sources of the catalog. The customizable services are:

  • Product Item Manager - Responsible for managing the explicit attributes for an item.

  • Category Manager - Responsible for managing the mapping of items into categories.

  • Custom Data Manager - Responsible for managing the custom attributes for an item.

  • Catalog Query Manager - Responsible for executing keyword and attribute queries and returning collections of items.

  These steps are described in Using the API to Extend the Product Catalog.

• Entity Property Manager Customization

  Custom attribute management has been delegated from the Custom Data Manager to the Entity Property Manager. A new implementation of the Entity Property Manager could be plugged for custom data management.

 

---

Improving Catalog Performance by Optimizing the Catalog Cache

WebLogic Commerce Server provides tools that allow you to tune the response-time efficiency of your product catalog by adjusting the size and behavior of in-memory cache settings. Two separate caches have been implemented:

• CategoryCache

• ProductItemCache

There is only one instance of each cache per server. In a WebLogic Server clustered environment, the cache is specific to each server. Thus if you make adjustments to a CategoryCache or ProductItemCache on a particular server in the cluster, and you want that adjustment to take effect on other servers in the cluster, you must invoke the Administration Tools on each server machine and make the updates separately.

Values for each cache are defined in the weblogiccommerce.properties file and on a catalog administration screen. As the site administrator, your primary tasks related to the setup and maintenance of the caches are as follows:

• Enable or disable each cache. Keeping the cache enabled is highly recommended. Each cache is enabled by default.

• Set the size of each cache. That is, the maximum number of category and item records in each cache.

• Set the time-to-live (TTL) for each cache.

• Increase or decrease the size of each cache.

• Flush the cache.

• View percentage statistics about the hit or miss rate of each cache.

• Reset the statistics.

By experimenting with the size and time-to-live (TTL) values for each cache, you can achieve optimal performance of the catalog. Most importantly, you can significantly improve the satisfaction level of customers who are shopping on your Web site. The goal of the cache is to avoid, as much as possible, excessive accesses to the Commerce database as the application software performs catalog data lookup requests.

Cache-Related Values in weblogiccommerce.properties

The WL_COMMERCE_HOME\weblogiccommerce.properties file includes the following values related to the category and item caches:

# Cache entries

ProductItemCache.ttl=21600000
ProductItemCache.capacity=10000
ProductItemCache.enabled=true

CategoryCache.ttl=86400000
CategoryCache.capacity=1000
CategoryCache.enabled=true

Table 4-2 describes the values defined for each cache property:

Table 4-2 Cache Property Values in weblogiccommerce.properties

Property Value	Default Value	Description
ProductItemCache.ttl	2160000 milliseconds (360 minutes, or 6 hours)	Sets the time-to-live (TTL) value that gets assigned to each item record that is added to the ProductItemCache. When the value has expired, the item is removed from the cache. Then as new item records are accessed by users (items retrieved from the database), a copy of each record is added to the server-wide item cache.
ProductItemCache.capacity	10000 items	Sets the maximum number of product items that can be loaded into the ProductItemCache.
ProductItemCache.enabled	true	Can be set to true or false. BEA recommends that you always leave the cache enabled; if your catalog has highly volatile product item data, use a lower TTL value to ensure that the data is refreshed at appropriate intervals.
CategoryCache.ttl	86400000 milliseconds (1440 minutes, or 24 hours)	Sets the time-to-live (TTL) value that is assigned to each category record in the CategoryCache. When the value has expired, the category record is removed from the cache. Then as new category records are accessed by users (categories retrieved from the database), a copy of each record is added to the server-wide category cache.
CategoryCache.capacity	1000 categories	Sets the maximum number of category records that can be loaded into the CategoryCache.
CategoryCache.enabled	true	Can be set to true or false. BEA recommends that you always leave this cache enabled; if your catalog has highly volatile category data, use a lower TTL value to ensure that the data is refreshed at appropriate intervals.

 

Use the caching statistics to understand whether the values that you select initially are too low or too high.

Note: Remember that in a WebLogic Server clustered environment, the cache is specific to each server. Thus if you make adjustments to a CategoryCache or ProductItemCache on a particular server in the cluster, and you want that adjustment to take effect on other servers in the cluster, you must perform the administration tasks on each server machine and make the updates separately.

Considering Hardware Costs Versus the Cost of Dissatisfied Web Site Users

BEA recommends that you provide sufficient hardware memory resources so that you can cache your entire product catalog. As you consider the options for implementing a caching strategy to support your e-commerce Web site's product catalog, ask the following question. In the long-term, what is more expensive:

• The costs associated with increasing RAM capacity on your Web servers,

• Or the cost of losing potential Web shoppers who grew impatient with the performance of your catalog's pages?

BEA suggests that, almost certainly, losing customers due to poor site performance will be far more costly than purchasing the necessary RAM hardware to support your site.

What's in Each Cache Initially?

When the server starts, it reads the property values for the CategoryCache and ProductItemCache from the weblogiccommerce.properties file. But those values simply set the behavior and potential size of the separate caches. Each cache is initially empty.

As users start accessing the site's pages and requests for category or product item data are received, the WebLogic Commerce Server software first checks to see if the requested category or item record is in the cache. If the record resides in cache, it is returned to the requesting user and displayed. If the record does not reside in cache, the record is retrieved from the Commerce database, put in cache, returned to the requesting user and displayed.

If you are interested in the architectural view of how the catalog service managers use cache, see the section Catalog Architecture and Services.

The Catalog Cache Administration Screen

To start the catalog cache administration screen, follow these steps:

1. Make sure the WebLogic Commerce Server is running. See the section Starting the Server.

2. Start the Administration Tools. See the section Starting the Administration Tools.

   Note: As previously mentioned, in a WebLogic Server clustered environment the cache is specific to each server. Thus if you make adjustments to a CategoryCache or ProductItemCache on a particular server in the cluster, and you want that adjustment to take effect on other servers in the cluster, you must perform the administration tasks on each server and make the updates separately.

   From your browser, you can administer another server in the cluster by specifying the other server's name in the URL (assuming that the WebLogic server software is already running on the remote machine). For example, if the machine Blues is a remote server in the cluster, you can use the following URL from a browser sessions on your local machine to invoke the main administration screen for the remote server:

   http://blues:7501/tools

3. On the main administration screen, click the Catalog Management graphic.

4. On the main Catalog Management screen, click either the Configure button or the underlined Cache link on the Cache graphic, as shown in Figure 4-41.

   Figure 4-41 Configure Button on Cache Graphic

   
    

5. Figure 4-42 shows the resulting initial Cache Statistics and Configuration screen.

   Figure 4-42 Initial Cache Statistics and Configuration Screen

   
    

6. On the Cache Statistics and Configuration screen, you can:

   • Enable or disable each cache. The general recommendation is that you leave both caches enabled.

   • Click the underlined ProductItemCache link to view a separate screen that only shows item cache statistics. By going to the cache-specific screen, you can flush just that cache.

   • Click the underlined CategoryCache link to view a separate screen that only shows category cache statistics. By going to the cache-specific screen, you can flush just that cache.

   • Change the value for the ProductItemCache or CategoryCache capacity. This is the maximum number of items or categories allowed in each cache.

   • Change the value for the ProductItemCache or CategoryCache time-to-live (TTL), shown in minutes. This is the maximum time that an item will not be reread from the database.

   • View statistics about the following:

     The number of product items or categories currently in the cache (Items column).

     The number of requests for product items or categories (Requests column).

     The number of times a requested product item or category was found in the cache (Hits).

     The number of times a requested product item or category was not found in the cache (Misses).

     The hit percentage; that is, the total requests divided by the number of hits (Rate% column).

     Note: The Administration Tools always bypass the cache. Thus any access you perform to category and item data in the Administration Tools will not be seen in the statistics.

7. The buttons on the screen perform the following functions:

   • To return to the main catalog administration screen, click the Back button. If you do not click the Save button before clicking the Back button, any changes you made are not performed.

   • To save any changes you make, click the Save button.

   • To reset the statistics to zero, click the Reset All button.

   • To flush the contents of both caches, click the Flush All button.

A basic approach to working with the statistics is as follows:

1. Reset the caching statistics in the administration screen.

2. Let the Web site run for awhile.

3. Examine the statistics and look at the Hit Rate (the % of times the requested record was found in the cache, instead of having to get the record from the database).

4. Adjust the caching values in the administration screen.

Repeat this process until the Hit Rate is high.

 

---

Using the wlcs-catalog.properties File

In the WebLogic Commerce Server's default Product Catalog configuration, the wlcs-catalog.properties file serves two purposes. The first part of the file defines values for internationalization string constants and constant configuration parameters, while the second part of the file defines the names of the tables, columns, and the SQL statements used by the JDBC catalog implementation to perform persistence activities.

Note: To learn more about string constants and constant configuration parameters, see Some Property Values You Might Modify. To learn how to modify the names of tables, columns, and so on, see Editing the Catalog Schema Definition.

In most cases, you will not have to modify the content of the wlcs-catalog.properties file. However, some of the properties are relevant to developers who need to extend the catalog to suit specific business requirements, or to internationalize the catalog for non-English readers.

Location

The default wlcs-catalog.properties file is located in WL_COMMERCE_HOME\classes, where WL_COMMERCE_HOME is the directory in which you installed the WebLogic Commerce Server software.

Some Property Values You Might Modify

The wlcs-catalog.properties file contains over 1000 lines of name/value properties. Table 4-3 lists a subset of the properties to introduce you to the type of information contained within the file. After reading this summary, you should be able to decide if your catalog's environment would benefit by adjusting the values in wlcs-catalog.properties.

Table 4-3 Summary of Values in the wlcs-catalog.properties File

Property	Value and Description
catalog.jsp.date.format	MM/dd/yyyy hh:mm:ss z Sets the default format of DATE or TIMESTAMP fields in the database.
catalog.jsp.default.iterator.size	10 Sets the default size of the ViewIterators created by Pipeline Components. You should set this parameter to a large enough value so that a typical set of items will not require an excessive number of trips to the database.
catalog.searchresults.size	-1 Sets the maximum search results returned by the catalog. -1 means unlimited search results size. You can dynamically change the search results by using the get/set MaxSearchResults methods on the CatalogQuery object.
catalog.jsp.keyword.convert	lower Used by the Administration pages to determine whether keywords should be case converted. Possible values are: lower upper none
catalog.category.jsp.default	/commerce/catalog/includes/category.jsp Sets the default JSP file used to display a category.
catalog.item.jsp.default.summary	/commerce/catalog/includes/itemsummary.jsp Sets the default JSP file used to display an item's summary page.
catalog.item.jsp.default.details	/commerce/catalog/includes/itemdetails.jsp Sets the default JSP file used to display an item's details page.
catalog.custom.data.catalog.manager	com.beasys.commerce.ebusiness.catalog.CatalogManager The JNDI name of the CatalogManager used to access Custom properties.
Messages: The wlcs-catalog.properties file includes numerous properties for catalog-related messages. A few examples: user.message.error.format.date.log =The date format is invalid. Please enter a valid date. user.message.error.duplicate.user =A category with the specified identifier already exists. Category identifiers must be unique within the catalog. user.message.search.invalid.expression.user =The search expression you have entered is invalid. Please try again. If desired, you can change the value on the right side of the equal sign. For example, internationalization (I18N) developers can translate the values to a non-English language. Types of messages: General user messages Category messages Item messages Search messages Tag messages Error messages See the wlcs-catalog.properties files for the full set of messages.

 

Editing the Catalog Schema Definition

In addition to modifying some name/value pairs in the wlcs-catalog.properties file, you may also want to customize the names of the tables and/or columns used by the BEA WebLogic Commerce Server Product Catalog system.

The schema and persistence definition section of the wlcs-catalog.properties file are referenced by the Tier 2 JDBC catalog Service Providers.

Warning: The configuration parameters listed in this section are subject to change. Take extreme care when editing the persistence parameters.

The name of the persistence definition (or schema) file used by the Tier 2 Service Providers is loaded from the deployment environment of the stateless session beans. Therefore, it is possible to deploy multiple instances of the catalog services that are bound to different schema files. This allows multiple instances of the WebLogic Commerce Server Product Catalog to be deployed, bound to distinct tables or columns.

Note: For more information about multiple Product Catalog instances, see Method 3: Multiple Product Catalog Instances.

By editing the schema file you can modify the names of tables and columns. The SQL scripts should also be modified to reflect the new names. An example from the default schema file is presented in Listing 4-1.

Listing 4-1 Default Schema File

####################################################################
#  CATALOG TABLE NAMES
####################################################################

CATALOG_TABLE_CATEGORY=WLCS_CATEGORY
CATALOG_TABLE_PROD_ITEM=WLCS_PRODUCT
CATALOG_TABLE_PROD_KEYWORD=WLCS_PRODUCT_KEYWORD

By editing the right-hand side of the equal sign, you can modify the names of the tables used by the WebLogic Commerce Server Product Catalog Tier 2 persistence mechanism.

Notes: It is not currently possible to add or remove attributes by editing the schema file. New attributes (schema additions) are best handled by writing a new CustomDataManager stateless session bean that reads and writes the values of the new properties, or by using the provided CustomDataManager, which will store the values in the WLCS_CAT_ set of tables.

Please refer to the comments within the wlcs-catalog.properties file for additional details.