FAS 8.5 Upgrade Notes

FAS 8.5 APIs are compatible with the previous release.

This release introduces the following major changes:

• Users can define rules which span multiple markets or channels (GA). Requires additional configuration (multi-site.xml).
  The format of multi-site.xml has been changed since FAS 8.4. Any existing files must be re-worked. However, this feature was NOT used in production and should not affect any existing customers.
• Presentation fields are now known as display fields. Display fields are now managed separately and as scoped entities. You can now manage separate Preview and Live configurations for display fields.

Multi-market rules and fields

Customers model a multi-market or multi-channel business one of two ways: through multiple universes or using one universe with multiple market-specific attributes.

For integrations that rely on the single universe model, FAS 8.5 makes it possible to specify the following entities to work across multiple markets or channels:

• Ranking attributes
• Rankings
• Display fields
• Filters in result modification groups*
• Filters in campaigns*
• Sorting fields in campaigns*
• Facets
  * Applicable to all attribute types except list and set.

To enable this feature, the mapping of market-related attributes must be done in a new configuration file multi-site.xml. By default, this file is not included in the site configuration.

FAS 8.5 supports three mapping strategies for this feature: by locale name, by the market selector attribute, or custom mapping.

Note: The format of multi-site.xml has been changed since FAS 8.4. Any existing files must be re-created.

Mapping by locale name

In this strategy, market-specific attributes get the respective locale's country or language name as a suffix. For example, price_gb reflects a price in the UK, while price_ie reflects a price in Ireland.

When mapping by locale name, multi-site.xml has the following contents: <?xml version="1.0" encoding="UTF-8"?>

<config>
    <strategy type="locale">
        <locale-selection>country</locale-selection>
    </strategy>
</config>

When this strategy is applied, the Business Manager displays market-specific attributes such as price_gb and price_ie as one template attribute (for example, price_{locale}). Users will be able to set up a facet, a ranking cocktail, or a ranking using the attribute template. When a locale is specified, FAS substitutes the respective attribute when processing queries.

Alternatively, conflation can be done by the locale's language. The following example declares the multi-site strategy for Belgium, so attributes price_nl and price_fr for Belgium would be resolved to price_{locale}.

If a locale selection is not defined, the system will try to resolve attributes by the whole locale string.

Mapping by market selector attribute

This strategy requires the definition of an attribute of the type set whose values will be used for the conflation and a default value to be used when the query cannot resolve the attribute.

When mapping by market selector, multi-site.xml has the following contents:

<config>
    <strategy type="attribute">
        <attribute name="markets" default-value="en_gb" />
    </strategy>
</config>

In this example, if the markets attribute is not specified in the query, then the en_gb value will be used.

Custom mapping

This strategy relies on a map of custom values. You need to specify a resolver attribute that you will pass in your queries.

When using custom mapping, multi-site.xml has the following contents:

<config>
<strategy type="custom">
   <name>region</name>
   <default-map-value>en_de</default-map-value>
   <values>
      <entry key="en">en_de</entry>
      <entry key="de">en_de</entry>
   </values>
   <resolver type="locale">
      <locale-selection>country</locale-selection>
   </resolver>
</strategy>
</config>

In this example, the system might have a field rating_en_de, and this field will be resolved both for the EN and DE locales.

Improved display fields

FAS 8.5 introduces the following improvements to display fields (formerly presentation fields):

• Display fields are now scoped entities. Their management is now on a separate page (Display fields) under the System tab.
• You can manage a Preview and a Live configuration.<br/>Preview display fields are rendered on the pre-published environment. Live display fields are rendered on the published environment.<br/>Having many preview fields lets merchandisers see more information while testing their configuration. Having a few live display fields ensures improved web page performance.
• Changes to display fields are subject to publication management. Their publication is detached from the publication of other System settings.

FAS renders the secondid of items if no display field lists are defined.

Migration

Migration automatically occurs when upgrading to FAS 8.5.

If upgrading from FAS 7.5.x, the operation will first migrate old rules and then migrate display fields.

