We recommend using XML feeds to share product catalog data with Bazaarvoice because XML is flexible enough to allow for inclusion of as many custom attributes as desired, while also structured enough to provide efficient approaches to modifications and troubleshooting.

Create an XML product catalog feed

If you choose to provide your catalog to Bazaarvoice in an XML feed, which is the recommended method, a well-formed product feed is critical for success. The following example shows the general structure of a simplified XML product feed:

<?xml version="1.0" encoding="UTF-8"?> 
    <Feed>
    <Brands>
        <Brand>...</Brand>
        ...
    </Brands>
    <Categories>
        <Category>...</Category>
        ...
    </Categories>
    <Products>
        <Product>...</Product>
        ...
    </Products>
    </Feed>

Complete the steps in this section to create an XML feed and upload it to Bazaarvoice.

Quick start steps

This section provides the quick start steps for creating your product feed. Refer to other sections of this topic for detailed information on how to create and validate product feed.

  1. Create or update the product XML feed as described by the XML schema . You can use the Product Feed Generator as a starting point for creating your product feed.

    Each product in the feed must include these properties:

    • Brand
    • Product ID
    • Product name
    • Product URL
    • Image URL
    • EAN, UPC, or MPN
    Note: The product ID is defined within the div tag where the data-bv-show attribute appears on your product page. If your current implementation uses the scout file (bvapi.js), you can set the product ID in the $BV.ui configure call on your product page. In the product feed, you must specify the value of the product ID in ExternalId.

    Within Bazaarvoice, ExternalId is especially important. Without it, product matching across features cannot occur. Product ID is also used in submission form links (productId) and in the integration code on product display pages (PDPs), and it is used by sku in BV Pixel transactions.

    Refer to this XML feed example if necessary.

  2. Validate the XML feed against the schema using this validation tool .
  3. Upload feed to the Bazaarvoice staging or production SFTP server, in /import-inbox. Feeds are processed in a daily queue at 2 AM Central Time (CST: UTC-6 or CDT: UTC-5) and are placed in the /backup folder.
  4. Check the results from your staging or production server Workbench.
Note: If you want to provide catalog data to Bazaarvoice using multiple sources, it is recommended to provide the majority of catalog data using an XML feed, and then use a text feed to provide supplemental data.

Step 1: Create an XML feed file

How you generate a feed depends on your system and processes. Regardless of your situation, every feed must be an XML file and follow the same structure.

Get started structuring your product feed by referring to the following:

  • Product Feed Generator, which provides a starting point for creating your product feed

  • Product feed XML schema , which defines the structure and contents of the feed.

    Note: Version 14.3+ of the schema does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored. You can find the complete syntax for all globally unique identifiers in this sample file.

Bazaarvoice recommends the following best practices when you create a product feed:

  • Ensure that the first line of your feed adheres to the following format:
    <?xml version="1.0" encoding="utf-8"?>
  • The standard character-encoding scheme, such as UTF-8 or Windows-1252, must match the scheme that you use for any special characters in the feed.
  • If you do not have a value for a particular field, omit the field from your feed. Do not include the field with a blank value.

Refer to the example below to see an XML feed that includes multiple products.

Step 2: Check the elements and attributes

You must use the appropriate elements and attributes to describe the feed, brand, category, and product information. Refer to the following tables for child elements and attributes for the <Feed>, <Brands>, <Categories>, and <Products> elements.

Note: If an element is not required but you maintain it for your products, include it in the feed.

Feed element

This element is required. The following table identifies required attributes for the <Feed> element.

Attribute Description
name The short version of your Bazaarvoice client name.
extractDate A timestamp that should be populated automatically in the XML DateTime format .
incremental Whether the feed includes all catalog data. If you are uploading a data feed that contains your entire product catalog, set this value to false.
supplemental Whether the feed contains supplemental catalog data. This feed type should be used only when providing multiple catalog sources.
xmlns Schema reference. Set this value to http://www.bazaarvoice.com/xs/PRR/ProductFeed/15.1. 
<Feed xmlns="http://www.bazaarvoice.com/xs/PRR/ProductFeed/15.1" 
      name="ExampleClient" incremental="false" 
      extractDate="2016-01-18T12:00:00">

Brands element

You can declare all product brands in the <Brands> element using these child elements:

Element Value
Brand

Represents a a product brand in your feed and must contain the following <ExternalId> and <Name> or <Names> child elements.

You can include the removed="true" attribute in the <Brand> element to mark the brand inactive.
ExternalId

Unique brand ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If a brand ID contains an invalid character, replace it with an alternate character, such as an underscore. This format is used in the data feed only and does not affect end users. The ID is case insensitive, so you cannot use IDs that match except for case.

Ensure the ID is a stable ID that will not change for the same logical brand, even if the name of the brand changes.
Name or Names Name of the brand, which is visible to end users.

If specifying localized brand names in a multilingual implementation, include a <Name> element for each locale in a parent <Names> element, and then specify the locale attribute (of type String) for each <Name> child element.

Then, when defining products in the <Products> element, you can use the <BrandExternalId> element to reference a brand's ID in the <Brands> element.

Note: Another way to declare brands in your catalog is to use the <Brand> child element in the <Product> element. You can use this method instead of using the <Brands> element as described here.
<Brands>
   <Brand>
      <ExternalId>AAA</ExternalId>
      <Name>First Brand</Name>
   </Brand>
   <Brand>
      <ExternalId>BBB</ExternalId>
      <!-- Default brand name -->
      <Name>Second Brand</Name>
      <!-- Localized brand names -->
      <Names>
         <Name locale="en_CA">Second Brand CA</Name>
         <Name locale="fr_CA">Deuxième marque CA</Name>
      </Names>
   </Brand>
