Chapter 7
Administering Catalogs
This chapter provides information and guidelines for administering BuyerXpert/SellerXpert catalogs.
|
Note
|
The information in this chapter is based on the assumption that you have already read Concepts and Release Notes.
|
This chapter contains the following sections:
About Catalogs
The major components of BuyerXpert/SellerXpert Catalog Manager are:
Master catalog ontology
Seller catalogs
Buyer catalogs
Further information on the topics discussed here is contained in the Catalog interface Help.
Master Ontology and Master Catalog
To present product information from different seller catalogs consistently, BuyerXpert/SellerXpert provides a catalog structure called the master ontology. The master ontology consists of a structure made up of product categories that contain product attributes associated with these categories.
The term master catalog refers to the aggregate of all the seller catalogs, with all their product items and details (stored in the master ontology).
Categories
Categories are nodes in the master ontology. Initially, categories are created as part of the process of creating the master ontology. As a rule, a category can have only one parent category, and an item can be held by only one category.
Attributes
Attributes are characteristics of product items. For example, the Pen category would typically have such attributes as Name, Description, Price, Color, Material, and so on. This information is stored under two types of attributes: common and specific. Common attributes are category-wide attributes that are common to all items under a category; specific attributes are attributes that apply only to a specific item.
When you view the product details of all the items in a particular category, you will notice that some information is common to all the items in the category and other information is item-specific. The master ontology enables sellers to provide product information in a combination of common attributes and specific attributes.
Seller Catalogs
In BuyerXpert, the master ontology is owned and maintained by the buyer organization, whereas master catalogs with their product items are owned and managed by individual seller organizations. That is, the seller owns the items in the master catalog. An item can be viewed, edited or deleted only by the organization that added the item to the master catalog, not by other seller organizations. Occasionally the BuyerXpert administrator (superadmin) updates the master catalog on behalf of a seller organization.
Typically, the BuyerXpert administrator (superadmin) maintains the master ontology and the individual seller organizations manage their product items and details.
In SellerXpert, the master catalog and ontology are owned by the seller and only the catalog views belong to the buyer.
Buyer Catalogs
A buyer catalog is a view of a master catalog that selectively shows categories and items in the master catalog. For example, a buyer catalog might contain only office supplies. Or a buyer catalog might be set up to only offer items from a particular seller.
A buyer catalog is created and maintained by the BuyerXpert administrator (orgadmin) who has the privilege to create catalogs for the buyers in that organization. Buyer companies can create remote catalogs in addition to local catalogs.
Catalog Roles
A role is a set of privileges that allows a user to perform certain actions in the BuyerXpert/SellerXpert application. When creating a buyer catalog, the BuyerXpert/SellerXpert administrator selectively associates particular buyer roles with the catalog. This authorizes all the buyers who belong to these roles to browse that buyer catalog. In this way, access to catalogs is limited to specific groups of buyers within the organization.
Typically, in a buyer organization there is a person who is assigned the BuyerXpert/SellerXpert catalog administrator role. This person has privileges to create buyer catalogs and assign user roles to that catalog, thereby granting access.
There are four types of catalog roles:
BuyerXpert/SellerXpert super administrator (superadmin)
-
Has all the privileges in Catalog Manager.
Buyer organization administrator (orgadmin)
BuyerXpert/SellerXpert user
Browses buyer catalogs.
Purchases catalog items.
Seller organization administrator (orgadmin) or user
Adds items to designated catalogs.
Approves items added to the catalogs.
Edits and deletes seller catalog items.
|
Note
|
Organization administrators can create additional roles by making any meaningful combination of the privileges available to the organization, depending upon the business role of the organization.
|
Catalog Privileges
There are two types of catalog privileges: the buyer organization privileges and the seller organization privileges as shown in Table 7-1.
Table 7-1 Catalog Privileges
|
Organization
|
Privilege
|
Capabilities
|
|
Buyer
|
Browse and buy
|
Browsing buyer catalogs
|
|
Performing searches on product items
|
|
Choosing and adding product items to requisitions
|
|
Creating requisitions
|
|
Create
|
Creating buyer catalogs and authorizing buyers to browse the catalogs
|
|
Adding items to and deleting items from buyer catalogs
|
|
Selecting and removing products of specific seller organizations from buyer catalogs
|
|
Seller
|
Browse
|
Browsing catalogs
|
|
Edit seller items
|
Adding product items to master catalog
|
|
Editing and deleting catalog items and item details added to the master catalog by the user's organization
|
Administrator's Catalog Tasks
Creating the master ontology is the first step in implementing a catalog for BuyerXpert/SellerXpert. A collaborative effort between the buyer and seller organizations, creating the master ontology is a one-time event carried out during the initial process of importing the seller catalog(s). Later, the master ontology is maintained by the BuyerXpert administrator (superadmin) using the Catalog interface.
After the master ontology is created, seller catalogs can be added to the master catalog using the Import utility, which maps the items and categories in the seller catalog to those of the master catalog.
After a catalog is imported into BuyerXpert/SellerXpert, buyer organizations are given the ability to create private buyer catalogs from the master catalog.
Occasionally, it may be necessary to add, edit, or delete categories and their attributes. This can be done from the Catalog interface.
|
Note
|
Most instructions for performing the tasks associated with Catalog Manager are contained in the Catalog interface Help.
|
Table 7-2 contains a list of the key tasks required for catalog administration. The right-hand column provides information about where to find instructions, guidelines, or tools for performing that task.
Creating the Master Ontology
Once the master ontology is created, it becomes commonly available to all the seller companies to add their product items to the master catalog. Individual sellers store their items with item details in the master catalog which contains all the seller catalogs. To maintain the order and consistency of the master ontology, the BuyerXpert/SellerXpert superadmin assumes ownership.
Instructions for creating the master ontology are contained in the Catalog interface Help.
Creating a Public Master Catalog
To create a public master catalog for a seller catalog, you need to convert basic tabular data to a seller catalog hierarchy structure. You define this hierarchy structure with the column structure specification desired for the catalog.
The main tasks required to convert a seller catalog to a BuyerXpert/SellerXpert public master catalog are:
Add column hierarchy structure to the seller catalog.
Translate the seller catalog format to the public master catalog XML format.
Load the XML file into the catalog database.
Instructions for creating a public master catalog are contained in the iPlanet Market Maker Catalog Import Guide.
Column Hierarchy
The character separated value (CSV) file defines the seller catalog input information in a tabular text format to be translated to XML format with its column structure hierarchy defined. The seller catalog is then mapped to the public master catalog. For example, here are some entries that define characteristics of pens and pencils:
-
pens~fine_point~black~red~7
-
pens~med_point~black~red~9
-
pencils~number_2~blue~green~9
The "~" character that separates each of the entries is defined in the makefile.
Creating the XML File
For the Import utility to understand the column structure of the tabular input, you need to create an XML column structure specification file that defines the hierarchy structure.
|
Note
|
You can also use the createxml.sh script to create an XML file as described in the section on Importing Catalog Data.
|
The character separate value (CSV) and column structure specification files are the minimum required inputs. Additional input files are either optional, or are generated by the Import utility. The input file formats are contained in Table 7-4 in the Importing Catalog Data section.
Further information and instructions for performing the tasks required are contained in the iPlanet Market Maker Catalog Import Guide.
Loading the XML File
Once you have created your public master catalog XML file, you can load it into the catalog database using the following loader command syntax:
java com.iplanet.ecommerce.vortex.catalog.catimport.Loader options
|
Note
|
You can also use the loadfromxml.sh script to load an XML file as described in the section on Importing Catalog Data.
|
The loader command options are listed in Table 7-3.
Table 7-3 Loader Command Options
|
Option
|
Description
|
|
-USER
|
User name.
|
|
-PASSWORD
|
User password.
|
|
-COMPANYID
|
Company login name of ID of the user running the loader command. If the -VENDORID option is not specified, items are added under this company name or ID.
|
|
-VENDORID
|
Seller identification, typically a company name.
|
|
-LOCALE
|
Specifies an optional locale other than the default. If a locale is specified, format is <language>-<country code>, where the language and country code comply to the ISO 639 standard. For example, the locale for French is fr-FR.
|
|
-IN XML_file_name
|
Name of the load file. The default file name is mm.xml.
|
|
-LOG log_file_name
|
Log file name. Default is the -VENDORID name with a .log extension.
|
|
-ERROR error_file_name
|
Error file name. Default is the -VENDORID name with a .error extension.
|
|
-ITEM item_number
|
Optional item number to begin processing. Default item number is 0.
|
|
-ontology
|
Creates a new ontology. This option is used by the BuyerXpert/SellerXpert superadmin only when creating a new ontology, such as when creating a catalog database for the first time. It should be used carefully. This option allows the loader to make ontology changes by adding new categories in the public master catalog. Default is Off.
|
|
-THREADS
|
Specifies the number of threads. Default is 10.
|
|
-MAXITEMBATCHSIZE
|
Specifies the number of items in a category that can be processed in a transaction batch. The default is the number of items in a category as specified in the public master catalog XML file.
|
|
-D vortex_debugLevel
|
Specifies a Java property that can have the following values:
0 = No debugging output
3 = Exceptions output
7 = Sql statements in output
|
|
-mv
|
Loads a multi-vendor catalog. Each item in the XML file must have a seller ID attribute that has a value of the ID of a valid seller organization in the membership database. This option is used by the BuyerXpert/SellerXpert superadmin.
|
Resolving Catalog Hierarchy Issues
Because XML has strong support for hierarchies, the Import utility uses XML syntax to represent the hierarchical structure of the seller and public master catalogs. This means that name and path clashes might occur in the categories in your catalog.
Name/path clashes occur in two cases:
Name clashes—Occur when categories have the same names except for special characters that are not allowed in the XML name token.
Path clashes—Occur when categories have the same name, but their child categories have different names.
If there are name clashes in your hierarchy, you must resolve them before a public master catalog can be created. Further information and instructions for performing the tasks required are contained in the Catalog interface Help.
Managing Categories and Attributes
As the superadmin, you can create new categories and edit and delete existing categories from the master ontology. Attributes can be updated at the same time.
|
Note
|
For the most part, sellers add their own attributes to product items.
|
Creating a New Category
You may need to create a category and attributes to meet the requirement of one seller company or another. If you are only creating a few categories, it may be more efficient to use the Catalog interface, rather than the Import utility.
Typical reasons for creating new categories include:
Further information and instructions for performing the tasks required are contained in the Catalog interface Help.
Editing a Category
Editing a category allows you to:
Make changes to the category name
Delete an additional search attribute
Add more search attributes with initial values
Further information and instructions for performing the tasks required are contained in the Catalog interface Help.
Deleting a New Category
Deleting a category should be done only after careful consideration, because it results in deleting all the categories down the hierarchy as well. Deleting a category is possible only if there are no items under that category or under any of the categories down the hierarchy.
Further information and instructions for performing the tasks required are contained in the Catalog interface Help.
Managing Buyer Catalogs
As the BuyerXpert administrator, you can create, edit, or delete buyer catalogs for your organization.
While creating a buyer catalog, the buyer administrator adds the existing buyer roles to that catalog as catalog roles. Buyers in an organization can browse their organization's buyer catalogs if the following are true:
Creating a Buyer Catalog
Generally, the BuyerXpert administrator (orgadmin) creates a buyer catalog for one of the following reasons:
So buyers in that organization can purchase items which belong to selected categories only (the other items in the master catalog do not display).
So buyers in that organization can purchase items supplied by selected seller companies only (items for other sellers do not display).
You can create separate catalogs for many groups of buyers in the organization. For example, a catalog for office supplies can be created for a group of buyers who are authorized to purchase office supplies. Another catalog containing high value items can be created for the group of buyers authorized to purchase capital goods. This way, a buyer catalog can be created for an individual group, with access to that catalog limited to the people in that group.
Creating a catalog includes four major tasks:
Give a name and description to the catalog.
Select seller companies whose products you want to have included in your catalog.
Add categories and items to the catalog.
Add roles to the catalog.
Further information and instructions for performing the tasks required are contained in the Catalog interface Help.
Editing a Buyer Catalog
As BuyerXpert administrator, you can edit the buyer catalogs created for your organization. Editing a buyer catalog allows you to:
Include or exclude products supplied by a particular seller organization from the buyer catalog.
Include or exclude items or categories from the buyer catalog.
Add user roles to or remove roles from a buyer catalog to allow or deny access to a group of buyers.
Change the name and description of the catalog in such cases where there is substantial change in the content of the buyer catalog.
Select or deselect the option to dynamically update the items in the buyer catalog.
Further information and instructions for performing the tasks required are contained in the Catalog interface Help.
Deleting a Buyer Catalog
Buyer catalogs are owned by the buyer companies. A BuyerXpert administrator can delete the buyer catalog created for his/her company. The BuyerXpert/SellerXpert superadmin can delete catalogs owned by any company.
A typical reason for deleting a buyer catalog is the case where deleting and creating a new version of the catalog is more efficient than editing the existing catalog.
|
Note
|
Deleting a buyer catalog does not affect the categories and items in the master catalog or other buyer catalogs.
|
Further information and instructions for performing the tasks required are contained in the Catalog interface Help.
Importing Catalog Data
The Catalog Manager Import utility is a batch process that you can use to import catalog data offline. Full instructions on using the Catalog Manager import utility are contained in the iPlanet Market Maker Catalog Import Guide.
The following sections describe the overall process and the scripts used for BuyerXpert/SellerXpert:
Files and Parameters
Before you run the Import utility, you must specify your input files in a makefile.
|
Note
|
You can also use thecreatexml.sh script to create an XML file as described at the end of this section.
|
Table 7-4 lists the default input files.
Table 7-4 Import Utility Input Files
|
Default File Name
|
Description
|
|
User defined, no default
|
CSV input file
|
|
css.xml
|
Column structure specification file
|
|
User defined, no default
|
Names file
|
|
User defined, no default
|
Paths file
|
|
vendor.xml
|
Seller catalog with column hierarchy structure defined
|
|
omd.xml
|
Ontology map definition file
|
|
mm.xml
|
Output of the Import utility to be loaded in a public master catalog
|
|
mm.dtd
|
Public master catalog document type definition (DTD) file
|
To control the output of the Import utility, you can set a number of run-time parameters in the makefile to determine what information the Import utility creates or updates. Table 7-5 lists these parameters.
Table 7-5 Import Utility Run-Time Parameters
|
Run-Time Parameter
|
Description
|
|
ALL
|
Creates or updates the following files:
- Ontology definition
- Document type definition
- Public master catalog
|
|
CATALOG
|
Creates or updates the public master catalog.
|
|
ONTOLOGY_MAP
|
Creates or updates the ontology definition file.
|
|
DTD
|
Creates or updates the document type definition file.
|
|
CHECK
|
Checks for both name and path clash problems.
|
|
CLEAN
|
Creates or updates the name and path clash reports.
|
|
CLOBBER
|
Removes all files except the source input files, column structure specification file, ontology map definition, and the names and path files.
|
Scripts
The following scripts should always be run from the working directory:
createxml.sh script
loadfromxml.sh script
Using the createxml Script
You can use the createxml.sh script to convert a seller catalog in character separated values (CSV) format to XML format. After all the input files are in the working directory, run the createxml script using the following syntax:
createxml.sh -csv csv_file_name -css css_file_name [options]
Options can be listed in any order. All optional files should be in the working directory
Table 7-6 createxml Script Parameters
|
Parameters
|
Description
|
|
-csv
|
Character separated value file name.
|
|
-css
|
Column structure specification file name.
|
|
Option
|
Description
|
|
-encoding
|
US-ASCII/ISO-8859-1/UTF-8/UTF-16BE/UTF-16LE/UTF-16/DEFAULT. For encoding rules, refer to http://java.sun.com/products/jdk/1.2/docs/guide/internat/encding.doc.html
|
|
-names
|
Name of the file to resolve name clashes.
|
|
-paths
|
Name of the file to resolve path clashes.
|
|
-units
|
Name of the XML file for performing attribute unit normalization.
|
|
-map
|
Name of the XML file for performing attribute name normalization.
|
|
-attr
|
Name of the XML file for specifying attribute types.
|
|
-char
|
Separator charactor in csv file. Default is ~ (tilde).
|
|
-skip
|
Number of header lines to skip in csv file. Default is 0.
|
|
-check
|
Checks for name and path clashes
|
|
-v
|
Verbose
|
Examples
#IAS_ROOT/buyer/bin/catalog/createxml.sh -csv sun_data.csf -css sun_css.xml -attr
attr-type.xml -skip 1 -char ','
#IAS_ROOT/buyer/bin/catalog/createxml.sh -csv sun_data.csf -css sun_css.xml -attr
attr-type.xml -map attr-renaming.xml -skip 1
#IAS_ROOT/buyer/bin/catalog/createxml.sh -csv xyz.csf -css css.xml -attr
attr-type.xml -skip 1 -check
#IAS_ROOT/buyer/bin/catalog/createxml.sh -csv xyz.csf -css css.xml -attr
attr-type.xml -names n_clashes.xml
#IAS_ROOT/buyer/bin/catalog/createxml.sh -csv sun_data.csf -css sun_css.xml
-units units-map.xml
Using the loadfromxml.sh Script
A wrapper loadfromxml.sh script is provided to call the Loader.class. Syntax:
loadfromxml.sh <inputs> [options]
The loadfromxml.sh script inputs and options are listed in Table 7-7.
Table 7-7 loadfromxml.sh Script Parameters
|
Input
|
Description
|
|
-usr
|
User name.
|
|
-passwd
|
User password.
|
|
-cid
|
Company ID of the user.
|
|
-xml
|
XML file name to load.
|
|
Option
|
Description
|
|
-vid
|
Vendor ID of the dataset owner.
|
|
-log
|
Log file name. If this option is not specified, the VendorID is used as the file name, appended by the .log extension.
|
|
-err
|
Error file name. If this option is not specified, the VendorID is used as the file name, appended by the .err extension.
|
|
-item
|
Start item. Default is 0.
|
|
-ontology
|
Superadmin creates a new ontology. Allows for ontology changes by adding categories. Use carefully. Default is Off.
|
|
-threads
|
Number of insert threads. Default 10.
Note: When the load size is less than 10,000 items, specifying -threads 5 may give better performance.
|
|
-batchsize
|
Number of items in a category to process in a transaction.
|
|
-approve
|
Approves loaded items.
|
|
-mv
|
Loads a multi-vendor catalog.
|
|
-locale
|
Locale information. Default is en-US. If a locale is specified, format is <language>-<country code>, where the language and country code comply to the ISO 639 standard. For example, the locale for French is fr-FR.
|
Example
#IAS_ROOT/buyer/bin/catalog/loadfromxml.sh -usr admin -passwd admin -cid staples
-xml toys.xml
#IAS_ROOT/buyer/bin/catalog/loadfromxml.sh -usr admin -passwd admin -cid
mercury.com -xml some.xml -vid staples
#IAS_ROOT/buyer/bin/catalog/loadfromxml.sh -usr admin -passwd admin -cid
mercury.com -xml multivendor.xml -approve -mv
#IAS_ROOT/buyer/bin/catalog/loadfromxml.sh -usr admin -passwd admin -cid
mercury.com -xml toys.xml -ontology