IMPORTANT: If upgrading from FAS 8.4, ensure all system settings are published.

For every display fields list, the migration algorithm does the following:

1. Reads the display field universe and locale.
2. Looks for the first scope with matching universe and locale triggers.
3. If there is no exact match for the locale, looks for the first scope with the same universe and wildcard locale triggers that could match.
4. If there is still no match, look for the scope with the same universe, ignoring the locale.
5. If there is still no match, the migration of a particular display fields list does not happen. A warning is logged.

The new Display fields and Presentation pages are visible to any role which had access to at least one of the old Presentation sub-pages.

Example 1

Display fields in a previous FAS version have been declared for catalog01/en_GB, catalog01/de_DE, catalog01/fr_FR, catalog01related/en_GB, catalog01related/de_DE, and catalog01/FR_fr.

FAS has the following scopes structure:

scopes
  |- catalog01
      |- en_US
      |- eb_AU
      |- fr_FR
      |- de_*
      |- facets
         |- fr_FR

In this case:

• Display fields for catalog01/en_GB will be migrated to catalog01 because there is no scope which matches the universe and locale.
• Display fields for catalog01/de_DE will be migrated to catalog01/de_*.
• Display fields for catalog01/fr_FR will be migrated to catalog01/fr_FR and not into catalog01/facets/fr_FR, because the migration happens only to the first scope which matches the lookup criteria.
• Display fields for catalog01related universe will not be migrated because there are no scopes for this universe.

Note: For some customers, display fields might be auto-migrated to scopes which fulfil the universe/locale matching criteria but do not reflect the actual configuration of the customer. In this case, display fields need to be moved to more appropriate scopes using Business Manager or the REST API.

De-duplication

When processing a query, FAS looks at the display field universe and locale and tries to resolve display fields corresponding to this universe and locale. If it is not possible, FAS will check whether display fields are declared on the universe level.

This mechanism can de-duplicate declarations of display fields by declaring them on the universe level instead of duplicating them across several locale levels.

Example 2

The display fields declared in the previous example for the EN, DE and FR locales are essentially the same. You can copy them to the catalog01 scope and remove them from their original scopes. In this case, the system will always use the same display field configuration, disregarding the selected locale.

Example 3

The display fields for the EN and GB locales are the same, but for the FR locale they are different. You can copy the display fields for EN or DE to the catalog01 scope and remove them from their original scopes. You can retain the FR locale configuration on the fr_FR scope level.

FAS will resolve fields for //catalog01/en_GB and //catalog01/de_DE from the catalog01 scope. Fields for //catalog01/fr_FR will be resolved from the catalog01/fr_FR scope. 

Changes in the query language

It is now possible to override default display fields settings and render only secondid.

For more information, see the fh_displayfields_mode parameter in Fredhopper Query Language.

Behaviour changes

FAS 8.5 introduces the following behaviour changes.

Reading localisation files

Localisation files in FAS are located in the config/i18n directory and have the following naming pattern:

localization.<universe>.<locale>.xml (for example, localization.catalog01.en_GB.xml)

In earlier versions, FAS would pick up any localisation file with the name starting with 'localization' and ending with 'xml'. In some cases, this resulted in FAS picking up the wrong localization file (for example, when old copies of the same localisation file copy were stored in the same place).

Starting with FAS 8.5, the correct localisation file will be applied.

IMPORTANT: The manual editing of localisation files and storing old copies in the i18n folder is strongly discouraged.

Default selection with a non-existing attribute value

It is possible that a default selection declares a range using an attribute value which no longer exists in the system.

Previously, the system threw an error. Currently, the system ignores the invalid attribute value (while applying other default selection criteria) and logs a warning with id 40416.

Changes in default system settings (system.xml)

Some default settings have changed values or were renamed. It might impact the system behaviour after the upgrade.

Setting: com/fredhopper/config/ShadowingCopy@mode

Change: standalone -> <removed>

Impact: Shadowing copy is the only mechanism to back up configuration until now, so the system setting was cleaned up.