OpenSearch

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

OpenSearchWeb Scripts2.1
Welcome to the Alfresco OpenSearch WIKI.

Back to HTTP API.

NOTE:

This document describes features to be found in Alfresco v2.1 onwards.

Documentation for OpenSearch in Alfresco v2.0 can be found here.

Table of Contents

• 1 Introduction


• 2 Alfresco Keyword Search
  
  
  
  • 2.1 Example Responses
  
  
  • 2.2 Description Document
  
  


• 3 Search Engine Registry
  
  
  
  • 3.1 Auto-discovery of Search Engines
  
  
  • 3.2 Search Alfresco with FireFox 2 and Internet Explorer 7
  
  
  • 3.3 Registering new Search Engines
  
  
  • 3.4 Example Search Engine Registrations
  
  


• 4 Alfresco Proxy Search

Introduction

OpenSearch is a collection of simple formats for sharing of search results, extending existing schemas such as ATOM and RSS. Execution of searches is supported via HTTP requests and responses.

OpenSearch comprises of:

• Description documents that describe the availability of a search engine
  
• Template Urls that describe how to invoke a search
  
• Paged search results in (extended) ATOM, (extended) RSS and HTML
  
• Auto-discovery of Description documents
  

Alfresco exposes its search engines via OpenSearch and also provides a new aggregate open search feature in the Alfresco Web Client.

Alfresco OpenSearch engines

• Keyword (Google-like) search as available in Alfresco Web Client
  

Alfresco Web Client aggregate OpenSearch

Sidebar Query:

• Sidebar Query
  

Dashboard Query

• Dashboard Query
  

Note: For details on general OpenSearch support such as Authentication, Response Formats and Logging see Web Scripts Framework.

Note: Advanced Web Client Search and Query Language searches will be OpenSearch enabled some time in the future, probably in line with up-and-coming CM standards.

Alfresco Keyword Search

This search mimics the keyword search of the Alfresco Web Client.  Documents containing the specified keywords in their name or content are returned.

The search URL template is:

http://<host>:<port>/alfresco/service/api/search/keyword?q={searchTerms}&amp;p={startPage?}&amp;c={count?}&amp;l={language?}

where:

• searchTerms = keyword or keywords to search with
  
• startPage (optional) = the page number of search results desired by the client
  
• count (optional) = the number of search results per page (default: 10)
  
• language (optional) = the locale to search with (XML 1.0 Language Id e.g. en-GB)
  

Response Formats:

• html (default)
  
• atom
  
• rss
  

Example Responses

ATOM

Raw data representation of the result set - useful for custom display rendering and aggregation of multiple result sets.

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:opensearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:relevance='http://a9.com/-/opensearch/extensions/relevance/1.0/'>
  <generator version='2.0.0 (dev @build-number@)'>Alfresco (Community Network)</generator>
  <title>Alfresco Search: alfresco tutorial</title>
  <updated>2006-12-20T13:43:40GMT</updated>
  <icon>http://localhost:8080/alfresco/images/logo/AlfrescoLogo16.ico</icon>
  <author>
    <name>admin</name>
  </author>
  <id>urn:uuid:19c2d38a-9030-11db-be55-975f5973e046</id>
  <opensearch:totalResults>12</opensearch:totalResults>
  <opensearch:startIndex>11</opensearch:startIndex>
  <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
  <opensearch:Query role='request' searchTerms='alfresco tutorial' startPage='2'/>
  <link rel='alternate' href='http://localhost:8080/alfresco/service/search/keyword?q=alfresco tutorial&p=2&c=10&guest=&format=html' type='text/html'/>
  <link rel='self' href='http://localhost:8080/alfresco/service/search/keyword?q=alfresco tutorial&p=2&c=10&guest=&format=atom' type='application/atom+xml'/>
  <link rel='first' href='http://localhost:8080/alfresco/service/search/keyword?q=alfresco tutorial&p=1&c=10&guest=&format=atom' type='application/atom+xml'/>
  <link rel='previous' href='http://localhost:8080/alfresco/service/search/keyword?q=alfresco tutorial&p=1&c=10&guest=&format=atom' type='application/atom+xml'/>
  <link rel='last' href='http://localhost:8080/alfresco/service/search/keyword?q=alfresco tutorial&p=2&c=10&guest=&format=atom' type='application/atom+xml'/>
  <link rel='search' type='application/opensearchdescription+xml' href='http://localhost:8080/alfresco/service/search/keyword/description.xml'/>
  <entry>
    <title>RSS_2.0_recent_docs.ftl</title>
    <link href='http://localhost:8080/alfresco/download/direct/workspace/SpacesStore/f01865f3-9022-11db-923d-5b4061816aa6/RSS_2.0_recent_docs.ftl'/>
    <icon>http://localhost:8080/alfresco/images/filetypes/ftl.gif'</icon>
    <id>urn:uuid:f01865f3-9022-11db-923d-5b4061816aa6</id>
    <updated>2006-12-20T12:09:32GMT</updated>
    <summary>Renders a valid RSS2.0 XML document showing the documents in the current space created or modified in the last 7 days. The template should be configured to use the appropriate server and port before use.</summary>
    <author>
      <name>System</name>
    </author>
    <relevance:score>0.056</relevance:score>
  </entry>
  <entry>
    <title>doc_info.ftl</title>
    <link href='http://localhost:8080/alfresco/download/direct/workspace/SpacesStore/ef7d8547-9022-11db-923d-5b4061816aa6/doc_info.ftl'/>
    <icon>http://localhost:8080/alfresco/images/filetypes/ftl.gif'</icon>
    <id>urn:uuid:ef7d8547-9022-11db-923d-5b4061816aa6</id>
    <updated>2006-12-20T12:09:32GMT</updated>
    <summary>Displays useful information about the current document</summary>
    <author>
      <name>System</name>
    </author>
    <relevance:score>0.055</relevance:score>
  </entry>