</Brands>
<Products>
   <Product>
      <Name>First Product</Name>
      <ExternalId>Prod-1234</ExternalId>
      <BrandExternalId>AAA</BrandExternalId>
      ...
   </Product>
</Products>

Categories element

The <Categories> element defines each category that is represented by products in your feed using the following child elements. It can also be used to define a category hierarchy. This element is required.

Element Value Required
Category

Represents a product category in your feed and may include other elements listed in this table.

You can include the removed="true" attribute in the <Category> element to mark the category inactive.

 Yes
ExternalId

Unique category or subcategory ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If a category ID contains an invalid character, replace it with an alternate character, such as an underscore. This format is used in the data feed only and does not affect end users. The ID is case insensitive, so you cannot use IDs that match except for case.

Ensure that the category ID is stable and will not change, even if the name of the category changes.

 Yes
ParentExternalId Parent category's ID of the subcategory in question. No
Name or Names

Name of the category or subcategory, which is visible to end users.

If specifying localized categories in a multilingual implementation, include a <Name> element for each locale in a parent <Names> element, and then specify the locale attribute (of type String) for each <Name> child element.

 Yes
CategoryPageUrl or CategoryPageUrls

Unique URL for the category or subcategory. When specifying a URL, be aware of the following:

  • Do not include extraneous query string parameters that you might use for tracking and partnership codes.
  • If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).
  • If specifying localized categories in a multilingual implementation, include a <CategoryPageUrl> element for each locale in a parent <CategoryPageUrls> element, and then specify the locale attribute (of type String) for each <CategoryPageUrl> child element.
 Only if collecting Questions & Answers content at the Category level
ImageUrl or ImageUrls

Unique URL for the category or subcategory image, which is usually hosted on your website or a content delivery network. When specifying a URL, be aware of the following:

  • If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).
  • If specifying localized categories in a multilingual implementation, include an <ImageUrl> element for each locale in a parent <ImageUrls> element, and then specify the locale attribute (of type String) for each <ImageUrl> child element.
Note: If Ratings & Reviews is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.
 Only if collecting Questions & Answers content at the Category level 
<Categories>
    <Category>
        <ExternalId>1010</ExternalId>
        <!-- Default category name -->
        <Name>First Category</Name>
        <!-- Localized category names -->
        <Names>
            <Name locale="en_CA">First Category CA</Name>
            <Name locale="fr_CA">Première catégorie CA</Name>
        </Names>
        <!-- Default category page URL -->
        <CategoryPageUrl>
            http://www.example.com/category.htm?cat=1010
        </CategoryPageUrl>
        <!-- Localized category page URLs -->
        <CategoryPageUrls>
            <CategoryPageUrl locale="en_CA">
                 http://www.example.ca/en_ca/category.htm?cat=1010
            </CategoryPageUrl>
            <CategoryPageUrl locale="fr_CA">
                 http://www.example.ca/fr_ca/category.htm?prod=1010
            </CategoryPageUrl>
        </CategoryPageUrls>
        <!-- Default category image URL -->
        <ImageUrl>http://images.example.com/catimages/1010.gif</ImageUrl>
        <!-- Localized category image URLs -->
        <ImageUrls>
            <ImageUrl locale="en_CA">
                http://images.example.ca/en_ca/catimages/1010.gif
            </ImageUrl>
            <ImageUrl locale="fr_CA">
                http://images.example.ca/fr_ca/catimages/1010.gif
            </ImageUrl>
        </ImageUrls>
    </Category>
    <Category>
        <ExternalId>1020</ExternalId>
        <Name>Second Category</Name>
        <CategoryPageUrl>
            http://www.example.com/category.htm?cat=1020
        </CategoryPageUrl>
        <ImageUrl>http://images.example.com/catimages/1020.gif</ImageUrl>
    </Category>
    <Category>
        <ExternalId>1021</ExternalId>
        <ParentExternalId>1020</ParentExternalId>
        <Name>Sub Category</Name>
        <CategoryPageUrl>
            http://www.example.com/category.htm?cat=1021
        </CategoryPageUrl>
        <ImageUrl>http://images.example.com/catimages/1021.gif</ImageUrl>
    </Category>
</Categories>

Products element

The <Products> element defines each product in your feed using these common child elements. This element is required. Refer to the product feed schema for a complete list of available elements.

Element Value Required
Product

Represents a product in your feed and may include other elements listed in this table.

You can include the removed="true" attribute in the <Product> element to mark the product inactive. If the product does not exist in the database and is marked inactive, it is not added to the database.

 Yes
ExternalId

Unique product ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If the external product ID contains an invalid character, replace it with an alternate character, such as an underscore. The ID is case insensitive, so you cannot use IDs that match except for case.

This format is used in the data feed only and is not visible to end users.

 Yes, one for each product
Name or Names

Name or names of the product, which is visible to end users.

If specifying localized product names in a multilingual implementation, include a <Name> element for each locale in a parent <Names> element, and then specify the locale attribute (of type String) for each <Name> child element.

 Yes, one for each locale
Description or Descriptions

Description of the product. Bazaarvoice recommends that product descriptions be at least three sentences or 300 characters long.

If specifying localized product descriptions in a multilingual implementation, include a <Description> element for each locale in a parent <Descriptions> element, and then specify the locale attribute (of type String) for each <Description> child element.

 Yes, one for each locale
