Using SAP NetWeaver Enterprise Search in a Web Service

As the OpenSearch standard (http://www.opensearch.org/ ) has evolved and became popular, SAP NetWeaver Enterprise Search SP3 provides its search functionality in accordance with the OpenSearch standard. With the OpenSearch support SAP offers a simple search integration technology that can be used without complex tools. The transport protocol is bound to HTTP/HTTPS and limited to GET requests.

This blog is written for you if you want to create an application that uses search services offered by SAP NetWeaver Enterprise Search, for example, a stylish user interface, a fancy widget, or an integration in an search federation engine.

Let’s start. The way to the search result consists of only 3 steps:

• Retrieve a specific OpenSearch description document.
• Send a search query.

h3. 1. Retrieve the OpenSearch Description Document List

SAP NetWeaver Enterprise Search can provide multiple OpenSearch services. A general search service and many detailed search services are supported. A description document list service specifies all supported search services of SAP NetWeaver Enterprise Search.

The description document list is an OPML file (content type: text/x-opml) with URLs to the locations of the detailed OpenSearch description documents. The description document list can be requested with the following URL of the SAP NetWeaver Enterprise Search system:

This OPML file is generated dynamically based on the current configuration of categories and search object connectors in Enterprise Search. It lists the URLs to the different OpenSearch description documents. Open the URL of the OpenSearch description document list and have a look at the XML format.

Now that you have the OpenSearch Description Document list you can go to the next step.

h3. 2. Retrieve a Specific OpenSearch Description Document

An OpenSearch description document in SAP Netweaver Enterprise Search describes how a query can be constructed to search in a specific search scope and provides the search response in an industry standard format (RSS/ATOM). The OpenSearch description documents are dynamically generated based on the current configuration of categories and object connectors in Enterprise Search.

You can browse the OpenSearch Description Document list and find all the URLs to specific OpenSearch description documents of search object connectors. For example

</p><p>Open the URL of a specific OpenSearch description document and have a look at the XML format.</p><p>Entries of type <Url> are important for you. Here you can find the URL templates for sending a search request. </p><p>There are three different formats available. The search result can be returned in the following formats: standard text, RSS2.0, or ATOM1.0. Choose the URL of the desired format.</p>h3. 3. Send a Search Query
<p>The OpenSearch description document stores the URL templates you need to construct a search query. The URL templates uses placeholders for OpenSearch parameters, which we use as query parameters. See the table: </p>  <table border=”1″ cellspacing=”1″ cellpadding=”1″ style=”background-color: #d3d1cf” dir=”ltr”><thead><tr><td><p style=”margin: 6pt 0cm 0pt; text-align: center” class=”MsoNormal” align=”center”>Parameter 

OpenSearch Parameter

Mandatory

Description</p></td></tr></thead><tbody><tr><td><p>query</p></td><td><p>searchTerms</p></td><td><p>Yes</p></td><td><p>The search query.</p></td></tr><tr><td><p>scope</p></td><td><p>not applicable</p></td><td><p>No</p></td><td><p>The search scope limits Enterprise Search to return search results from the specified scope. The default scope is to search across all configured categories and object connectors. The search scope is displayed in a hierarchical format “/<CategoryId>/<ObjectConnectorId>”.</p></td></tr><tr><td><p>startIndex</p></td><td><p>startIndex</p></td><td><p>Yes</p></td><td><p>The index of the first search result item in the response.</p></td></tr><tr><td><p>maxItems</p></td><td><p>count</p></td><td><p>Yes</p></td><td><p>The maximum number of search results items to be returned in the response.</p></td></tr><tr><td><p>language</p></td><td><p>language</p></td><td><p>No</p></td><td><p>The default language is derived from the user context of the logged in user in case of secure search. </p></td></tr><tr><td><p>format</p></td><td><p>not applicable</p></td><td><p>No</p></td><td><p>The format of the search response. The default format is HTML (text/html). The supported format strings are “rss” for RSS 2.0 format and “atom” for ATOM 1.0 format.</p></td></tr></tbody></table><p><br />Example of an template URL:<br />“

Example of an query:

“

h3. Conclusion

Now you know about the important URL and how to build a search query. With a simple GET request you can create applications that send search queries to search object connectors in the Enterprise Search system. Then the search results are returned in the format you specified in the query (standard text, RSS2.0, or ATOM1.0).

h3. Before I Forget, Some Words About Authentication and Authorization

All URLs matching the pattern “/es/api/opensearch/*” are accessible by default with HTTP BASIC Authentication. They are accessible if a valid user name/password combination is found in the authorization HTTP header.

Single Sign-On is supported by using SAP logon tickets. In this case the SAP logon ticket must be  available as a MYSAPSSO2 cookie in the HTTP request.

The default authentication mechanism supported by SAP Netweaver Enterprise Search 7.00 SP3 for OpenSearch requests can be modified at runtime to support more authentication mechanisms provided by the underlying SAP Netweaver AS Java.

Once authenticated, the user needs to have the ES_SEARCH permission configured with SAP Netweaver Enterprise Search to complete the request.

h3. To Be Continued

This blog was the first part of a series on OpenSearch. Stay tuned for the next one in which I will tell you how to add SAP NetWeaver Enterprise Search as an additional search provider in Microsoft Internet Explorer 7 and Mozilla Firefox.