This article will explain you how to setup Fredhopper with a relational universe (e.g. products & variants or accommodations & prices). The article does not explain the concepts of relational universes.

Background

Fredhopper can store products & variants in a different universes, this will allow to browse products but use the variant attributes like color & price as if they belong to the products. A relational universe setup is usefull for example for travel or clothing (1 jeans available in multiple sizes).

In this step by step guide we will explain how to setup a simple product & variant relation in Fredhopper, the product universe is the primary universe (catalog01). The variants are stored in a secondary universe (catalog01related). Every variant in this example will have a price, a relational to the product it belongs to and a SKU number.

Requirements

In order to setup a relational universe with Fredhopper it is assumed that the following requirements are met:

• You already have a Fredhopper installation running with a single universe.
• You are familiar with Fredhopper basetypes.
• Every product has at least 1 variant (products with no variants attached will not be shown in a relational universe setup).
• Every variant should have a relation to the main product it belongs to.

Finally, it is recommended to use the Fredhopper Data Manager to create the input XML for products & variants.

Step 1: Prepare related universe data

In a Fredhopper related universe setup the relation from a variant to a product is stored at the variant level. Below is an example of the input XML that Fredhopper requires for a relational universe setup. Generating this XML will not be different than for your current single universe setup (e.g. the XML format is the same).

Example primary universe data

The primary universe product contains the normal attributes, including categories, that belong to the product.

<?xml version="1.0" encoding="UTF-8"?>
<items>
    <item operation="add" identifier="100001">
        <attribute type="asset" identifier="short_description">
            <value locale="en_US">Womens Skirt</value>
        </attribute>
        <attribute type="asset" identifier="description">
            <value locale="en_US">By Morgan. Jagged style hem. Length: 27ins. Washable. Viscose.</value>
        </attribute>
        <attribute type="asset" identifier="name">
            <value locale="en_US">Womens Print Skirt</value>
        </attribute>
        <attribute type="list" identifier="brand">
            <value locale="en_US" identifier="morgan">Morgan</value>
        </attribute>
        <attribute type="hierarchical" identifier="categories">
            <value locale="en_US" identifier="catalog01">catalog01</value>
            <attribute type="hierarchical" identifier="categories">
                <value locale="en_US" identifier="15">Home</value>
                <attribute type="hierarchical" identifier="categories">
                    <value locale="en_US" identifier="15000">Womens</value>
                    <attribute type="hierarchical" identifier="categories">
                        <value locale="en_US" identifier="15095">Skirts</value>
                    </attribute>
                </attribute>
            </attribute>
        </attribute>
    </item>
</items>

Example secondary universe data

The secondary universe variants contains variant specific attributes like price and color. Every product in the primary universe must have at least one variant in the secondary universe. The reference to the primary universe product in which the relation is stored is called "primary_id" and is of Fredhopper basetype "ref". Every product in the secondary variant universe must have a category attribute. The category attribute holds only a reference to the secondary variant universe.

<?xml version="1.0" encoding="UTF-8"?>
<items>
    <item operation="add" identifier="1758493">
        <attribute type="hierarchical" identifier="categories">
            <value locale="en_US" identifier="catalog01related">catalog01related</value>
        </attribute>
        <attribute type="float" identifier="sku_price">
            <value>41.00</value>
        </attribute>
        <attribute type="asset" identifier="sku">
            <value locale="en_US">1758493</value>
        </attribute>
        <attribute type="list" identifier="color">
            <value identifier="red" locale="en_US">Red</value>
        </attribute>
        <attribute type="ref" identifier="primary_id">
            <value locale="en_US">100001</value>
        </attribute>
    </item>
    <item operation="add" identifier="1758494">
        <attribute type="hierarchical" identifier="categories">
            <value locale="en_US" identifier="catalog01related">catalog01related</value>
        </attribute>
        <attribute type="float" identifier="sku_price">
            <value>42.00</value>
        </attribute>
        <attribute type="asset" identifier="sku">
            <value locale="en_US">1758493</value>
        </attribute>
        <attribute type="list" identifier="color">
            <value identifier="green" locale="en_US">Green</value>
        </attribute>
        <attribute type="ref" identifier="primary_id">
            <value locale="en_US">100001</value>
        </attribute>
    </item>
</items>

It is recommended that you generate this XML using the Fredhopper Data Manager.

Step 2: Update Fredhopper configuration with relational universe information