Brand The name of the brand to which the product belongs. You must include a <Name> child element, to specify the brand name.
Note: Specify either <Brand> or <BrandExternalId> in the <Product> element, but do not specify both.
 Yes, one per product, if <BrandExternalId> is not provided
BrandExternalId

ID of the brand to which the product belongs. Specify this element if a brand is declared as a separate element in the <Brands> block. The value of <BrandExternalId> must match a brand ID defined in the <Brands> block. If the <Brands> block is not defined in the product feed, use <Brand> (above) instead.

Note: Specify either <BrandExternalId> or <Brand> in the <Product> element, but do not specify both.
 Yes, one per product, if <Brand> is not provided
CategoryExternalId

Category or subcategory ID for the product. Specify this element if a category is declared as a separate element in the <Categories> block. The value of <CategoryExternalId> must match a category ID defined in the <Categories> block. If the <Categories> block is not defined in the product feed, use <CategoryPath> (below) instead.

Note: Specify either <CategoryExternalId> or <CategoryPath> in the <Product> element, but you cannot specify both.
 Yes, one per product
CategoryPath

A list of categories ordered by hierarchy. Each category must be specified in a <CategoryName> child element. You can specify multiple <CategoryName> child elements, each for a subcategory of the <CategoryName> immediately above it.

Note: Specify either <CategoryPath> or <CategoryExternalId> in the <Product> element, but you cannot specify both.
 Recommended, one per product
ProductPageUrl or ProductPageUrls

Unique, uncorrupted URL for a product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes. When specifying a URL, be aware of the following:

  • If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).
  • If specifying localized URLs in a multilingual implementation, include a <ProductPageUrl> element for each locale in a parent <ProductPageUrls> element, and then specify the locale attribute (of type String) for each <ProductPageUrl> child element.
 Yes, one per locale
ImageUrl or ImageUrls

Unique URL for the product image. The optimal but slightly flexible display size is 600 x 600 pixels. When specifying a URL, be aware of the following:

  • If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).
  • If specifying localized images in a multilingual implementation, include an <ImageUrl> element for each locale in a parent <ImageUrls> element, and then specify the locale attribute (of type String) for each <ImageUrl> child element.
Note: If Ratings & Reviews is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.
 Yes, one per locale
ModelNumbers Unique referencing code that businesses use to identify a part that a particular industry uses. Specify a <ModelNumber> child element for each model number you want to define. Each model number can contain letters, numerals, and other characters. No; if included, one per product
ManufacturerPartNumbers Manufacturer-specific part number. Specify a <ManufacturerPartNumber> child element for each part number you want to define. Part numbers can contain letters, numerals, and characters. Yes; you can specify an unlimited number of child elements
EANs

European Article Numbers (EANs), which are used worldwide for marking retail goods. Specify an <EAN> child element for each EAN you want to define, which must be a string of eight numerals or 13 numerals (no letters or other characters are allowed). Remove spaces and hyphens because they disrupt syndication matching.

Note: Version 14.3+ of the schema does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored. You can find the complete syntax for all globally unique identifiers in this sample file.

Either EANs, UPCs, or ISBNs is required.

If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
UPCs

Universal Product Code (UPC), which is a 6- or 12-digit bar code used for standard retail packaging in the United States. Specify a <UPC> child element for each UPC you want to define, which can contain numerals only, with no letters or other characters. Remove spaces and hyphens because they disrupt syndication matching.

Note: Version 14.3+ of the schema does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored. You can find the complete syntax for all globally unique identifiers in this sample file.

Either EANs, UPCs, or ISBNs is required.

If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
ISBNs International Standard Book Number (ISBN), which is a 10- or 13-character value used predominantly for media products such as books, music, and videos. Specify an <ISBN> child element for each ISBN you want to define. The last character provides a checksum that helps validate the product identifier. Most ISBNs are composed only of digits, except for some 10-character ISBN values that use an X for the checksum.

Either EANs, UPCs, or ISBNs is required.

If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
Attributes Custom attributes that enable you to define additional product-specific information, to report on product-specific information or to support product families. Specify an <Attribute> child element for each product attribute you want to define. Be sure to include the name of the product attribute using the id attribute of the <Attribute> element; spaces are not permitted in the attribute ID. No; if included, you can specify an unlimited number of child elements
Color

Color of the product.

 No; Recommended
Size

Size of the product.

 No; Recommended
Material

Material of the product. For example, steel, plastic, silk, etc.

 No; Recommended
Currency

Currency of the product in each Locale.

Note: Currency must be provided in the format ISO 4217N.

 No; Recommended
Price

Price of the product.

 No; Recommended
Availability

Indicates whether or not a product is available to purchase. It may be out of stock or out of season.

 No; Recommended 
