exteNd 5.2.1 Documentation Addenda

Changes to the Autonomy Search Engine

Autonomy-based search technology provides conceptual and keyword searching in exteNd Director applications. exteNd Director 5.2.1 incorporates a new version of the Autonomy search engine called Suir Server version 5.0, which is part of the Autonomy IDOL search engine product suite. The Suir Server replaces Autonomy DRE Server version 3.x, the server supported by earlier versions of exteNd Director.

This document describes the differences between the DRE and Suir Servers, and explains how to install, configure, and use the upgraded search engine. Topics include:

Summary of changes

Here is a summary of changes to Autonomy-based searching in exteNd Director 5.2.1 as a result of upgrading to the Suir Server:

The installation process is simpler, especially on UNIX platforms. See Installing the Autonomy Suir Server.
The default query and index ports have changed. See New defaults for query and index ports. You can use these new port numbers to verify the status of the Suir Server, as described in Verifying server status.
The Suir Server now processes custom fields automatically, as described in Processing custom fields.
exteNd Director 5.2.1 ships with new Autonomy documentation. See Getting help on the Autonomy Suir Server.
Information in the exteNd Director Content Search Guide that references the Autonomy DRE Server is obsolete. See Backward compatibility.

Installing the Autonomy Suir Server

This section explains how to install the Suir Server on supported platforms. The information in this section supersedes conflicting install instructions in the chapter Configuring Your Environment for Conceptual Searching in the exteNd Director Content Search Guide.

Installing the Suir Server on Windows machines

The Suir Server is installed with exteNd Director and launched automatically as a Windows service called DirectorSuir when you start up your machine. The display name of the service is exteNd Director Suir.

To complete the installation, follow these steps:

Add autonomyJNI.jar to your classpath.
Add the native library autonomyJNI.dll to your runtime environment.

For detailed instructions, see the section on adding the Autonomy dynamic library to your environment in the chapter Configuring Your Environment for Conceptual Searching in the exteNd Director Content Search Guide.

Suir executable file on Windows

The executable file is DirectorSuir.exe, located in:

  exteNd install directory/Director/autonomy/engine

Installing the Suir Server on UNIX machines

The Autonomy search engine is now installed automatically on Linux and Solaris servers when you install exteNd Director 5.2.1. You no longer need to run a setup script.

To complete the installation, follow these steps:

Add autonomyJNI.jar to your classpath.
Add the native library libautonomyJNI.so to your runtime environment.

For detailed instructions, see the section on adding the Autonomy dynamic library to your environment in the chapter Configuring Your Environment for Conceptual Searching in the exteNd Director Content Search Guide.

Install directory structure

The directory structure for the Autonomy search engine has been reconfigured to match the one provided for Windows. The root installation folder is:

  exteNd install directory/Director/autonomy

This folder contains:

Scripts for starting and stopping the search engine
JNI files used by exteNd Director to interoperate with Suir
engine subfolder, which contains Autonomy search engine executables
OmniSlaves subfolder, which contains the executables and files used to import documents into the search engine

Suir executable file on UNIX

The executable is DirectorSUIR.exe, located in:

  exteNd install directory/Director/autonomy/engine

Starting and stopping Suir on UNIX

To start the Suir Server on a Unix machine, execute the startSUIR.sh script. This script launches the server as a Unix daemon. You can stop the running server by running the stopSUIR.sh script. These scripts reside in the root installation folder:

  exteNd install directory/Director/autonomy

New defaults for query and index ports

The default ports for the search engine have changed as follows:

Port	Old Default	New Default
Query port	2000	52000
Index port	2001	52001

Reconfiguring query and index ports

To change the ports for the search engine, you must modify them in two locations:

Modify the query and index port numbers in the exteNd Director project

For detailed instructions, see the sections Query Port and Index Port in the chapter Search Options Reference in the exteNd Director Content Search Guide.
Modify the query and index port numbers in the Suir Server configuration file:
```
  exteNd install directory/Director/autonomy/engine/DirectorSuir.cfg
```

Verifying server status

You can verify Suir Server status by:

Querying the Suir Server port

You can query the Suir Server using the Autonomy JNI API.

To query the Suir Server port, enter this URL in your browser:

  http://server name:Suir Server port/qmethod=v

By default, the Suir Server runs on port 52000, specified as QUERYPORT in the Suir Server configuration file, located in:

  exteNd install directory/Director/autonomy/engine/DirectorSuir.cfg

Here is an example of the status information you receive when you query the Suir Server port:

statusDisplay

Querying the Autonomy Content Infrastructure (ACI) interface port

The ACI interface is a new API included with the Suir Server. This interface contains a set of HTTP commands that provide new query functionality for communicating with the Suir Server. You can use ACI commands in place of the HTTP commands used by the Autonomy JNI API, such as the qmethod commands. The Suir Server continues to support the JNI API.

