Retrieving a Product's Item Specifics

On the eBay Web site, the user selects a product by clicking a Sell One Like This button on the search results page (or on the page that lists all products in one particular family). The eBay site then displays the Title & Description page. Many of the Item Specifics are pre-filled based on the product the user selected. A few attributes that are expected to vary or that do not yet have pre-filled values may still be editable.

Figure 21-6 Pre-filled Item Specifics on an eBay Web Site

Use GetProductSellingPagesCall to retrieve stock information about a product, including Item Specifics. The data lets you render the equivalent of the Item Specifics portion of the Title & Description page. This call gives you a dynamic and scalable way to import, update, and render pre-filled and editable Item Specifics for a catalog product. You should not hard-code product meta-data in your application. The Attributes Library includes a sample data-source provider class called AttributesXmlDownloader, which executes GetProductSellingPagesCall for you and handles other common functionality that you need when working with Item Specifics. This class implements the IAttributesXmlProvider interface and caches the data in memory. If you want to use the Attributes Library, you can use the sample downloader class or you can create your own implementation of the IAttributesXmlProvider interface that stores the data in a different way (such as in a database).

If you choose to use the AttributesXmlDownloader class as your XML data-source provider, you can skip reading this section. The information in this section is mainly applicable if you need are creating your own data-source provider and you need to execute GetProductSellingPagesCall directly to retrieve product information.

GetProductSellingPagesCall returns the product Item Specifics XML for one or more products in a single ProductSellingPagesData object as a string. The attributes and values are not defined in the WSDL (i.e., there are no code lists that describe the meta-data), and therefore they will not be converted into objects or modules by your SOAP client. If you are using the Attributes Library, your data-source provider class should parse the XML string to create a Document object. See the AttributesXmlDownloader class for an example of how to do this.

The input to GetProductSellingPagesCall or your data-source provider comes from GetProductSearchResultsCall (or GetProductFamilyMembersCall). You use the response as input to calls related to adding, revising, and relisting items (the AddItem family of calls).

GetProductSellingPagesCall returns the same characteristics meta-data as GetAttributesCSCall, with these differences:

The data is returned as a string in the ProductSellingPagesData property (instead of AttributeData).
In the XML string, the data for each selling page is embedded in a Product container node that contains additional information about the product (e.g., the stock photo URL).
The meta-data (Characteristics container) still includes all possible values for Type 0 and Type 2 attributes (even if the Type 2 attributes are pre-filled), but the default values (AttributeSet container) specifies default and pre-filled values for the attributes.

You can use the Item Specifics SYI XSL stylesheet to render the XML returned from GetProductSellingPagesCall. See Working with Attribute XSL Stylesheets. If you are using the Attributes Library, the AttributesMaster class provides helper methods that you can use to render the XML and get the attributes that the user selects. In this case, you do not need to write code to handle the stylesheet yourself. If you provide your own implementation of the AttributesMaster class, you will need to understand how to work with the XSL stylesheet.

If you choose not to use the XSL stylesheet, or if your application design requires you to understand the details of the product selling page meta-data, see Attribute and Product Finder Content Models for additional information about the XML returned in the ProductSellingPagesData property.

This section describes the following process:

Prerequisites

Step 1:  Indicate the Product Data to Return

Step 2:  Make the API Call

Step 3:  Maintain the Product XML

Step 4:  Next Steps

Prerequisites

You need a current product ID to pass as input to this call. Typically, you get the product ID as a result of executing GetProductSearchResultsCall or GetProductFamilyMembersCall. In some cases, the product ID might be returned as a result of executing AddItemCall (see Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID)).

Step 1: Indicate the Product Data to Return

GetProductSellingPagesCall lets you retrieve information about multiple products (i.e., the call supports batch requests). This may be useful for users who are listing several different items at the same time. If you use a data-source provider like the AttributesXmlDownloader class instead, you can design the getMultipleCSXmlText( ) method to retrieve data for multiple products as well.

When creating the GetProductSellingPagesCall request, set the Products property. For each product, specify the ID of the product whose stock information you are retrieving. Also specify the characteristic set and its version value.

If you use a data-source provider class like AttributesXmlDownloader instead of using GetProductSellingPagesCall directly, the Attributes Library includes a wrapper interface called IAttributeSet.This extends the AttributeSetType object and adds functionality to handle catalog product data as part of the same object. To specify that you want to retrieve product data rather than standard Item Specifics, set IAttributeSet.ProductID to the product ID the user selected. Then pass in the array of IAttributeSet objects as an argument to the getMultipleCSXmlText( ) method.

