The following objects are used when creating a federated connector for Perceptive Enterprise Search.
The federator object is the base object that you extend when creating a federated connector. Then is only a single method that you must implement, Execute. All other methods are optional.
bool Federator.Execute(ISYSFederatorRequest Request, ISYSFederatorResponse Response);
The Execute method must be implemented by all federator connectors. Execute is called to pass the translated query to the remote system, it must wait for the response before translating it and returning it to Perceptive Enterprise Search. The Request object contains information about the search including the original query, the translated query and any configuration properties. The Response object is used to build up the data that is to be returned to Perceptive Enterprise Search.
bool Federator.DownloadDocument(ISYSFederatorRequest Request, Stream Dest);
The DownloadDocument method is optional, it allows you to provide special handling for Perceptive Enterprise Search to be able to download and return the binary document of a search result. The Request method contains the details of the document being requested, with the result being pushed in the Destination Stream.
If the method is not implemented, Perceptive Enterprise Search will attempt to download the document using the URL property of the document.
void Federator.Prepare(ISYSFederatorRequest Request);
The prepare method is called prior to the Execute method. It gives you an opportunity to validate the configuration options. The prepare method is also called during connector configuration, any exception raised here will be shown in the configuration wizard.
ISYSFederatorRequest Request { get; }
The Request property gives you access to the current Request object.
QueryTranslator Translator { get; }
The Translator property gives you access to the current Translator object being used for this request.
The ISYSFederatorRequest object is passed to the Execute, DownloadDocument and Prepare methods. It contains information about the current action being executed, including the Query, and configuration options and document information.
String GetProperty(string name)
Returns the property with the give name, the property name should match the name published in the configuration XML file.
ISYSFederatorQuery Query { get; }
Returns an object containing both the translated query and the raw uninterpreted query. To access the translated query, call Query.ToString();
int RangeStart { get; }
Returns the index of the first item being requested starting from 1. As users navigate through the pages of results, you will get subsequent requests with this number growing.
int RangeEnd { get; }
Returns the index of the last item being requested.
String GetMetaData(string name);
Returns the metadata element with the given name from the current document. Use this method to find out about the document being requested in the call to DownloadDocument.
The response object collects information about the results to push back the Perceptive Enterprise Search. You need to add one result for each item. Where possible, you should also set the total count to enable search results to be paged.
int Total { get; set }
The Total property represents the total number of search results found by the remote system. If you set this value, Perceptive Enterprise Search will automatically page the results for you. If the total is not set, you will only be able to see one page of results.
int Count { get; }
Returns the number of items currently in the result for this instance.
ISYSFederatorResponseItem CurrentItem { get; }
Returns the reference to the last item added to the response.
ISYSFederatorResponseItem AddResult();
Adds a new result item to the response and returns its reference. You can gain access to the last added item using the CurrentItem property.
The ISYSFederatorResponseItem is returned from the ISYSFederatorResponse object and represents a single item in the result list. You must populate the data in this object for each item you wish to appear in the result list.
void SetAttribute(String name, String value)
Use SetAttribute to publish information about a document. There are a fixed set of “known†attributes that automatically get mapped into Perceptive Enterprise Search properties. You can gain access to these using the Attributes object.
Available attributes are:
Attributes.Title | Value is shown as the title in the result line. |
Attributes.Filename | Value is shown as the item’s filename |
Attributes.Size | Value is shown as the item’s file size, should be stored as number of byte. |
Attributes.Category | Value is shown as the item’s category, collation of categories will also be done of this value. |
Attributes.FileType | Value is shown as the item’s file type. |
Attributes.Date | Value is shown as the item’s timestamp. |
Attributes.URLBinary | Indicates the location of the binary document, setting this property allows you to omit the DownloadDocument method. |
Attributes.URLText | Indicates the text only view of the document. |
Attributes.Summary | Value is shown as the contextual snippet in the result list. |
Attributes.HREF | Indicates the location of the file. |
If you wish to publish information above and beyond these attributes, you can use AddMetaData.
string GetAttribute(String name)
Returns the attribute with the given name.
void AddMetaData(String name, String value)
Allows you to add information about the document outside of the attributes published above. The metadata is available on the Document Details page, or you can add it to the result list using the {MetaValues …} tag.
The query translator object is used to help translate queries from Perceptive Enterprise Search syntax into a format understood by the federated system. The default translator handles simple mapping for you, loading operator information from the connector configuration file.
You can override certain aspects of the query translator if the query syntax of the federated system is more complex than can be achieved using the simple mapping.
To create your own QueryTranslator, you must create a new class that extends the QueryTranslator class; you then specify your class in the constructor of the connector. You can override any of the following methods:
string QueryTranslator.GetWord(string token)
Called for each no operator in the search allowing you to do extra processing on each token.
Example: CAT and DOG not FISH
string QueryTranslator.GetPhrase(string phrase)
Called for each phrase in the search allowing you to perform
extra processing, for example, you may need to return the value quoted:
Example: SOFTWARE INSTALLATION not DOWNLOAD
string QueryTranslator.GetProximity(string operator, string distance, string left, string right)
Called to handle proximity searches, the operator will be one of the following:
… | Documents must contain the left token followed anywhere by the right token. |
.. | Documents must contain the left token followed by the right token in the same paragraph. |
\\ | Documents must contain both the left and right token in the specified number paragraph, order is not important. A number mentioned between the slashes indicates the number of paragraphs apart the two expressions can be. |
// | Documents must contain both the left and right token in the same paragraph, order is not important. A number mentioned between the slashes indicates the number of words apart the two expressions can be. |
Example: TAX // RATES NOT 2004
string QueryTranslator.GetFielded(string field, string value)
Called to handle fielded searches, where the search expression should be constrained to a particular field.
Example: JOHN CITIZEN in AUTHOR
string QueryTranslator.GetFilter(string filter, string value)
Called to handle filter expressions entered into the search, Perceptive Enterprise Search supports specifying the following filters:
FNAMELIKE, FNAMEUNLIKE, PATHCONTAINS, PATHOMITS, CATEGORYLIKE, CATEGORYUNLIKE, FILEDATEBEFORE, FILEDATEAFTER, INDEXEDBEFORE, INDEXEDAFTER, FIRSTDATEBEFORE and FIRSTDATEAFTER.
Example:
TAX // RATES NOT 2004 FNAMELIKE *.doc
string QueryTranslator.GetRange(string operator, string value)
Called to handle numeric or alphanumeric range searches, such as GE and LE.
Example: TAX // RATES AND GE 2005
string QueryTranslator.GetOperator(string operator, string left, string right)
Called to handle Boolean operators such as AND, OR and NOT.