Home > Sample chapters

Managing the Search Experience in Microsoft SharePoint 2010

Federated Queries

Federated queries permit end users to search for and retrieve content from an OpenSearch 1.1–compliant search server. These content sources can be enterprise content repositories, other search engines (including remote SharePoint search), or your SharePoint Server 2010 search services. With a federated query, the server sends the queries to the federated locations, retrieves the results from the location feed, and then formats and renders the results to your users on the same page as results from your crawled content. With SharePoint Server 2010, all queries (including those to the local search service applications) are federated.

Federated Location Management

To access the management page for the federated locations shown in Figure 9-3, click Federated Locations on the Search Service Application page. This discussion will focus primarily on actions available from the Manage Federated Locations page:

  • Add a federated location by using the provided New Location UI or by importing existing definition files.

  • Edit a federated location using the UI.

  • Copy a federated location to use as the basis for another location.

  • Delete a federated location.

  • Export a federated location into a portable file.

    Figure 9-3

    Figure 9-3 The Manage Federated Locations page.

Add New Location or Edit a Location

To add and configure a new location in the UI, click the New Location link on the Manage Federated Locations page as shown in Figure 9-3. This opens the Add Federated Location page, where the properties of the location will be configured. Editing an existing location opens essentially the same page except that the location name cannot be changed. Most, but not all, information entered on this page will be included in the Federated Location Definition (FLD) file itself. The configuration entries are grouped under headings that can be expanded or collapsed.

General Information

The first three items shown in Figure 9-4 are required information.

The Location Name text box is used to identify this location, and the name chosen must be unique within your organization. It cannot be modified after the FLD has been created. This name is used only by service administrators and developers. More than one FLD can connect to the same search server with different parameters as long as each one has a unique name. This name cannot contain spaces or any punctuation.

The name entered in the Display Name text box for this location should also be unique. Site collection administrators will be the primary users of this name, but they can choose to display this name to end users in federated-enabled Web parts.

The description entered in the Description text box will be visible to service administrators, site administrators, and developers. It should include all information defining how the queries will be run, such as the source (and any limitation or refinements), who can access this location, and what triggers or macros are provided.

Figure 9-4

Figure 9-4 New location general information.

The next two items, the Author and Version text boxes, are shown in Figure 9-5. Providing this information is optional.

Figure 9-5

Figure 9-5 New Location optional information.

The author information you provide depends on whether the location is shared externally or only internally. It is simply a text field in which you can enter your company name, an individual’s name, an e-mail address, and so on. This entry does not assign any ownership or permissions.

Information entered in the Version text box is purely optional information. If you choose to enter a value, it must contain at least one period (.). This information is included in the file and simply provides a way to track change history, because there is no way to upgrade a location based on its version.

The Trigger configuration shown in Figure 9-6 is very much functional information and controls whether the location is used in a query and how much of the query term is forwarded to the search server. The location Web part will be displayed on the results page only if results are returned from the query.

Figure 9-6

Figure 9-6 Trigger configuration.

The default setting, Always, sends all queries to this location. Bandwidth utilization of the traffic generated by all queries being forwarded externally and the latency of results sets being returned should be considered before using this option.

If you choose to use the Prefix trigger, an exact match of a term listed as a prefix is required. Use of prefixes requires users to be trained. The first consideration is that the word used as a prefix will not be forwarded to the federated location search engine but will be used in searching your local content. If users are properly trained, however, the use of prefixes will enable the selective use of federated locations controlled by users’ query constructions.

For example, a prefix trigger for “medicine” will match “medicine Benadryl.” In this case, only “Benadryl” will be sent to the location as a search term, because the prefix is not included in {searchTerms}. If you want to send both “medicine” and “Benadryl” to the location, you need to use a pattern trigger instead.

A pattern query will probably be transparent to your users. Patterns are defined as .NET regular expressions (REGEX). If the query or part of the query matches the pattern defined, the entire query is forwarded to the location. This pattern matching of regular expressions quickly parses text to find specific character patterns, which triggers the use of the federated location. It can also add the extracted strings to a capture group or collection, which will store it in a named variable for later use in the query template.

For example, the pattern (^([\w-\.]+)@([\w-]+\.)+([a-zA-Z]{2,4})$) searches the location for e-mail queries such as email@contoso.com. For more information on .NET Framework regular expressions, see http://go.microsoft.com/fwlink/?LinkId=100710.

If the pattern were medicine(?<drug>.*) and the user query was medicine Benadryl, the pattern would match medicine and store Benadryl in the capture group (or variable) <drug>. You could then configure the FDL to send only this capture group to the location by replacing {searchTerms} with {drug} in the query template. This example behaves just like a prefix trigger in that it does not forward medicine from the original query in the federated query.

MSDN has a forum on regular expressions at http://social.msdn.microsoft.com/Forums/en-US/regexp/threads.

Location Information

The next section of configuration settings for the location is grouped under Location Information, as shown in Figure 9-7.

Figure 9-7

Figure 9-7 Location Information settings.

The location type determines the protocol used to connect to this location, and several configuration options change depending on your choice:

  • Search Index On This Server. Used to run a standard query to get results from the local index. Selecting this option will display results from a predefined scope or a managed property with all the specified parameters, including triggers and query templates.

  • FAST Index Used to query a FAST server.

  • OpenSearch 1.0/1.1. Used to display results from another search engine that can receive a query by using a URL and return results as structured XML, including remote search indexes on other SharePoint farms.