NOTE: exteNd Director does not use the new ACI API or ACI HTTP commands internally. Instead, it continues to use the Autonomy JNI API which uses the qmethod HTTP commands.

Querying the ACI interface port

To query the ACI interface port, enter this URL in your browser:

  http://server name:ACI interface port/action=GetStatus

By default, the ACI interface uses port 52003, specified as PORT in the Suir Server configuration file:

  exteNd install directory/Director/autonomy/engine/DirectorSuir.cfg

Here is an example of the status information you receive when you query the ACI interface port:

statusDisplayACI

Getting help on using the ACI

The following URLs provide help on using the ACI:

To learn about:	Use this URL:
Using ACI HTTP commands	http://host name:ACI port/action=Help For example, if your host is MyHost using the default ACI port, enter this URL: http://MyHost:52003/action=Help
Configuring ACI	http://host name:ACI port/action=confighelp For example, if your host is MyHost using the default ACI port, enter this URL: http://MyHost:52003/action=confighelp
Issuing HTTP queries using ACI	http://host name:ACI port/action=Query&Text=search phrase For example, if your host is MyHost using the default ACI port and your search phrase is Human Resources, enter this URL: http://MyHost:52003/action=Query&Text=Human Resources To learn more about query syntax, refer to Autonomy help and documentation, as described in Getting help on the Autonomy Suir Server.

To learn about:

Use this URL:

Using ACI HTTP commands

http://host name:ACI port/action=Help

For example, if your host is MyHost using the default ACI port, enter this URL:

  http://MyHost:52003/action=Help

Configuring ACI

http://host name:ACI port/action=confighelp

For example, if your host is MyHost using the default ACI port, enter this URL:

  http://MyHost:52003/action=confighelp

Issuing HTTP queries using ACI

http://host name:ACI port/action=Query&Text=search phrase

For example, if your host is MyHost using the default ACI port and your search phrase is Human Resources, enter this URL:

  http://MyHost:52003/action=Query&Text=Human Resources

For more information To learn more about query syntax, refer to Autonomy help and documentation, as described in Getting help on the Autonomy Suir Server.

Processing custom fields

The Autonomy Suir Server streamlines the process of indexing custom fields. exteNd Director supports several types of custom fields for describing documents stored in the content repository:

Metadata fields that ship with exteNd Director, such as Author, Title, Subtitle, and Abstract
User-defined fields

The following sections describe how the Suir Server processes metadata fields and user-defined fields for searching.

Indexing metadata fields

Metadata fields are now indexed automatically and incorporated into query results.

To speed up the index process and optimize disk space, you can prevent one or more metadata fields from being indexed, as described in Excluding custom fields from the index process.

Indexing user-defined fields

User-defined fields are now indexed automatically for searching. You no longer need to restart the server to make sure that the Autonomy search engine adds the values of the new fields to the index store.

However, user-defined fields are not automatically incorporated into query results. This means that when you search for documents that contain specific user-defined field values, the query returns the expected documents, but does not list the user-defined fields in the query results.

You specify the fields to include in query results by editing a results template located in:

  exteNd install directory/Director/autonomy/engine/templates/resultsbody.txt

By default, the results template contains Autonomy-defined fields and the exteNd Director metadata fields. These fields will automatically appear in query results. To include your own custom fields in query results, you need to add them to the template, as follows:

Open the results template in your favorite text editor:

The results template is located in:
```
  exteNd install directory/Director/autonomy/engine/templates/resultsbody.txt
```

Add a descriptor entry for your custom field.

For example, if you defined a custom field called REFERENCEDBY, add a descriptor that looks something like this:

  REFERENCEDBY=<!-- ATNMY_FIELD MATCH="*/REFERENCEDBY" TRIM="1" ESCAPE="0" -->

In this example, the descriptor contains the following additional parameter settings:

Parameter	What it means
TRIM	Controls line break characters: 1 = Remove line break characters from the results (default) 0 = Do not remove line break characters from the results
ESCAPE	Determines whether to escape special characters: 1 = Escape special characters according to XML rules—for example, & becomes & (default) 0 = Do not escape special characters

Parameter

What it means

TRIM

Controls line break characters:

1 = Remove line break characters from the results (default)
0 = Do not remove line break characters from the results

ESCAPE

Determines whether to escape special characters:

1 = Escape special characters according to XML rules—for example, & becomes & (default)
0 = Do not escape special characters

For more information about template descriptors and syntax, see the Autonomy IDOL Server Administrator's Guide, installed with exteNd Director 5.2.1, as described in Getting help on the Autonomy Suir Server.

Save the results template file.
Force the Suir Server to read the changes in the template by using one of the following methods:
- In the DRE Administration tool, select the Advanced tab and click Reset DRE.
- Issue the HTTP RESET command via the index port using the following URL:
```
  http://host name:index port/DRERESET
```
- Stop and restart the server.

