Retrieving Item Specifics Meta-Data

This section discusses the means and strategies for retrieving Item Specifics that have been defined for the categories on a particular eBay site. Specifically, it focuses on retrieving Item Specifics in the format that would be used when a seller is listing an item the standard way.

Many categories support listing the standard way with Item Specifics. As each eBay site has its own category hierarchy, the exact combination of Item Specifics that are available and the kinds of categories that support this feature can vary for different sites. Furthermore, the Item Specifics meta-data for any given category can be updated without notice.

When you are listing an item the standard way, you determine the Item Specifics for a given category by using GetAttributesCSCall. This call gives you a dynamic and scalable way to import, update, and render Item Specifics meta-data for any category in an application. You should not hard-code Item Specifics meta-data in your application.

The Attributes Library includes a sample data-source provider class called AttributesXmlDownloader, which executes GetAttributesCSCall 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).

GetAttributesCSCall returns the Item Specifics XML for one or more categories in a single AttributeData 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). Describing Item Specifics as a raw XML string makes it possible to use eBay's Item Specifics SYI XSL stylesheet to render the data in a graphical user interface.

Only use GetAttributesCSCall to retrieve Item Specifics when you are listing an item the standard way. That is, do not use it when you are creating a listing with Pre-filled Item Information.

This section describes the following process:

Prerequisites

Step 1:  Indicate the Characteristic Set Data to Return

Step 2:  Make the API Call

Step 3:  Store the Item Specifics Data for Future Use

Step 4:  Maintain the Item Specifics XML

Step 5:  Note: Next Steps

Prerequisites

Make sure your locally cached category-to-characteristics data is up to date (see Retrieving Category-to-Meta-Data Mappings).

Although you do not necessarily have to specify a characteristic set in order to execute GetAttributesCSCall or a data-source provider class that implements IAttributesXmlProvider, you will need to know the correct mappings for each category in order to determine which set of Item Specifics to use later during the listing process.

Step 1: Indicate the Characteristic Set Data to Return

As the attribute meta-data contains a large volume of data, you should retrieve and store all the data once and then retrieve only the information that changes. This is similar to the process you use to retrieve and store the category-to-characteristic set mappings. If you are using the Attributes Library, the same principle applies when working with classes that implement IAttributesXmlProvider, such as the AttributesXmlDownloader class.

The first time you execute GetAttributesCSCall or the AttributesXmlDownloader class, you should retrieve all the available meta-data for the site's current category hierarchy.

Optionally, if you want to be able to use a category ID to auto-fill certain attributes, set the IncludeCategoryMappingDetails flag to true. This causes the response to include a list of categories along with attributes and values that your application can auto-fill for items listed in those categories. This feature is primarily useful for sellers who want to use a listing's category ID to auto-fill attributes on the client side (instead of allowing eBay to do this on the server when the item is listed). (This functionality is not available by default in the current version of the eBay SDK for Java. See GetAttributesCSCall Input Fields for information on adding this feature.)

After initially obtaining the meta-data, in subsequent calls use the locally saved version of the data in the AttributeSystemVersion filter to check whether the version has changed. If it has, use the version information to get changes that have been made to the mappings.

Optionally, use the AttributeSetID property as a filter to limit the results to a specific characteristic set. If not specified, then the meta-data for all attribute-enabled categories is returned. To determine the available characteristic set IDs, execute GetCategory2CSCall or use your data-source provider class to look up the IDs in the mapping data that you have stored locally.

See GetAttributesCS for information on the best ways to use data filters like AttributeSystemVersion, AttributeSetID, and DetailLevel.

You can expect the meta-data to be updated at least once or twice a month, but it may sometimes be updated more frequently than this interval. Use GetAttributesCSCall or your data-source provider class to check the version at least once a day, and then retrieve any changes to the meta-data if the version has changed.

The call-specific properties are also described in GetAttributes Input Fields.

When you use the Attributes Library to retrieve Item Specifics, 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 19-3 Setting up a Characteristic Set Data-Source Provider 

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

Step 2: Make the API Call

Making the API call with the Attributes Library entails invoking the AttributesXmlDownloader.downloadXml( ) method, which parses the returned 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 getAttributesCS( ) method defined on the GetAttributesCSCall class to retrieve the XML string. In the example below, the axd variable holds the data-source provider. The data-source provider is then set on the AttributesMaster object to be retrieved later during the listing flow.  

Example 19-4 Making the API Call 

axd.downloadXml(apiContext);    amst.setXmlProvider(axd); } // Catch and handle errors, displaying appropriate messages for the end-user // See Error Handling for information about handling infrastructure errors

Note: GetAttributesCSCall returns a string that specifies the Item Specifics XML for the characteristic sets that you requested. Your data-source provider class should parse this string to create a Document object. See the AttributesXmlDownloader class for an example of how to do this.