A search query is sent to a federated location as URL parameters in a format called a query template. This is called the URL template in the OpenSearch specification, and the query template syntax is based on the URL template syntax. When using the local index as a federated location, no query template is required because the protocol uses the object model to execute the query.

The default query template simply includes the case-sensitive {searchTerms} capture group as a variable, which represents the keywords entered into the search box by users. As we discussed in pattern triggers, you can replace {searchTerms} with capture groups created by your pattern. You can include other parameters in the template to specify additional query restrictions. These parameters are managed properties of the index that are probably not known to your users. If a parameter is optional, include a question mark character (?) after the parameter name. Common parameters are the following:

  • scope: <name of scope>. Limits the search to a particular scope. Multiple entries are permitted to combine more than one scope.

  • type:.doc type.docx type.docm. Returns Microsoft Office Word document results for the keywords entered into the Search box. Other content types can be added to further refine the results—for example, to include only contracts.

Parameters that you specify in the URL template must be URL-encoded. For example, a space must be represented by %20.

An example of an OpenSearch template is http://www.bing.com/search?q={searchTerms}&go=&form=QBLH&qs=n&format=rss.

The More Results Link Template option specifies the URL of the Web page that displays results for a search query. When this link is configured in the Web part, a More Results link displays beneath the search results from this location. This link opens a page that presents the full list of results from the location, not just the number specified in the results Web part. An example is http://www.bing.com/search?q={searchTerms}.

Display Information

The configurations in this grouping control how the results will be displayed within the Web part.

Microsoft federated queries require that federated locations return results in structured XML, which must then be transformed into HTML by XSL before it can be displayed in the Federated Results Web part. The Top Federated Search Results Display Metadata section presents the options to use the default XSL or to edit it for a customized display of results, text, and images as shown in Figure 9-8.

Properties determine the metadata returned with the search results. If you modify the default list of metadata in the list of returned properties, you must also update the XSL to display the new properties.

Sample data is included so that a visual preview is available when editing the Federated Results Web part.

Figure 9-8

Figure 9-8 Federated Search Results Display Metadata.

The Core Search Results Display Metadata and Top Federated Results Display Metadata sections present the same options as the Federated Search Results Display Metadata section shown in Figure 9-8 except that these settings apply when different Web parts present results from the location.

Restrictions and Credentials Information

The final section controls the usage of the location and what type of authentication is required by the location.

As shown in Figure 9-9, the Restrict Usage section permits the search administrator to control whether all site collections can use an individual federated location or whether the location is restricted to a list of one or more site collections. The default is No Restriction, which permits site administrators from any site to use this location.

Selecting Use Restriction activates the box for listing by URL the specific site collections that can use this location. With this option, you can do the following:

  • Restrict access to confidential data

  • Limit the number of people who can access the location

  • Provide access to the same search server configured differently as unique federated locations for different site collections within your enterprise

A semicolon must be used to separate the start addresses of URLs in the Allowed Sites list. For example, the list http://team1;http://team2 ensures that the location can be used only in sites starting with http://team1 or http://team2.

Figure 9-9

Figure 9-9 Restrictions options.

In some instances, authentication might be required. Most Internet search engines do not require credentials. If Search Index On This Server is selected as the Location Type for the federated location, no additional authentication information is required. Results from this federated location will be security trimmed based on user credentials after they have been returned to the Web front-end server. However, if the location type selected is FAST Index or OpenSearch 1.0/1.1, you must specify the authentication method and provide security credentials as shown in Figure 9-10.

Figure 9-10

Figure 9-10 Authentication settings for FAST or OpenSearch locations.

These authentication options are grouped as follows:

  • Anonymous Access. Indicates that the location does not require authentication.

  • Common Authentication. Provides a single user name and password to the location. If you enable this option, you must select the authentication method required by the search server and provide the credentials to be used. Each authentication method, as selected, presents the appropriate dialog boxes for entering the credentials to be used. These dialog boxes are not illustrated here.

  • User-Level Authentication. Passes individual user credentials to the location using the method that you select.

Download and Import an FDL file

You can download federated search connectors from the Search Connectors Gallery at http://go.microsoft.com/fwlink/?LinkID=95798, or you can use custom connectors that you have built and exported to your file system to quickly import a preconfigured connector into your Search Server configuration. The Import Location link on the Manage Federated Locations page opens a page where you can browse to a local file system and select the appropriate .fld file. After importing a location that requires authentication, you must edit the location and re-enter the credentials that were not saved during an export operation.

Copy a Federated Location

The Copy Location option shown in Figure 9-3 copies all the settings of the location except the name, which needs to be unique. This is the easiest way to change the name. It is also useful when you want the same location available with modified parameters for different site collections.

Delete a Federated Location

When you select Delete Location from the context menu shown in Figure 9-3, you will be given one warning. If you click OK, all information about the location is deleted. You might want to export the location before deleting it so that it will be available if you need to restore it later.

Export a Federated Location

Exporting a location from the context menu shown in Figure 9-3 gives you a portable configuration file with an .fld extension, which can be used to restore the location locally or imported onto another search server. However, when you export a federated location to a definition file, your security credentials or settings are not included with the file.