XML endpoint

Introduction

search.xml provides a REST style API to the Funnelback Modern user interface. It allows developers to integrate Funnelback results into their applications by making HTTP GET calls to search.xml and wrapping the resulting XML response.

There is also a Modern UI entry point that emulates the XML format of the Classic UI: search.classic.

Getting XML Results from search.xml

The following sections give details on how to get results from search.xml.

Query string parameters

search.xml will support the same parameters accepted by the HTML Modern search interface (search), as well as query string parameters accepted directly by the PADRE query processor. Please see the following documents for a list of these parameters:

At a minimum you will need:

query: Query terms
collection: The name of the collection to query

Construct a query URL to the live Funnelback search service

If the search service resides at +http://company.com/s/search.xml + and the query parameters passed into the wrapper script by the user were

query = leave form
collection = intranet

then the search URL will be +http://company.com/s/search.xml?query=leave+form&collection=intranet +

Fetch the XML results

Fetching the XML results is as simple as making an HTTP GET request at the URL constructed in the step above. How to do this depends on which language your wrapper script is in. In pseudocode, this could be done as:

query = "http://company.com/s/search.xml?query=leave+form&collection=intranet"
xml = http_get(query)

Displaying the Results

Once you have the XML results you can perform whatever processing you wish on them, like displaying the results in a web page, or un-marshall them into Java objects.

Render the search results in HTML

It’s up to you how to present your results, but there are a few things to keep in mind:

Cached links

The cached result URLs returned in the XML are only absolute if the collection’s ui_cache_link configuration setting is being used to point users back to an alternative server that stores the cached pages. When this is the case, the cached result link can be used as is.

In all other cases, the cached result link URLs are not absolute. For example,

<cacheUrl>cache?collection=intranet&amp;doc=http://company.com/forms/leave_form.htm<cacheUrl>

This means that you must:

prefix them with the Web server and path of the live Funnelback service, or
develop a custom wrapper that will fetch the cached results page, or
not display the cached result links.

Note that this also applies to the click links (/s/redirect) generated in the <clickTrackingUrl> element if the collection has click tracking enabled.

Pagination

The next and previous result page links (e.g. _Previous 1

Next_) are not explicitly included in the XML. This means that you will need to use the information provided in the <resultsSummary> element to construct these links yourself. For example, the <resultsSummary> element might look like:

<resultsSummary>
  <fullyMatching>30</fullyMatching>
  <estimatedHits>30</estimatedHits>
  <partiallyMatching>0</partiallyMatching>
  <totalMatching>30</totalMatching>
  <numRanks>10</numRanks>
  <currStart>1</currStart>
  <currEnd>10</currEnd>
  <nextStart>11</nextStart>
</resultsSummary>

Each time a next or previous page link is clicked, a new query needs to be submitted to Funnelback. The query string parameters start_rank and num_ranks can be used to indicate which page of results should be presented to the user. For example, if twenty results are displayed per page of results and the user wishes to see the third page of results, the start_rank parameter will need to be 41 (the first forty are display on the first two pages). The URL for the third page of search results would look like:

http://company.com/find.asp?collection=intranet&query=leave+form&start_rank=41&num_ranks=20

The num_ranks parameter defaults to 10 when not specified. A quick calculation using the value of the <totalMatching> element and the <numRanks> element will determine how many results page links need to be displayed. Generally, no more than ten result page links are displayed at the bottom of the results page. If required, the user can continue to navigate through the results using the Next and Previous links which point to the results pages starting at <currStart> + <numRanks> and <currStart> - <numRanks> respectively.

Spelling

If you wish to display query spelling suggestions on the results page you will need to construct the link and Did you mean… text based on the content of the <spell> element. For example, the <spell> element might look like:

<spell>
  <url>collection=intranet&query=funnelbeck%20search%20engine</url>
  <text>funnelback search engine</text>
</spell>

The <url> element contains the query string that can be used to submit the suggested query. Note that the <url> needs to be prefixed with the URL of your XML search wrapper.

The <text> element provides a human readable version of the suggested query for use in the Did you mean … ? link text.

Results from the Contextual Navigation system will also be available in the search.xml output if Contextual Navigation has been enabled. Some typical results might look like:

<contextualNavigation>
    <searchTerm>index</searchTerm>
    <clusterNav>
        <level>0</level>
        <url>collection=funnelback_documentation&profile=_default&query=index</url>
        <label>index</label>
    </clusterNav>
    <categories>
        <com.funnelback.publicui.search.model.padre.Category>
            <name>type</name>
            <more>0</more>
            <clusters>
                <com.funnelback.publicui.search.model.padre.Cluster>
                    <href>?clicked_fluster=spelling+index&cluster0=index&query=%60Spelling+Index%60&collection=funnelback_documentation&profile=_default
                    </href>
                    <count>6</count>
                    <label>Spelling...</label>
                    <query>Spelling Index</query>
                </com.funnelback.publicui.search.model.padre.Cluster>
                [...]
            </clusters>
        </com.funnelback.publicui.search.model.padre.Category>
        <com.funnelback.publicui.search.model.padre.Category>
            <name>topic</name>
            <more>0</more>
            <clusters>
                <com.funnelback.publicui.search.model.padre.Cluster>
                    <href>?clicked_fluster=data+in+index&cluster0=index&query=%60data+in+index%60&collection=funnelback_documentation&profile=_default
                    </href>
                    <count>8</count>
                    <label>Data in...</label>
                    <query>data in index</query>
                </com.funnelback.publicui.search.model.padre.Cluster>
                [...]
            </clusters>
        </com.funnelback.publicui.search.model.padre.Category>
    </categories>
    <customData />
</contextualNavigation>

Here, the <clusterNav> elements show the current browsing history (which clusters have been selected so far), and the <com.funnelback.publicui.search.model.padre.Cluster> elements contain lists of suggestions for further query options wrapped in <clusters> elements.

Go-live

After testing the wrapper script thoroughly, modify your search form to point at the wrapper. In most cases this will mean changing the ACTION parameter to point to the URL of your search wrapper (e.g. +http://company.com/find.asp +) instead of the live Funnelback service.

Un-marshall the XML results into Java objects

The search.xml XML feed is the result of marshalling Java objects into XML using the XStream library. The reverse operation can be achieved to convert the XML feed into Java objects using the same library.

Please find below a code example to do so. You’ll need to have the JAR file containing the Funnelback classes ($SEARCH_HOME/lib/java/publicui/publicui-core-<VERSION>.jar) in your classpath:

import com.funnelback.publicui.search.model.transaction.*;
import com.funnelback.publicui.search.model.padre.*;

// Fetch the results using an HTTP Get method
String xml = httpGetResults("http://company.com/s/search.xml?collection=intranet&query=leave+form");

XStream xstream = new XStream();
SearchTransaction st = (SearchTransaction) xstream.fromXML(xml);
SearchResponse response = st.getResponse();

System.out.println(response.getResultPacket().getResultsSummary().getFullyMatching() + " results found");

for (Result r: response.getResultPacket().getResults()) {
  System.out.println("Result " + r.getRank() + " is: " + r.getTitle());
}

Help Center

Menu