Skip to main content

Installing Custom Components into Fredhopper

Rumyana Grigorova
  • Updated

    The Fredhopper query Server is extensible using "custom components", which are delivered as additional .jar files.

    This page describes how to install these components.

     

    Introduction

    Custom components are (usually) delivered as JAR (Java ARchive) files, and must be deployed into the Fredhopper Query Server before they can be configured and used.

    Custom components are used to extend the functionality of the Fredhopper Query Server. Many "standard" extensions exist, but Fredhopper can also develop extensions for specialized use cases.

    Types of Custom Components

    Different types of custom components exist, the table below contains the commonly used types:

    Type Description/Use Example
    Analyzer Support for new languages in search product codes, stemming
    Campaign Filter Support for additional types of business rules in campaigns filter by URL parameters or database lookups
    Attribute Function Calculate item attributes for navigation and display based at runtime display and sort by distances
    Web Service Extensions Modify the Fredhopper response space management
    Query Rewriting Augment a query with additional parameters mod_rewrite-like functionality, additional triggers based on external systems
    Listeners React on events in the request monitor operational parameters

    Deployment

    The Fredhopper Query Server has a special directory for deploying the JAR files called custom. The contents of the files in this directory (Java Classes, Resources) are available in the query server.

    Most components also require configuration settings, typically in the config/business.xml configuration file. Not all custom components can be configured using the Fredhopper Business Manager.

    Type Configuration
    Analyzer config/business.xml and Business Manager (System > Search > Linguistic Analyzers)
    Campaign Filter config/business.xml and REST API, Business Manager configurability depends on filter
    Attribute Function config/business.xml only
    Web Service Extensions config/ws-extensions.xml
    Query Rewriting config/ws-extensions.xml
    Listeners depends on the listener

    Custom components are always deployed into a Fredhopper instance, and are considered part of the business configuration.

    Capturing Configuration
    Currently the custom component JAR files are not in all cases included when taking a capture of a Fredhopper instance. The JAR files can be copied from a running system without interfering with the live query servers.

    Note that it is generally not possible to deploy different versions of the same component into a single Fredhopper instance.

    Example Step-By-Step Instructions

    The following steps are needed to deploy a custom attribute function called 'distance' into a Fredhopper environment. The environment contains an indexer called 'indexer' (on host 'indexerhost'), and two live instances 'live1' and 'live2' ('live1host' and 'live2host', respectively).

    The component is delivered in the 'distance-function-1.0.jar' file, and requires configuration changes in the config/business.xml file.
    The JAR file is already downloaded into the fredhopper-releases directory on the indexing instance.

    Fredhopper delivers installation instructions together with any custom component, the steps below should serve as an example and general guide lines only.

    Please make sure to follow the installation instructions for the specific component carefully.

    Step 1: Deploy the JAR file

    The first step is to make the classes and resources of the custom component available in all query servers. This requires copying the JAR file to the right place, and restarting the qserver process.

    Analyzers
    Some components such as custom analyzers also affect the indexers, and may require additional steps such as reindexing before they can be used.
    1. Change to the fredhopper installation directory 
      $ cd /home/fredhopper
    2. Copy the function to the indexer instance using the deployment agent 
      $ bin/deployment-agent-client --location indexerhost put --instance indexer fredhopper-releases/distance-function-1.0.jar custom/distance-function-1.0.jar
    3. Copy the function to the first live query server 
      $ bin/deployment-agent-client --location live1host put --instance live1 fredhopper-releases/distance-function-1.0.jar custom/distance-function-1.0.jar
$ bin/deployment-agent-client --location live1host invoke live1 qserver stop
$ bin/deployment-agent-client --location live1host invoke live1 qserver start -Drole=live
      Role
      The -Drole=live parameter is important to ensure that the query server is running as a live query server.
    4. Copy the function to all other live query servers 
      $ bin/deployment-agent-client --location live2host put --instance live2 fredhopper-releases/distance-function-1.0.jar custom/distance-function-1.0.jar
$ bin/deployment-agent-client --location live2host invoke live2 qserver stop
$ bin/deployment-agent-client --location live2host invoke live2 qserver start -Drole=live

      This step needs to be repeated for each live instance as defined in config/topology.txt. Replace 'live2' and 'live2host' with the correct values.

    Restart
    Note that the live servers are restarted immediately so that they will have the function available as soon as the configuration is published.

    It is safe to copy the JAR file into the instance while processes like qserver are running, but the function will not be available until the relevant processes are restarted.

    Step 2: Configure the Indexer business.xml

    Make sure that the indexer query server is stopped and that you have a backup of the config/business.xml before editing the file. Errors in editing may prevent the query server from working correctly.
    1. Log into 'indexerhost'.
    2. Stop the indexer query server 
      $ bin/deployment-agent-client invoke indexer qserver stop
    3. Open config/business.xml in an editor
      The business.xml file resides in the config directory of the 'indexer' instance: 
      $ vi data/instances/indexer/config/business.xml
    4. Add the following snipped in the existing <attribute-functions> element: 
      <attribute-function>
  <setting name="id">distance</setting>
  <setting name="class">com.fredhopper.projects.functions.DistanceFunction</setting>
</attribute-function>
    5. Save the config/business.xml configuration file
    6. Start the indexer query server again 
      $ bin/deployment-agent-client invoke indexer qserver start

    Step 3: Publish the configuration

    The new configuration will be available on the indexer query server only until it is published to the live query servers. Before publishing you should make sure that everything works as intended.

    Changing Other Configuration Settings
    You can also change other settings (for example adding the function as display field), but you should avoid making many unrelated changes (for example adding campaigns) as it will be harder to rollback in that case.
    1. Open the Fredhopper Business Manager using any supported web browser
    2. File the configuration
    3. Publish the configuration
    4. Wait until the configuration is available on the live query servers (typically 10-15 minutes)

    Limitations

    Upgrades

    Any custom component is only compatible with a specific Fredhopper version. A newer version may already contain the functionality delivered by the component, and an older version may not provide the necessary interfaces.

    Upgrading to a different Fredhopper version therefore requires that all custom components are upgraded or replaced at the same time.

    Contact Fredhopper if you would like to know about the compatibility of Fredhopper versions with specific custom components.

    Related articles

    Comments

    0 comments

    Article is closed for comments.