See GetAttributesCS and The Attribute Meta-Data Model for information about the data that is returned.

See the generated library reference documentation for GetAttributesCSCall and AttributesXmlDownloader for additional fields and methods that you can use to access and manipulate the retrieved data.

An application uses the characteristics meta-data to determine the Item Specifics or return policy options that are available in the corresponding categories.

Depending on your application's workflow, you can use the meta-data along with the Item Specifics SYI XSL stylesheet to render Item Specifics or return policy options in your application's user interface, from which the user can select the attributes to include in their listing.

Optionally, if you set IncludeCategoryMappingDetails flag to true in the request, use the category mappings returned in the response (if any) to auto-fill Item Specifics based on the category. See Auto-filling Attribute Values Based on a Listing's Category for information on how to use the Item Specifics SYI XSL stylesheet to present this data to the seller.

GetAttributesCSCall also returns the version of the complete list of mappings. The next time you execute this call, use the version information as a filter to retrieve only the data that has changed.

Step 3: Store the Item Specifics Data for Future Use

Once you have retrieved the Item Specifics meta-data, you can use the same meta-data for all listings for the rest of the day. You should not need to retrieve the meta-data again for at least 24 hours.

If you retrieved all the characteristic set data (with no AttributeSetID filter), store the version information so that you can use it as input the next time you execute the call.

Store the attribute meta-data string returned in the AttributeData object (e.g., to a database table). If you plan to use the Item Specifics XSL to render the data, see Storing the XML for Use with the Stylesheet for additional steps that you should take when storing the XML.

Archiving Previous Versions of the Item Specifics Meta-Data

Some applications overwrite their locally stored meta-data each time they retrieve the latest version of the data. Other applications save the meta-data that was in effect whenever a user created a listing with Item Specifics. The approach you use depends on the features your application provides.

The Item Specifics meta-data for any given category can change periodically as the needs of the eBay community change. Here are some situations to consider as you develop your application:

Revising items with Item Specifics

Once an item has been listed with Item Specifics (using AddItemCall), the seller's selections will not be modified in the existing listing if the meta-data on the site changes. If you decide to modify a listing's Item Specifics when you revise the item (using ReviseItemCall), you will need to use Item Specifics that are consistent with the meta-data that was in effect when the item was originally listed. If you have listed an item with Item Specifics, it may be helpful to save the meta-data that was in effect at the time so that you can use it later to update the existing listing. See Revising Items with Item Specifics (Attributes) for additional information.

Relisting items with Item Specifics

When you relist an item, it is validated is if it were a new item, so the Item Specifics need to be consistent with the latest meta-data on the site. In some cases, you may receive a warning that Item Specifics have changed. In other cases, an error may be returned if some Item Specifics are no longer valid or new Item Specifics have become required for the category. It may be helpful to give the seller the option to compare the listing's original Item Specifics to the latest meta-data that is available so that they can decide whether or not to update the information to add new Item Specifics that were not previously available. See Relisting Items with Item Specifics (Attributes) for additional information.

Retrieving existing listings with Item Specifics

Similarly, using the original meta-data could be helpful if you want to render literal attribute names after retrieving the Item Specifics using GetItemCall (because GetItemCall only returns attribute IDs, not the names of the attributes). If the listing contains attributes that are no longer available now, you might not be able to determine the attribute names based on the latest version of the meta-data.

Creating pending or scheduled listings

The Item Specifics meta-data for a given category can change without notice. If your application supports creating listings with Item Specifics and then scheduling the listings to become active on the site at a later date (often called pending or scheduled listings), it is likely that you will cache the Item Specifics the user selected as part of the item you will submit. In this case, you need to make sure the item's attributes will be valid when the listing becomes active.

The easiest way to make sure the attributes will be valid is to use eBay's scheduled listing functionality instead of caching the configured item locally. With this feature, you submit the listing with Item Specifics at the time the user originally defines the listing, but the listing does not become active until a later date that you specify in the listing request. The validation of the Item Specifics occurs when the listing is submitted, not when it becomes active.

If you prefer to manage scheduled listings locally, it may be useful to save the meta-data that is in effect any time you originally create a listing with Item Specifics. Then, before you submit the listing, compare its meta-data to the latest meta-data to determine whether anything has changed. At a minimum, compare the selected attributes to the latest meta-data to make sure the selected attributes are still valid. See Creating Listings Before the Listing Start Date for more information.

Step 4: Maintain the Item Specifics XML

At the beginning of each day that the user will create or submit listings with Item Specifics, retrieve any updates that have been made to the meta-data.

Step 5: Note: Next Steps

Once you have retrieved the Item Specifics meta-data, you may also need to update your locally stored Item Specifics XSL stylesheet. See Retrieving the Item Specifics SYI XSL Stylesheet.

Use the Item Specifics XML when a seller wants to list the standard way with Item Specifics. See Listing with Item Specifics and Catalog Data.