<Products>
    <Product>
        <ExternalId>11111111111abc</ExternalId>
        <Name>First Product Round with Green</Name>
        <Description>First Product Description Text</Description>
        <Brand>
            <Name>brand-123</Name>
        </Brand>
        <CategoryPath>
            <CategoryName>Category</CategoryName>
            <CategoryName>Sub Category</CategoryName>
        </CategoryPath>
        <ProductPageUrl>http://www.example.com/product.htm?prod=2000001</ProductPageUrl>
        <ImageUrl>http://images.example.com/prodimages/2000001.gif</ImageUrl>
        <!-- Product details needed for syndication -->
        <ManufacturerPartNumbers>
            <ManufacturerPartNumber>26-12345-8Z</ManufacturerPartNumber>
        </ManufacturerPartNumbers>
        <EANs>
            <EAN>0213354752286</EAN>
            <EAN>0188173724031</EAN>
        </EANs>
        <UPCs>
            <UPC>382157229380</UPC>
            <UPC>283929327281</UPC>
        </UPCs>
        <!-- Custom product attributes -->
        <Attributes>
            <Attribute id="SAP_STATUS">
               <Value>L</Value>
            </Attribute>
            <Attribute id="BUYING_NUMBER">
               <Value>Not_Available</Value>
            </Attribute>
            <Attribute id="PROD_MGMT_GRP_NUMBER">
               <Value>Group56789</Value>
            </Attribute>
        </Attributes>
    </Product>
    <Product>
        <ExternalId>22</ExternalId>
        <Name>Second Product Round and Green</Name>
        <Description>Second Product Description Text</Description>
        <BrandExternalId>BBB</BrandExternalId>
        <CategoryExternalId>1021</CategoryExternalId>
        <ProductPageUrl>http://www.example.com/product.htm?prod=2000002</ProductPageUrl>
        <ImageUrl>http://images.example.com/prodimages/2000002.gif</ImageUrl>
        <ModelNumbers>
           <ModelNumber>1235832</ModelNumber>
           <ModelNumber>1235839</ModelNumber>
        </ModelNumbers>
        <ManufacturerPartNumbers>
           <ManufacturerPartNumber>26-12345-8W</ManufacturerPartNumber>
        </ManufacturerPartNumbers>
        <EANs>
           <EAN>0213354752287</EAN>
        </EANs>
        <UPCs>
           <UPC>138313830283</UPC>
        </UPCs>
    </Product>
</Products>

Step 3: Validate the feed

Your feed needs well-formed XML that works with the Bazaarvoice XML schema . Validate your feed against the schema before uploading it to Bazaarvoice. You can use an XML validation tool to validate your feed, or you can upload your product feed by SFTP by following the steps below and trigger an import via staging Workbench.

Step 4: Upload the feed

Bazaarvoice recommends that you upload an updated product feed whenever changes are made to your product catalog as reflected by your website. It is imperative that you provide Bazaarvoice with matching updates as your product catalog changes on your live site.

You can add another level of security to your data by supplying a public Secure Socket Shell (SSH) key using SSH passwordless entry. This process relies on a private key that resides with you, paired with a public key used by a Bazaarvoice SFTP server. If you want to set up this key-based authentication method, contact Bazaarvoice Support for information and assistance.

Upload the XML feed file to the /import-inbox directory of the SFTP server:

  • If your data is hosted in the US, use the following URLs:
    • Staging server—sftp-stg.bazaarvoice.com
    • Production server—sftp.bazaarvoice.com
  • If your data is hosted in Europe, use the following URLs:
    • Staging server—sftp7-stg.bazaarvoice.com
    • Production server—sftp7.bazaarvoice.com

Be sure to connect to SFTP using port 22. Contact Bazaarvoice Support if you do not know your SFTP credentials or where your data is hosted.

After you upload a product feed to an SFTP server, Bazaarvoice automatically begins importing the feed at 2 AM Central Time (CST: UTC-6 or CDT: UTC-5), although Bazaarvoice may not finish importing your feed until later the same day due to the import process.

If you uploaded the feed to a staging server, you can trigger an import manually. (You cannot manually trigger an import to the production server.) Complete the following steps to manually import the feed:

  1. From the Bazaarvoice Workbench of your staging server, select Settings > Validate Product Feed.
  2. Select Schedule one-time import to manually import the feed.

Step 5: Check the feed status

After uploading a feed to the staging or production SFTP server, you can view the import summary and error or warning count of the feed. Checking the import summary enables you to correct errors before the next import, so you can ensure you provide a valid feed for the next import.

View the import summary for your staging server or production server by selecting Settings > Validate Product Feed. If your feed returns an error or warning, select it for more information.

Note: Validate the feed as described in Step 3 before uploading it and using the feed validation tool in the Workbench. You should upload only well-formed feeds to the server and use the feed validation tool to catch errors your primary validation tool may have missed.

Example XML feed

Although the following example product feed is probably smaller and less complex than your product feed, you can review it to learn about the basic feed structure required by Bazaarvoice.

