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:

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.

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 guidelines 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 Attraqt if you would like to know about the compatibility of Fredhopper versions with specific custom components.