</feed>

HTML

Pre-formatted result set for display (currently used by Browsers) - for now, the HTML is not annotated with meta-data (e.g. micro-format).

Description Document

http://<host>:<port>/alfresco/service/api/search/keyword/description.xml

Response Formats:

• opensearchdescription (default)
  

Search Engine Registry

To list all search engines registered with Alfresco, issue:

http://<host>:<port>/alfresco/service/api/search/engines[?type={type?}]

where:

• type (optional) : the type of search engine url to list - one of the following values:
  
  • description (default) : open search description entries
    
  • template : template search url entries
    
  • all : all entries
    

Response Formats:

1. html (default)
   
2. atom
   

Auto-discovery of Search Engines

The HTML response of the above request contains OpenSearch meta-data that lists the available search engines.  OpenSearch clients such  as Internet Explorer 7 and Firefox 2 are sensitive to this data, allowing very simple registration of Alfresco search engines in a search client.

Search Alfresco with FireFox 2 and Internet Explorer 7

The following simple steps allow for Alfresco searches in your browser of choice:

1. Visit either:
   
   1. http://<host>:<port>/alfresco/service/api/search/engines
      
   2. http://<host>:<port>/alfresco  (Alfresco Web Client)
      
2. The browser 'drop-down' search control will glow indicating a new search engine is available
   
3. Click the drop-down and add the appropriate Alfresco search engine
   
4. Type some keywords into the Browser search box and execute search
   
5. Enter Alfresco user name and password
   
6. Browse search results (page forward/back) and view content
   

Registering new Search Engines

The list of registered search engines accessible to Alfresco is configured in:

/config/alfresco/web-scripts-config.xml

The configuration is organised as a list of engines where each engine may present one or more URLs for issuing a search. Each URL supports a specific search response mimetype and may include OpenSearch description documents.

<config evaluator='string-compare' condition='OpenSearch'>
  <opensearch>

    <engines>
       <engine label-id='keyword_search' label='Alfresco Keyword Search'>
         <url type='application/opensearchdescription+xml'>/api/search/keyword/description.xml</url>
         <url type='application/atom+xml'>/api/search/keyword?q={searchTerms}&p={startPage?}&c={count?}&l={language?}&guest={alf:guest?}&format=atom</url>
       </engine>
    </engines>

  </opensearch>
</config>

Sometimes, it is necessary to configure a search engine proxy.  This means that the OpenSearch client indirectly submits a search request via the Alfresco Web Server (i.e. the proxy), rather than directly to the search engine.  This is particularly useful in scenarios where the client is an AJAX based browser limited by cross-domain scripting locks.

Creating a search engine proxy is as simple as adding the proxy attribute to the engine configuration.  The value of this attribute is a unique name that identifies the engine.

<engine label='Alfresco Open Source Talk' proxy='opentalk'>
  <url type='application/rss+xml'>http://blogs.alfresco.com/opentalk/os-query?s={searchTerms}&amp;itemstart={startIndex?}&amp;itempage={startPage?}&amp;itemlimit={count?}</url>
</engine>

When adding new search engines, the recommendation is to place them in:

/config/alfresco/extension/web-scripts-config-custom.xml

Example Search Engine Registrations

The following 'extension' configuration file provides sample search engine registrations for a remote Alfresco Repository and the on-line Alfresco 'Open Talk' Blog.

/alfresco/extension/web-scripts-config-custom.xml.sample

To enable these registrations...

1. Rename web-scripts-config-custom.xml.sample to web-scripts-config-custom.xml
   
2. Within .xml file, find & replace [host] with server name of remote repository
   
3. Within .xml file, find & replace [port] with server port of remote repository
   
4. Re-start Alfresco server
   

Alfresco Proxy Search

This search engine acts as the entry point for all other 'proxied' search engines registered with Alfresco.

The search URL template is:

http://<host>:<port>/alfresco/service/api/search/engine/{engine}/{format}?[argName=argValue]*

where:

• engine = the name of the registered 'proxied' search engine
  
• format = the specific engine url to proxy (as defined by response mimetype)
  

All URL arguments are passed as is to the proxied engine url.  The response type is of the mimetype defined by format.

OpenSearch paging links within ATOM & RSS responses are re-written so that they are 'proxied' too.