<?xml version="1.0" encoding="utf-8"?>
<Feed xmlns="http://www.bazaarvoice.com/xs/PRR/ProductFeed/15.1" name="ExampleClient" incremental="false" extractDate="2011-10-18T12:00:00.000000">

   <!-- Brands -->
   <Brands>
      <Brand>
         <ExternalId>AAA</ExternalId>
         <Name>First Brand</Name>
      </Brand>
      <Brand>
         <ExternalId>BBB</ExternalId>
         <!-- Default brand name -->
         <Name>Second Brand</Name>
         <!-- Localized brand names -->
         <Names> 
            <Name locale="en_US">Second Brand US</Name>
            <Name locale="en_CA">Second Brand CA</Name>
            <Name locale="fr_CA">Deuxième marque CA</Name>
         </Names>
      </Brand>
   </Brands>

   <!-- Categories -->
   <Categories>
      <Category>
         <ExternalId>1010</ExternalId>
         <!-- Default category name -->
         <Name>First Category</Name>
         <!-- Localized category names -->
         <Names> 
            <Name locale="en_US">First Category US</Name>
            <Name locale="en_CA">First Category CA</Name>
            <Name locale="fr_CA">Première catégorie CA</Name>
         </Names>
         <!-- Default category page URL -->
         <CategoryPageUrl>http://www.example.com/category.htm?cat=1010</CategoryPageUrl>
         <!-- Localized category page URLs -->
         <CategoryPageUrls>
            <CategoryPageUrl locale="en_US">http://www.example.com/en_us/category.htm?cat=1010</CategoryPageUrl>
            <CategoryPageUrl locale="en_CA">http://www.example.com/en_ca/category.htm?cat=1010</CategoryPageUrl>
            <CategoryPageUrl locale="fr_CA">http://www.example.com/fr_ca/category.htm?prod=1010</CategoryPageUrl>
         </CategoryPageUrls>
         <!-- Default category image URL -->
         <ImageUrl>http://images.example.com/catimages/1010.gif</ImageUrl>
         <!-- Localized category image URLs -->
         <ImageUrls>
            <ImageUrl locale="en_US">http://images.example.com/en_us/catimages/1010.gif</ImageUrl>
            <ImageUrl locale="en_CA">http://images.example.com/en_ca/catimages/1010.gif</ImageUrl>
            <ImageUrl locale="fr_CA">http://images.example.com/fr_ca/catimages/1010.gif</ImageUrl>
         </ImageUrls>
      </Category>
      <Category>
         <ExternalId>1020</ExternalId>
         <Name>Second Category</Name>
         <CategoryPageUrl>http://www.example.com/category.htm?cat=1020</CategoryPageUrl>
         <ImageUrl>http://images.example.com/catimages/1020.gif</ImageUrl>
      </Category>
      <Category>
         <ExternalId>1021</ExternalId>
         <ParentExternalId>1020</ParentExternalId>
         <Name>Sub Category</Name>
         <CategoryPageUrl>http://www.example.com/category.htm?cat=1021</CategoryPageUrl>
         <ImageUrl>http://images.example.com/catimages/1021.gif</ImageUrl>
      </Category>
   </Categories>

   <!-- Products -->
   <Products>
      <Product>
         <ExternalId>11111111111abc</ExternalId>
         <Name>First Product Round with Green</Name>
         <Description>First Product Description Text</Description>
         <BrandExternalId>AAA</BrandExternalId>
         <CategoryExternalId>1010</CategoryExternalId>
         <ProductPageUrl>http://www.example.com/product.htm?prod=2000001</ProductPageUrl>
         <ImageUrl>http://images.example.com/prodimages/2000001.gif</ImageUrl>
         <!-- Product details needed for syndication -->
         <ManufacturerPartNumbers>
            <ManufacturerPartNumber>26-12345-8Z</ManufacturerPartNumber>
         </ManufacturerPartNumbers>
         <EANs>
            <EAN>0213354752286</EAN>
            <EAN>0188173724031</EAN>
            <EAN>1833474920123</EAN>
         </EANs>
         <UPCs>
            <UPC>382157229380</UPC>
            <UPC>283929327281</UPC>
            <UPC>058227392728</UPC>
         </UPCs>
         <!-- Custom product attributes -->
         <Attributes>
            <!-- Families the product is a member of -->
            <Attribute id="BV_FE_FAMILY">
               <Value>Green</Value>
            </Attribute>
            <Attribute id="BV_FE_FAMILY">
               <Value>Round</Value>
            </Attribute>
            <!-- Product management group ID -->
            <Attribute id="ProductManagementGroupId">
               <Value>Group56789</Value>
            </Attribute>
         </Attributes>
      </Product>
      <Product>
         <ExternalId>22</ExternalId>
         <Name>Second Product Round and Green</Name>
         <Description>Second Product Description Text</Description>
         <BrandExternalId>BBB</BrandExternalId>
         <CategoryExternalId>1021</CategoryExternalId>
         <ProductPageUrl>http://www.example.com/product.htm?prod=2000002</ProductPageUrl>
         <ImageUrl>http://images.example.com/prodimages/2000002.gif</ImageUrl>
         <ModelNumbers>
            <ModelNumber>1235832</ModelNumber>
            <ModelNumber>1235839</ModelNumber>
         </ModelNumbers>
         <ManufacturerPartNumbers>
            <ManufacturerPartNumber>26-12345-8W</ManufacturerPartNumber>
         </ManufacturerPartNumbers>
         <EANs>
            <EAN>0213354752287</EAN>
         </EANs>
         <UPCs>
            <UPC>138313830283</UPC>
         </UPCs>
         <!-- Custom product attributes -->
         <Attributes>
            <!-- Families the product is a member of -->
            <Attribute id="BV_FE_FAMILY">
               <Value>Round</Value>
            </Attribute>
            <Attribute id="BV_FE_FAMILY">
               <Value>Green</Value>
            </Attribute>
            <!-- Show all content from other products in the Round Family -->
            <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:Round</Value>
            </Attribute>
            <!-- Product management group ID -->
            <Attribute id="ProductManagementGroupId">
               <Value>Group56789</Value>
            </Attribute>
         </Attributes>
      </Product>
      <!-- Example product with multiple languages -->
      <Product>
         <ExternalId>333</ExternalId>
         <!-- Default product name -->
         <Name>Third Product Square and Red</Name>
         <!-- Localized product names -->
         <Names> 
            <Name locale="en_US">Third Product US</Name>
            <Name locale="en_CA">Third Product CA</Name>
            <Name locale="fr_CA">Troisième produit CA</Name>
         </Names>
         <!-- Default product description -->
         <Description>Third Product Description Text</Description>
         <!-- Localized product descriptions -->
         <Descriptions>
            <Description locale="en_US">Third Product Description Text US</Description>
            <Description locale="en_CA">Third Product Description Text CA</Description>
            <Description locale="fr_CA">Troisième texte Description du produit</Description>
         </Descriptions>
         <BrandExternalId>BBB</BrandExternalId>
         <CategoryExternalId>1021</CategoryExternalId>
         <!-- Default product page URL -->
         <ProductPageUrl>http://www.example.com/product.htm?prod=2000003</ProductPageUrl>
         <!-- Localized product page URLs -->
         <ProductPageUrls>
            <ProductPageUrl locale="en_US">http://www.example.com/en_us/product.htm?prod=2000003</ProductPageUrl>
            <ProductPageUrl locale="en_CA">http://www.example.com/en_ca/product.htm?prod=2000003</ProductPageUrl>
            <ProductPageUrl locale="fr_CA">http://www.example.com/fr_ca/product.htm?prod=2000003</ProductPageUrl>
         </ProductPageUrls>
         <!-- Default product image URL -->
         <ImageUrl>http://images.example.com/prodimages/2000003.gif</ImageUrl>
         <!-- Localized product image URLs -->
         <ImageUrls>
            <ImageUrl locale="en_US">http://images.example.com/en_us/prodimages/2000003.gif</ImageUrl>
            <ImageUrl locale="en_CA">http://images.example.com/en_ca/prodimages/2000003.gif</ImageUrl>
            <ImageUrl locale="fr_CA">http://images.example.com/fr_ca/prodimages/2000003.gif</ImageUrl>
         </ImageUrls>
         <ModelNumbers>
            <ModelNumber>123523832</ModelNumber>
            <ModelNumber>123325839</ModelNumber>
         </ModelNumbers>
         <ManufacturerPartNumbers>
            <ManufacturerPartNumber>26-93812-8W</ManufacturerPartNumber>
         </ManufacturerPartNumbers>
         <EANs>
            <EAN>0813354723287</EAN>
         </EANs>
         <UPCs>
            <UPC>138313830999</UPC>
         </UPCs>
         <!-- Custom product attributes -->
         <Attributes>
            <!-- Families this product is a member of -->
            <Attribute id="BV_FE_FAMILY">
               <Value>Red</Value>
            </Attribute>
            <Attribute id="BV_FE_FAMILY">
               <Value>Square</Value>
            </Attribute>
            <!-- Show all content from other products in the Red Family -->
            <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:Red</Value>
            </Attribute>
            <!-- Show all content from other products in the Square Family -->
            <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:Square</Value>
            </Attribute>
            <!-- Price of this product in USA -->
            <Attribute id="PriceUs">
               <Value>65.30</Value>
            </Attribute>
            <!-- Price of this product in Canada -->
            <Attribute id="PriceCa">
               <Value>67.25</Value>
            </Attribute>
            <!-- Product management group ID -->
            <Attribute id="ProductManagementGroupId">
               <Value>Group12345</Value>
            </Attribute>
         </Attributes>
      </Product>
      <Product>
         <ExternalId>4444</ExternalId>
         <Name>Fourth Product Round and Black</Name>
         <Description>Fourth Product Description Text</Description>
         <BrandExternalId>BBB</BrandExternalId>
         <CategoryExternalId>1021</CategoryExternalId>
         <ProductPageUrl>http://www.example.com/product.htm?prod=2000002</ProductPageUrl>
         <ImageUrl>http://images.example.com/prodimages/2000002.gif</ImageUrl>
         <ModelNumbers>
            <ModelNumber>1235832</ModelNumber>
            <ModelNumber>1235839</ModelNumber>
         </ModelNumbers>
         <ManufacturerPartNumbers>
            <ManufacturerPartNumber>26-12345-8W</ManufacturerPartNumber>
         </ManufacturerPartNumbers>
         <EANs>
            <EAN>0213354752287</EAN>
         </EANs>
         <UPCs>
            <UPC>138313830283</UPC>
         </UPCs>
         <!-- Custom product attributes -->
         <Attributes>
            <!-- Families this product is a member of -->
            <Attribute id="BV_FE_FAMILY">
               <Value>Round</Value>
            </Attribute>
            <!-- Show all content from other products in the Round Family -->
            <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:Round</Value>
            </Attribute>
            <!-- Product management group ID -->
            <Attribute id="ProductManagementGroupId">
               <Value>Group56789</Value>
            </Attribute>
         </Attributes>
      </Product>
      <Product>
         <ExternalId>55555</ExternalId>
         <Name>Fifth Product- Family level</Name>
         <Description>Use this product to collect reviews at a Family level. This product is also a member of the Green Family. It has the BV_FE_EXPAND Attribute set which will pull all reviews for the family</Description>
         <BrandExternalId>BBB</BrandExternalId>
         <CategoryExternalId>1021</CategoryExternalId>
         <ProductPageUrl>http://www.example.com/product.htm?prod=2000002</ProductPageUrl>
         <ImageUrl>http://images.example.com/prodimages/2000002.gif</ImageUrl>
         <ModelNumbers>
            <ModelNumber>1235832green</ModelNumber>
            <ModelNumber>1235543green</ModelNumber>
            <ModelNumber>127654green</ModelNumber>
            <ModelNumber>123111green</ModelNumber>
         </ModelNumbers>
         <UPCs>
            <UPC>138313830281</UPC>
            <UPC>138313830282</UPC>
            <UPC>138313830283</UPC>
            <UPC>138313830284</UPC>
         </UPCs>
         <!-- Custom product attributes -->
         <Attributes>
            <!-- Families this product is a member of -->
            <Attribute id="BV_FE_FAMILY">
               <Value>Green</Value>
            </Attribute>
            <!-- Show all content from other products in the Green Family -->
            <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:Green</Value>
            </Attribute>
         </Attributes>
      </Product>
   </Products>