The configuration for the relational universe has to be added manually to the business.xml (C:\fredhopper\data\instances\demo\config\business.xml - this URL may be different on your machine, but please respect the Fredhopper folder hierarchy, there are two business.xml files and you must edit the one in the said directory). This is a one time operation.

1. Open the business.xml and add the following lines just before the closing tag of the primary universe node. In this example the "field-name" is price. This tells Fredhopper to always return the SKU with the lowest price for the selection the user is in.

<universe-refs>
<universe-ref universe="catalog01related" ref-attribute="primary_id">
<selection-criterium field-name="sku_price" display-name="variant_price"
skey="variant_price" universe="catalog01related"></selection-criterium>
</universe-ref>
</universe-refs>

If you are adding a related universe for an additional primary universe, "universe-ref @ref-attribute" must be different for each related universe.  Commonly the values to use are: primary_id_<primary-universe-name>  eg. primary_id_catalog01 , primary_id_catalog02, etc..

If by accident a second universe is present in the data, the expected connection attribute changes from primary_id to primary_id_<primary-universe-name> which breaks the connection between the primary and related universe.

2. Add the variant universe definition to the business.xml just below the primary universe definition but within the universes node of the business.xml

    <universe name="catalog01related">
    <setting name="lister-fields">secondid</setting>
    <setting name="default-sort-order">secondid</setting>
    <setting name="auto-generate-facets">false</setting>
    <setting name="redirect-one-item-facet">true</setting>
    <setting name="theme-fields">secondid</setting>
    <setting name="detail-fields">secondid</setting>
    <setting name="similar-item-fields">secondid</setting>
    <setting name="compare-fields">secondid</setting>
    <setting name="compare-sort-order">secondid</setting>
    <setting name="live-attribute-types"></setting>
    <setting name="show-null-item-attributes">true</setting>
    <facet-ranking method="distribution-of-values" prioritize-enriched="false">
            <method name="distribution-of-values" fallback-method="" prioritize-min="6" prioritize-max="8"/>
    </facet-ranking>
    <themes locale="en_US">
    </themes>
  </universe>

3. You need to ensure that the attribute selection-criterium[@field-name] (price) is part of the live attributes node in the primary universe.

4. Add the variant attributes to the enrich.py so that Fredhopper is aware of all possible attributes as soon as the loaders are started.

After you have added the configuration to your business.xml ensure that the XML is still valid by checking it using an XML validator.

Step 3: Load relational universe data into Fredhopper

Now that the data is generated and the configuration has been adjusted it can be loaded into Fredhopper. In order to load this follow the same steps as you would normally take to reindex Fredhopper with new data with the following exceptions:

1. Ensure that primary universe data is loaded first, before you place any secondary universe XML in the batch directory
2. Only start the the Qserver after all data has been loaded (primary & secondary)
3. Fredhopper detects the new universe automatically when the loaders are started.

Simple example setup

Using the steps described below you will be able to start a minimal related universe setup with the data and configuration used in this article.

1. Ensure you have a clean FAS6.2+ installed. There should be no business.xml or enrich.py in place.
2. Place the business.xmlattached business.xml and enrich.py in the config directory of the Fredhopper installation
3. Place the primary universe products data input file in \data/xml/incoming/batch\
4. Start the Fredhopper loaders (bin/startloader)
5. Place the secondary variant SKU data input file in data/xml/incoming/batch\
6. Check in the xmlloader.log if all file have been loaded. You should see a message like:

   2009-07-13 18:00:30,516 INFO \[xmlloader\] XmlLoaderApp.java:649 50105 Parsing `catalog01related-1.xml
   is done. Details: '2 operations ( add: 2), parse time 24 ms, enrich time 3 ms'
   2009-07-13 18:00:30,516 PROGRESS \[xmlloader\] XmlLoaderApp.java:651 10541 itemstore.size = '3' items.

7. Only after this message appeared you can start the Fredhopper Query Server (bin/qserver)
8. You should now see two facets (color + price) which represent the variants which you are browsing the primary products universe.

Further considerations for related universe setups

In Fredhopper relational universe setups always ensure:

1. Primary universe data (products) are all loaded before the secondary universe (variants) data is loaded. If this order is not followed products might not be loaded in Fredhopper properly.
2. Attributes from the secondary universe cannot be used in free text search, if you want to search these attributes they have to be projected on the primary product.