In addition, you need to specify the context in which the call is being executed—selling, revising, or re-listing. This will imply certain server-side validation rules when eBay processes the request. Set the UseCase property on GetProductSellingPagesCall to make sure you retrieve the appropriate version of product information and attribute meta-data when you are listing, revising, or re-listing an item with Pre-filled Item Information. The ProductUseCase code list defines the possible use cases:

Use the AddItem code when you are executing this call before adding an item. This causes the response to return the latest product ID, attribute meta-data, and stock information for the product. This is important in case the product ID has changed since you originally retrieved it.
Use the ReviseItem code before revising an item. This causes the response to return the product ID, attribute data, and other data that is (or was) associated with the version of the product you passed in. This is useful in case the product ID or associated data has changed in the system since the item was originally listed. When revising an item, this helps you make changes that are consistent with the original listing.
Use the RelistItem code before re-listing an item. This causes the response to include the latest product ID and other information in the system. When you re-list an item, you need to use the latest version of the product and related meta-data.

GetProductSellingPages summarizes the main input fields that are applicable for this call.

When you use the Attributes Library to retrieve a product's Item Specifics and related information, you create an instance of the AttributesMaster class and configure it to use a data-source provider, such as the AttributesXmlDownloader class. The example below shows creating the master class and the data-source provider.

Example 21-4 Setting up a Characteristic Set Data-Source Provider 