</Feed>

Incremental feed files

A full product catalog feed includes all products that are available in your catalog and for which you want to collect content. An incremental feed contains data for a subset of your products.

Consider the following strategies for using full vs. incremental feeds:

  • Only full feeds

    You can upload a full, periodic, XML catalog feed to Bazaarvoice that includes all current data for all active products and categories. This is the recommended strategy.

  • Full and incremental feeds

    You can provide a mix of full and incremental catalog feeds. We recommend that you provide an initial full catalog feed followed by periodic, incremental feeds that contain only changes to your catalog data. Consider using full and incremental product feeds if:

    • Your product catalog changes so frequently that daily product feed updates are necessary
    • Infrequent or modest updates are made to your product feed

    However, to prevent gaps in the data set that can result from failure to upload and process any given incremental feed, we recommend that you provide a full feed periodically (with current data for your complete catalog) to ensure no data gaps exist.

  • Only incremental feeds

    If you cannot provide all products in a single, full catalog feed, you can provide incremental feeds only. Be sure to include the removed=”true” attribute when providing only incremental feeds. Refer to Control the active set of products for more information about this approach.

    Caution: If you use incremental feeds only and you never provide a full feed to Bazaarvoice, it is possible that catalog data may become out of sync with your source product catalog if an incremental feed upload is missed or fails in any way.