Excluding custom fields from the index process

To speed up the indexing process and conserve disk storage, you can prevent the Suir Server from indexing custom fields that you do not intend to search on in a field query. The Suir Server uses a configuration parameter called CantHaveFieldCSVs to specify which fields should not be indexed. The parameter is located in the Server section of the Suir Server configuration file:

  exteNd install directory/Director/autonomy/engine/DirectorSuir.cfg

To prevent a field from being indexed, follow these steps:

Open the Suir Server configuration file.
Search for the parameter CantHaveFieldCSVs.
Append the field to the comma-separated list of values for CantHaveFieldCSVs.

For example, suppose you define a custom field called CITATIONS. By default, this field will be indexed for searching. To prevent it from being indexed, add the custom field to the CantHaveFieldCSVs descriptor, as in this example:
```
  CantHaveFieldCSVs=*/CHECKSUM,*/DREWORDCOUNT,*/CITATIONS
```
Force the Suir Server to read the changes in the configuration file by using one of the following methods:
- In the DRE Administration tool, select the Advanced tab and click Reset DRE.
- Issue the HTTP RESET command via the index port using the following URL:
```
  http://host name:index port/DRERESET
```
- Stop and restart the server.

Requirements for naming custom fields

The Suir Server requires that custom field names contain only alphanumeric characters and underscores, but no other punctuation or embedded spaces.

Getting help on the Autonomy Suir Server

There are several ways to get help on how to use the Autonomy Suir Server:

Read the Autonomy IDOL Server Administrator's Guide, installed with exteNd Director 5.2.1 at the following location:
```
  exteNd install directory/Docs/help/Autonomy
```
NOTE: The IDOL Server Administrator's Guide also contains information about the Nore, Laune, and DiSH servers, but these are not used by exteNd Director 5.2.1.

Access Autonomy online help by querying a running server, as follows:

To access	Use this URL:
Autonomy Suir Help Pages	http://server name:Suir Server port/qmethod=H TIP: For example, if your server is called MyServer running on the default Suir Server port, the URL is: `http://MyServer:52000/qmethod=H`
Suir Server 5.0 Help Action List	`http://`server name`:`ACI interface port`/action=Help` TIP: For example, if your server is called MyServer running on the default ACI interface port, the URL is: `http://MyServer:52003/action=Help`

To access

Use this URL:

Autonomy Suir Help Pages

http://server name:Suir Server port/qmethod=H

TIP: For example, if your server is called MyServer running on the default Suir Server port, the URL is: http://MyServer:52000/qmethod=H

Suir Server 5.0 Help Action List

http://server name:ACI interface port/action=Help

TIP: For example, if your server is called MyServer running on the default ACI interface port, the URL is: http://MyServer:52003/action=Help

Backward compatibility

This section describes backward compatibility issues you may encounter when you upgrade from previous versions of exteNd Director.

Support for Autonomy DRE Server

This section describes how exteNd Director 5.2.1 handles previously installed Autonomy DRE Servers on Windows and UNIX platforms.

Support for Autonomy DRE Server on Windows

On Windows platforms, exteNd Director 5.2.1 automatically launches the Autonomy search engine as a service called exteNd Director Suir on startup. In previous exteNd Director versions, the service was called exteNd Director DRE.

The exteNd Director 5.2.1 installer disables exteNd Director DRE services it detects, but does not remove them. You can run exteNd Director Suir and exteNd Director DRE services simultaneously as long as they use different ports. However, both services run on the same port by default so you must reconfigure one of the installations before running both search engines on multiple versions of exteNd Director on a single machine. For instructions, see Reconfiguring query and index ports.

You can safely remove the exteNd Director DRE service when you no longer need earlier versions of exteNd Director.

Support for Autonomy DRE Server on UNIX

The exteNd Director 5.2.1 installer does not stop Autonomy DRE Servers on UNIX platforms. It is recommended that you terminate any running queryh processes once you no longer require the earlier version of the Autonomy search engine.

Support for Autonomy DRE Administration Tool

exteNd Director 5.2.1 continues to include the Autonomy DRE Administration Tool on Windows because it can be used with a local Suir Server and with a Suir Server running on a remote UNIX machine.

The DRE Administration Tool no longer provides an Import tab.

exteNd Director Content Search Guide

The information in this document supersedes conflicting information in the exteNd Director Content Search Guide as follows:

The instructions in Installing the Autonomy Suir Server supersede conflicting install instructions in the chapter Configuring Your Environment for Conceptual Searching in the exteNd Director Content Search Guide.
The default ports for the search engine have changed as described in New defaults for query and index ports. Sections of the exteNd Director Content Search Guide may display the old default port numbers. All other instructions on configuring the search engine are correct in the chapter Configuring Your Environment for Conceptual Searching.

To change ports, see Reconfiguring query and index ports.