try {    AttributesMaster        amst        = new AttributesMaster();    AttributesXmlDownloader axd = new AttributesXmlDownloader(apiContext);    amst.setXmlProvider(axd);

Step 2: Make the API Call

Making the API call with the Attributes Library entails specifying the product you want to retrieve by setting IAttributeSet.ProductId to the product ID the user selected. Then pass in the array of IAttributeSet objects as an argument to the getMultipleCSXmlText( ) method on the data-source provider that implements the IAttributesXmlDownloader interface. This retrieves the product data as an XML string and creates an org.w3c.dom.Document object that is easier to work with. If you create your own data-source provider class that implements the IAttributesXmlProvider interface, your class would call the getProductSellingPages( ) method defined on the GetProductSellingPagesCall class to retrieve the XML string.In this example, the PRODUCT_ID variable specifies the ID of the product the seller selected, and the SEL_CATS variable contains the list of categories the seller selected. Although Pre-filled Item Information can be associated with only one category for a given listing, you can download product data for multiple products in a single call. The first time the code is executed, we use the Attributes Master to render the product data. As the user makes their selections, the HTML form might generate POST data, in which case we use the Attributes Master to refresh the page with the current data. Once the user submits their selections, the Attributes Master object validates their selections (see Validating Attribute Data Before Listing Items) and render any errors that are found. If no errors are found, we use the Attributes Master to collect the selected attributes and convert them to an AttributeSet that can be set on an Item object.

Example 21-5 Making the API Call 

String tableText = "", prodID = "";    Object obj = PRODUCT_ID;    if( obj != null )       prodID = (String)obj;

if (...) // Test for first-time execution.    {       CategoryType[] selCats = (CategoryType[])session.getAttribute(SEL_CATS);       int[] ids = new int[selCats.length];       for(int i = 0; i < selCats.length; i++ )          ids[i] = Integer.parseInt(selCats[i].getCategoryID());

if( prodID.length() > 0 )       {          AttributeSet[] sets = attrMaster.convertCategoriesToAttributeSets(ids);          sets[0].setProductID(prodID);          tableText = attrMaster.renderHtml(sets, null);       }

else       {          tableText = attrMaster.renderHtmlForCategories(ids, null);       }

else if(...) // Test whether the user has selected attributes and a refresh is needed    {       // Render the attributes the user has selected so far       tableText = attrMaster.renderHtmlForPostback(request.getParameterMap(), null);    }    else // Process the data the user submitted    {       AttributeSet[] sets = attrMaster.nameValuesToAttributeSets(                                 request.getParameterMap());       ErrorSet[] errList = attrMaster.validate(sets);

// If there are no errors, gather the selected attributes.       // Otherwise, render the errors.       if( errList == null || errList.length == 0 )       {          // Collect the attribute sets       }       else          tableText = attrMaster.renderHtmlForPostback(request.getParameterMap(), errList);       }       return tableText;    } } // Catch and handle errors, displaying appropriate messages for the end-user // See Error Handling for information about handling infrastructure errors

GetProductSellingPagesCall returns a ProductSellingPagesData object containing a string that specifies the product and Item Specifics XML for each product ID that you requested. The data is returned as raw XML so that you can more easily apply the Item Specifics XSL to render it.

Table 21-1 GetProductSellingPagesCall Return Fields 

Return Fields	Type/Code List	Purpose
ProductSellingPagesData	string	An XML string containing one or more product definitions (one for each product ID requested) along with related meta-data. Use the getProductSellingPages( ) method to retrieve this data. If you are using the Attributes Library, the AttributesXmlDownloader class demonstrates one way to parse this string to create a Document object that is easier to work with. For each product, the XML specifies the pre-filled values of each attribute, the possible values of attributes that are not pre-filled, the logic for presenting the attributes to a user, and rules for validating the user's selections. The meta-data format is based on the format of the AttributeData string returned by GetAttributesCSCall. Product and attribute information is nested within a set of Product tags. The product-specific data is merged into the attribute data so that the same XSL stylesheet can render both standard Item Specifics and pre-filled Item Specifics.

For each product, the raw XML contains a ProductInfo node that contains a URL for the product's stock photo, a URL for linking to a preview of the Pre-filled Item Information, and copyright content that your application should present to users (see Figure 21-6). This represents the product information that can be included in the listing. (In your application, you should give the user options to include the stock photo in the listing, to use the stock photo as the Gallery image, and to include Pre-filled Item Information in the listing.)

The XML also specifies the set of attributes and characteristics (Item Specifics) that are applicable for the product. That is, if the product is a DVD, the call would return the DVDs attribute meta-data and appropriate default attributes and values. For example, if the selected movie product is a comedy, the AttributeSet node would specify the default value for the Genre attribute as "Comedy" and it would specify the catalog system as the source of the value (AttributeSet.Attribute.source = "1").

The XML format of the Item Specifics portion of the response is consistent with the format of the response returned from calls to GetAttributesCSCall (although the data may be different, due to the pre-filled information). This means an application with a graphical user interface can use a stylesheet returned from GetAttributesXSLCall or a data-source provider that implements IAttributesXslProvider to render this part of the content. See Working with Attribute XSL Stylesheets.

If you are not using the XSL, attribute values that can be selected or overridden by the user should be presented as editable, in the same manner as any Type 0 or selectable (i.e., not pre-filled) Type 2 characteristics (see Determining Whether the User Can Choose an Attribute Value). For example, a movie's Condition attribute is never read-only, but if the Genre attribute is pre-filled by the catalog, it might be considered read-only (because the same movie might always be considered a comedy, no matter who the seller is). Some product attribute values that pre-filled by the catalog may still be overridable. For example, if a particular model of a laptop normally comes with a certain amount of memory, but the user has added more memory, the user should be able to override the value.

You can store the response XML in order to present the product information to the seller so that they can review and confirm the product, choose optional Item Specifics, and choose to include the stock photo and other information. However, in general you should assume that a product 's definition in the catalog can change periodically.

For each product, the call returns one full characteristic set and (for certain eBay sites) zero or more site-wide characteristic sets. The XML structure is the same for each, but site-wide characteristic sets also specify an additional type XML attribute to indicate that they are site-wide. You can use the Item Specifics SYI XSL stylesheet to render the site-wide characteristics alongside the category-specific characteristics.

Step 3: Maintain the Product XML

As each product you retrieve is only applicable for one particular kind of item, you cannot reuse the same product information when listing other types of items. Also, product IDs can change periodically. Therefore, it is often not practical to reuse the same GetProductSellingPagesCall response for listings that are created on different days.

GetProductSellingPagesCall also does not support versioning. For example, you cannot specify the version of a product to find out if the data has changed since you last retrieved that product.

You should retrieve the latest product data each time you need to list a new product. If you frequently list the same type of product, you can try to use the same product ID in the AddItemCall request for each subsequent identical item. If the product ID changes, the AddItemCall request will return an error indicating that the product ID is not valid. In that case, you would need to determine the correct product ID and then retrieve the product again to retrieve the latest product details.

Step 4: Next Steps

After you have retrieved the product details and the user has chosen optional Item Specifics and other information, you can use the selected data in a listing. See Listing with Item Specifics and Catalog Data.