Each feed file indicates whether it is full or incremental, though this is done differently depending on the feed format:

  • XML feed files: use the incremental attribute in the <Feed> element
  • Text feed files: specify a file header

Filter catalog data based on custom product attributes

To filter your product feed by custom product attributes, you must add them to your feed configuration. This lets you filter based on attributes in the content dashboards and reports in Portal. Custom product attributes give you a way to report on product-specific information; however, it does not provide multiple categories in a feed. For example, you could define a "region" attribute to report on hotels in a region of the country. Or, you could define a "department" attribute to track how products from various departments are being received by your customers.

Note: If you want to include custom product attributes in a text feed, contact Bazaarvoice Support for assistance.

Complete these steps to add a custom product attribute to your implementation and then enable custom product attributes in Portal:

  1. Include custom product attributes in the feed by adding the <Attributes> block to the <Products> element. Each <Attribute> element in the <Attributes> block identifies a custom attribute. Here is an example of three custom attributes:
    <Products>
        <Product>
        ...
        <Attributes>
            <Attribute id="CHANNEL_VISIBILITY">
                    <Value>Any</Value>
                </Attribute>
                <Attribute id="SAP_STATUS">
                    <Value>L</Value>
                </Attribute>
                <Attribute id="BUYING_NUMBER">
                    <Value>Not_Available</Value>
                </Attribute>
            </Attributes>
    </Product>
    </Products>
  2. Sign in to the Bazaarvoice Portal .
    Note: You can create attributes on your production server, but you may want to test and preview this on the staging server first.
  3. From the upper-right corner, select the settings icon settings icon.
  4. Select Configuration.
  5. Select an instance.
  6. Select Go to Configuration. The Site Manager appears, listing the available deployment zones and implementations.

    Note: You can also add new deployment zones and implementations on this screen.

  7. Under Implementations, use the filter to find the name of the implementation you require.
  8. Select Edit next to the implementation you want to configure.
    Note: You can't enable custom product attributes in individual deployment zones. If you haven't enabled them in the Main Site deployment zone, they won't display in Portal.
  9. From the menu on the left side of the page, select Technical Setup under Getting Started.
  10. Select the Product Catalog tab.
  12. In the Feed Attributes section, type an attribute name in the Custom Product Attributes field and then select Add. The attribute name must match the id attribute of the <Attribute> element in the product feed. Repeat this step for every attribute you want to add.

    13. This example shows attributes that match the IDs in the previous XML example:

    </ol>

    You can use custom product attributes to filter content in Portal reports, dashboards, and other views.

    Share reviews using product families

    Product families enable you to share UGC across multiple related products. By grouping products into families, you can display UGC written about one family member on the product display pages of all family members. Sharing reviews among product family members increases the following key performance indicators for your Bazaarvoice implementation:

    • Percentage of products with displayed reviews
    • Number of products with displayed reviews
    • Average reviews for each product
    • Number of total displayed reviews

    Types of product families

    The type of product family that you use depends on how products differ:

    • Product variants — Products that are nearly identical to other products in terms of consumer experience, but they have different SKUs or part numbers. For example, products that come in different colors, different sizes, or are packaged in different weights or quantities may be variants of one another. Content from product variants is usually shared in all directions. All products in a given family display content that was written about the other family members.

      Creating a product family of product variants works best when each product variant is featured on its own product display page. If all product variants share the same page on your site, treating the variants as one product when integrating with Bazaarvoice may be simpler and more practical than setting up a product family for those products.

    • Product bundles — Groups of products sold together that otherwise may be sold individually. Content about product bundles is usually shared in one direction: from individual components to the product bundle. Typically, the product display page of a bundle displays all reviews written about the individual components. However, the product display page of each component shows reviews only about that component.

    Configure product families

    You can configure product families in your product feed or through Portal. You can assign a product to one or more families at the same time using these methods.

    Keep the following caveats in mind when configuring product families:

    • Product family configurations do not carry over between the staging and production environments.
    • Any changes you make to product families directly in the Portal user interface or using its predecessor, Workbench, can be undone only through Portal or Workbench.
    • Family definitions in the product feed do not override any family operations in Portal or Workbench.
    Note: Product families only work for native reviews. Syndication ignores product family relationships. If you plan to or have implemented syndication, contact Bazaarvoice Support before configuring product families in your product feed.

    Using the product feed

    We recommend you create product families through the product feed if you have a clear idea about which products can be grouped into families. Automating those relationships in the product feed is straightforward and faster than creating them using Portal.

    You can configure product families in your product feed by including one or both of the following attributes:

    • BV_FE_FAMILY—Adds a product to a specific family.
    • BV_FE_EXPAND—Enables a product to display all content from other members of the family.
    Tip: We recommend that you do not use special characters, such as commas, in product family names.

    In this XML example, all products in a family display content about all other members in the family.

    <Product>
     <ExternalId>...</ExternalId>
     <Name>Green iPod Nano</Name>
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId>
     <CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
          <Attribute id="BV_FE_FAMILY">
               <Value>iPod_Nanos</Value>
          </Attribute>
          <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:iPod_Nanos</Value>
          </Attribute>
     </Attributes>
