Enabling Your Data Store in Windows Federated Search

  • Article

[This documentation is preliminary and is subject to change.]

Explains how to enable your data store to be accessed by an OpenSearch Web service, and how to circumvent potential barriers to enabling a data store.

This topic contains the following sections:

  • Conditions for Search Request Acceptance
    • Supported Query Syntax
    • Supported Authentication Protocols
  • Understand How Windows Maps Items to File Types
  • Circumvent Barries to Enabling a Data Store
    • Write a Middle-man Web Service
    • Use an Existing Search Engine
    • Write a Client-side Data Store
  • Additional Resources
  • Related Topics

Conditions for Search Request Acceptance

The OpenSearch Web service you create on your Web server must fulfill the following two conditions:

  • Accept a GET URL query from the client.

  • Permit the search terms to be embedded in the URL. See the following example of how a search terms could be embedded in a URL.

    https://example.com/search.aspx?query=terms&param=foo

Note  Federated search does not support sending POST requests to a Web service.

For more information about constructing a URL, see "URL Template Parameters" in Creating an OpenSearch Description File in Windows Federated Search.

Supported Query Syntax

There is no specific query syntax expected in Windows 7. The OpenSearch provider accepts whatever terms the user enters in the input box in Windows Explorer, and encodes it into the URL. It does so according to the URL template described in "URL Template Parameters" in Creating an OpenSearch Description File in Windows Federated Search.

Users expect that separate terms are treated as implicitly ANDed together. For example, a query for "Microsoft Windows" should return only a subset of the combined results of separate queries for "Windows" and "Microsoft".

Supported Authentication Protocols

Windows Search federation supports Windows-based authentication, and can provide credentials to Web services via the following protocols:

  • NTLM
  • Kerberos
  • Basic (only over https)

See the SSP Interface SDK documentation to keep abreast of the potential addition of other Security Support Providers (SSPs).

Understand How Windows Maps Items to File Types

Searching via Windows Explorer permits users to treat results as files when an RSS item points to a file stored remotely. The user can drag/drop items to the desktop, and the Windows Explorer UI displays the correct icon, and provides the appropriate shortcut menu. If the RSS item does not point to a remotely stored file, then the file is treated as a link, and users can perform actions on it such as creating a shortcut or opening it in the browser.

Determining an Item's File Type

To map an item to a file type you must:

  • Identify whether the item should be treated as a file or a Web link
  • Identify the correct file extension to use

For example, if the item has a link URL that uses a file system path (such as file:///\\server\share\etc\item.ext), the OpenSearch provider treats the link as a file, and determines the type by the file extension used in the path (.ext in this example).

If the item uses the standard RSS enclosure or MediaRSS media:content element, then the OpenSearch provider assumes that the item is a file and identifies the file extension as follows:

  • If the System.FileExtension Windows Shell property has been mapped for the item, then the provider uses that file extension.
  • If the System.FileExtension Windows Shell property has not been mapped, then the provider uses the Type attribute specified in the enclosure or content element. This element should contain a MIMEType string, such as "image/jpeg". If the MIMEType is associated with a file extension registered on the client machine, then the item is regarded as a file of that type. If the MIMEType is not associated with a file extension registered on the client machine, then the item is treated as a Web link type. The OpenSource provider does not attempt to parse the Url attribute to locate the file extension.
  • If the MIMEType is associated with a file extension registered on the client machine, then the provider determines whether the file extension is a known Web file type (.htm, .html, .asp, .aspx, .php, .swf, .stm). If so, the file type is regarded as a Web link type; otherwise, is regarded as a file type.
  • For example, if the MIMEType "text/html" is associated with the .htm file extension, then that item is regarded as a Web link instead of as an .htm file type.

Circumvent Barries to Enabling a Data Store

A data store cannot provide an OpenSearch compatible Web service for:

  • Remote indexes with authentication methods that are not supported in Windows 7 Federated Search.

    Examples include forms-based authentication, and other custom authentication methods.

  • High value public stores of vertical data that do not provide OpenSearch output support, but have public Web APIs.

    Examples include the Library of Congress, and medical research databases.

  • Proprietary enterprise data stores or indexes, and legacy content management stores, for which it might be impossible to implement a front end.

However, there are alternatives by which to circumvent barriers to enabling a data store.

Write a Middle-man Web Service

Scenario 1: You cannot modify the Web service for the existing data source

Scenario 2: The Web service provides a custom API

Write a middle-man Web service that can take the Windows 7 query, and then:

  • Connect to your data source and and retrieve the results
  • Reformat the results in RSS or Atom format
  • Return the results to the Windows 7 client

For enterprise data services and many internet data services, you may need to pass the user credentials through on behalf of the Web service to perform result trimming based on the user's permissions.

Use an Existing Search Engine

Scenario 1: You cannot enable a public data store

You can also use a public search engine that already supports OpenSearch with RSS. You can do so by providing your users with an .osdx file that has a URL template that restricts results to only those for your specific domain. See the following example of a sample OpenSearch description for searching only the help content for Windows by using a query against live.com:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
  <ShortName>Windows Help</ShortName>
  <Description>Search Windows Help using the live.com search engine</Description>
  <Language></Language>
  <Url type="text/html" template="https://windowshelp.microsoft.com/windows/en-us/search.aspx?=&amp;qu={searchTerms}"/>
  <Url type="application/rss+xml" template="https://api.search.live.com/rss.aspx?source=web&amp;query={searchTerms} site:windowshelp.microsoft.com&amp;web.count=50"/>
</OpenSearchDescription>

Scenario 2: You cannot enable proprietary enterprise data stores or indexes

You can use an existing indexing server that supports OpenSearch to index your content, such as the SharePoint Search Server. You can then create a .osdx file that restricts the results from the SharePoint index to only those from your server by using their KeyWord syntax within the URL template.

Write a Client-side Data Store

Scenario 1: A server-side only solution will not work

Write a client-side OpenSearch data source that sits in between the Windows OpenSearch provider and the external data source. Use the IOpenSearchSource Interface API in the Windows SDK for Windows to create an appropriately configured .searchconnector-ms file through which Windows Explorer can call your implementation with the query parameters. Your implementation can then return results formatted in RSS or Atom format. Doing so permits your implementation to provide custom authentication UI, and connect to the data source using its proprietary API.

Opening an .osdx file creates a .searchconnector-ms file (search connector) in the %userprofile%/searches directory, and places a link to it in the %userprofile%/links directory. For more information on how to create an .osdx file, see Creating an OpenSearch Description File in Windows Federated Search.

Additional Resources

  • For a demonstration of how to create an OpenSearch Web service for a SQL database, see the Windows 7: Empower Users to Find, Visualize and Organize their Data with Libraries and the Explorer World Wide Web link video presentation given at PDC (October 2008).
  • For information on Windows system-defined properties, see System-Defined Properties for Custom File Formats.
  • For information on Shell system properties, see System Properties.
  • SharePoint Search Server 2008 and MOSS 2007 SP2 also support federated search of remote servers using OpenSearch. For more information about federated search and Search Server 2008 deployment with Office SharePoint Server 2007, see Welcome to Microsoft Search Server 2008.
  • See the Microsoft Download Center Web site for the following downloadable resources:
    • Windows 7 Federated Search Provider Implementer's Guide
    • Search Server 2008 Sample: Federated Search Connector Sample
  • For more information about the OpenSearch standard, see the OpenSearch World Wide Web link Web site.