ATG Recommendations Catalog Format Guide

Catalog Delivery

XML catalogs should be submitted via FTP at ftp.atgsvcs.com using the same username and password you use on our Retailer Site (http://recmanager.atg.com).

Catalog Formatting

ATG Recommendations presently accepts the Google Base Bulk Upload Format in XML (RSS 2.0) format.

To be well-formed XML, a catalog must extend the RSS 2.0 standard. It must also group all product information within <rss> and <channel> blocks.

Your file must look like this:

<?xml version="1.0"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0">
  <channel>

    Your Product Information Goes Here

  </channel>
</rss>

Individual products may then be inserted inside <item> tags. All data inside an <item> block must be within appropriate definition tags. There are tags within all three defined namespaces which you may wish to utilize.

A list of fields that ATG Recommendations expects and their corresponding XML tag follows.

The format is <tag>ATG attribute</tag>.

Required:

• <title>title</title>
• <description>description</description>
• <link>link</link>
• <g:id>id</g:id>
• <g:image_link>image_link</g:image_link>
• <g:price type=price_type>price</g:price>

Required (if available):

• <g:category>category</g:category>
• <g:brand>brand</g:brand>

Recommended:

• <g:instock>instock</g:instock>
• <c:inventory>inventory</c:inventory>
• <c:recommend>recommend</c:recommend>
• <c:tags>tags</c:tags>
• <c:recommended>recommended</c:recommended>

Optional:

• <g:expiration_date>date</g:expiration_date>
• <c:new>new</c:new>
• <c:groups>groups</groups>
• <c:includeFirstRecs>includeFirstRecs</includeFirstRecs>
• <c:includeRandomRecs>includeRandomRecs</includeRandomRecs>
• <c:excludeRecs>excludeRecs</excludeRecs>
• <c:attribute name="[attribute_name]" type="[content_type]">value</c:attribute>

So an example file with only one product and only the required information would look like:

<?xml version="1.0"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0">
  <channel>

    <item>
      <title>Blue Jeans</title>
      <description>A rugged pair of pants</description>
      <link>http://mystore.com/clothes/mens/pants/bluejeans.html</link>
      <g:id>43920</g:id>
      <g:image_link>http://mystore.com/images/bluejeans.jpg</g:image_link>
      <g:price>$50.00</g:price>
    </item>

  </channel>
</rss>

Required Fields

There are up to eight attributes that must be included for every product in the catalog feed.

• title – The product’s name or title as it appears on the product page.
• description – The product’s description as it appears on the product page.
• link – The full URL of the product page (including ‘http://’).
• id – A unique identifier for this product, e.g. the item number in your catalog
• image_link – The full URL of the product image (including ‘http://’).
• price – The product’s price. This must match the price listed on your site. Price has an optional type attribute, possible values here might include sale, clearance, outlet, etc which if supplied give you access to a set of out of the box campaigns, please see the campaign documentation for more details.
• category – The product’s category structure on your site. Use a ‘>’ to separate category levels. e.g. Clothes>Mens>Pants
• brand – The brand of the product.

If your catalog includes brand and category information about products, you
must include these attributes as part of your catalog feed. If you do not
use brand or category information on your web site you may omit the unused
attributes.

Optional Fields

Ideally, retailers should also pass as many as eight additional attributes.

• instock – Whether or not this product is in stock (‘true’ or ‘false’).
• inventory – Inventory count for this product.
• recommend – Whether or not to recommend this product (‘true’ or ‘false’).
• tags – A comma-separated list of tags, or keywords, associated with the product. For example, a T-Shirt might have the tags ‘short sleeve,blue,men’s,outdoor’
• recommended – A comma-separated list of product Ids (taken from the same catalog) that have been hand-selected to be recommended with this product.
• expiration_date – The date on which this product expires from your catalog. After this date, the product will no longer be recommended. If you use expiration dates in your catalog, make sure you provide ATG Recommendations with updated catalog data on a regular basis so your entire catalog does not expire, leaving no products that can be used as recommendations.
• new – Whether or not this product is new (‘true’ or ‘false’). Using this attribute allows you to over-ride the system derived attribute that is used in the out of the box new campaigns, please see the campaign documentation for more details.
• groups – A comma-separated list of groups that this item belongs to. Using the groups attribute gives you access to the out of the box group campaigns, please see the campaign documentation for more details.
• includeFirstRecs – A comma-separated list of product ids that should be recommended with this product in all slots in the page. These products will appear before all other recommendations in each slot.
• includeRandomRecs – A comma-separated list of product ids that should be recommended with this product in all slots in the page. These products will appear in random locations, mixed in with generated recommendations, in each slot.
• excludeRecs – A comma-separated list of product ids that must not be recommended with this product.
• attribute – Custom Attributes, please see below for more details.

See the Manually Controlling Recommendations page for more information on the includeFirstRecs, includeRandomRecs, and excludeRecs attributes.

Custom Attributes

Want to tell us more about your items? The ATG Recommendations Catalog Format allows you to define an arbitrary number of custom fields. If you include certain custom attributes such as new and group you can easily take advantage of several out of the box campaigns, please see the campaign documentation for further details. The format for defining custom attributes is as follows:
<c:attribute name="[attribute_name]" type="[content_type]">[value]</c:attribute>

Where:

• [attribute_name] = name of the custom attribute
• [content_type] = content type of the custom attribute
• [value] = value of the custom attribute

The following content types are supported:

Type	Description	Example XML Tag
string	Any text string.	<c:attribute name="color" type="string">red</c:attribute>
int	Whole number value.	<c:attribute name="inventory" type="int">32000000</c:attribute>
float	Number with a decimal point.	<c:attribute name="margin" type="float">3.50</c:attribute>
dateTime	Date and time, the format: yyyy-MM-dd [HH:mm:ss [z]]. (Please see the section below about dates for further details)	<c:attribute name="launch date" type="dateTime"> 1979-10-12 03:44:26</c:attribute/>
url	HTTP URL.	<c:attribute name="overview"type="url"> http://www.atg.com</c:attribute>
boolean	Value may be either true or false.	<c:attribute name="featured" type="boolean">true</c:attribute>

Multi-Valued Custom Attributes

The ATG Catalog Upload Format also supports custom attributes, that contain not one, but two or more values. To take advantage of this special feature simply set type=list and the elementType to any of the above supported content types and separate the values with commas. Commas and backslashes (\) within the values should be escaped using backslashes.

If the colors attribute is a list of the three values black, yellow and red, white, and blue, then the catalog element would be:

<c:attribute name="colors" type="list" elementType="string">black, yellow, red\, white\, and blue</c:attribute>

About Dates

ATG Recommendations allows you to specify optional expiration dates on your products as well as other user defined date type attributes.

Dates are specified in the format yyyy-MM-dd [HH:mm:ss [z]], where the items in brackets are optional.

The year, month, and day are specified using the ISO-8601 format for dates:

• yyyy is the four digit year
• MM is the two digit month
• dd is the two digit day of the month

The time of day is optional. If you choose to provide it, use the following format:

• HH is the two digit hour using 24 hour notation
• mm is the two digit minute
• ss is the two digit second
• z is an optional timezone offset from UTC

Month and day numbers, hours, minutes, and seconds should be padded with leading zeros if necessary to make them two digits each. The timezone offset should be specified as the number of hours and minutes difference from UTC.

The following are all examples of properly formatted dates:

• 2009-03-01 means March 1, 2009 at midnight UTC
• 2009-03-01 14:30:00 means March 1, 2009 at 2:30 pm UTC
• 2009-03-01 14:30:00 -0600 means March 1, 2009 at 2:30 pm Central Standard Time

Getting the Most Out of Your Catalog

Comprehensive product information makes recommendations smarter! ATG Recommendations uses this data to make stronger targeted Recommendations and provide additional Recommendations functionality. The more data you supply, the better Recommendations work, and the easier we can provide you with features like:

• brand exclusivity rules
• same-category recommendations
• category filtering
• new product promotion
• cross-selling
• and more!