</Product>
<Product>                 
     <ExternalId>...</ExternalId>
     <Name>Pink iPod Nano</Name>
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId>
     <CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
       <Attribute id="BV_FE_FAMILY">
        <Value>iPod_Nanos</Value>
        </Attribute>
        <Attribute id="BV_FE_EXPAND">
             <Value>BV_FE_FAMILY:iPod_Nanos</Value>
       </Attribute>
     </Attributes>
</Product>

    In the following XML example, the product bundle includes BV_FE_EXPAND, so all reviews about family components display on the bundle's page. However, BV_FE_EXPAND is omitted from the product <Attribute> definitions of the individual components to prevent reviews about the bundle from displaying on component pages.

    <Product>
     <ExternalId>...</ExternalId>  
     <Name>Value Bundle</Name>   
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId>
     <CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
          <Attribute id="BV_FE_FAMILY">
               <Value>Value_Bundle</Value>
          </Attribute>
          <!-- Including BV_FE_EXPAND displays content from all components on the bundle page -->
          <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:Value_Bundle</Value>
          </Attribute>
     </Attributes>
</Product>
<Product>
     <ExternalId>...</ExternalId>
     <Name>Standalone Component</Name>
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId><CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
          <Attribute id="BV_FE_FAMILY">
               <Value>Value_Bundle</Value>
          </Attribute>
     </Attributes>
     <!-- Omitting BV_FE_EXPAND prevents content from the bundle from being displayed on the component page -->
</Product>

    Using the Workbench

    Only use Workbench to manage product families if you are already using Workbench for this purpose. Workbench is a predecessor of Portal that will be retired after a transition period. The new Manage families feature in Portal has the same functionality as Workbench, but the workflows and text have been improved based on user research.

    Using Portal

    Use Portal to manually create families in the following situations:

    • You are not familiar with XML.
    • You are unable to work on the product feed.
    • You need to create a family whose UGC sharing relationships are not straightforward or possible to configure in the product feed.

      The following two examples describe scenarios in which a product family should be created using Portal

      • A category manager for MP3 players wants to share reviews among all the colors of the 32 MB and 64 MB players. Setting up separate families for the 32 MB device and the 64 MB device is straightforward in the feed. However, because the 32 MB device and 64 MB device have different SKUs, combining them into one family using the feed might not be possible. The category manager should configure the family in Portal.
      • A personal-care brand manager wants to bundle lip balm and sunscreen for sale during the summer months. The brand manager wants to configure a product family containing the lip balm and sunscreen so that reviews about the individual family members will be shared on the product bundle's page. However, the lip balm and sunscreen do not have a common product feed element to link them together. The brand manager should configure the product family in Portal. When the season ends and the brand manager no longer wants to sell the products together, the manager can delete the product family bundle using Portal.

    For instructions, refer to Configure product families using Portal.

    Define a product category hierarchy

    If you create an XML feed file, you can define product category hierarchy. You can associate each product with a specific category within the hierarchy using the <CategoryExternalId> element, and you can define a category's parent, thereby defining the category hierarchy, using the <ParentExternalId> element.

    Be aware of the following if you are providing multiple feeds for your catalog data:

    • A product that appears in multiple feeds must be in the same category in all feeds. Therefore, if product A is in category X in Feed A, then product A cannot be in category Y in Feed B.
    • A category that is listed in multiple feeds must be in the same parent category in all feeds. Therefore, if category A is in parent category X in Feed A, then category A cannot be in parent category Y in Feed B.

    The following XML file excerpt defines a <CategoryExternalId> for a category that is then reference by a <ParentExternalId> element.

    <Categories>
   <Category>
      <ExternalId>food-1123</ExternalId>
       <Name>Food</Name>            <= no parent category; this is a top-level hierarchy element
         ...
   </Category>
   <Category>
      <ExternalId>fruit-1789</ExternalId>
      <Name>Fruit</Name>
      <ParentExternalId>food-1123</ParentExternalId>         <= "Fruit" category is a child of category “Food”
      ...
   </Category>
</Categories>
<Products>
   <Product>
      <ExternalId>123</ExternalId>
      <Name>Apple</Name>
      <CategoryExternalId>fruit-1789</CategoryExternalId>      <= belongs to category “Fruit”
      ...
   </Product>
   ...
</Products>