Customizing the Microsoft Office 2003 Research Task Pane

Jan Fransen

March 2003

Applies to:
    Microsoft® Office Word 2003
    Microsoft Office Excel 2003
    Microsoft Office PowerPoint 2003
    Microsoft Office System

Summary: Learn how to optimize the Research task pane in Office 2003. (12 printed pages)

Contents

Introduction
Getting Started
Anatomy of a Research Task Pane Web Service
The Registration Function
The Query Function
Registering and Testing the Web Service
Finding Out What the User's Looking For
Adding Data to the User's Document
Summary

Introduction

The new Microsoft® Office 2003 Research task pane, available in Microsoft Office Word 2003, Microsoft Office Excel 2003, and Microsoft Office PowerPoint 2003, provides Office 2003 users with the ability to search certain local and remote data sources from within these Office 2003 products. Out of the box, the Research task pane includes several resources. For instance, Office 2003 users can query reference books such as the Encarta World Dictionary, or online resources like stock quotes.

Most of the resources provided by Office 2003 are actually Web services. By creating a Web service that is compatible with the Research task pane (a Research service), you can give Office 2003 users access to information in corporate data sources from within the Office 2003 applications where the data is most likely to be used.

This document will discuss how to create a Research service. The solutions you create can provide increasingly sophisticated search results such as:

• Displaying a text-based list of results in paragraph or tabular form
• Providing a list of search results with expandable details
• Adding images to the result
• Querying a text result for more detail
• Adding data from the result to the user's current document

Getting Started

In order to experiment with these new features, you'll need to have the following tools installed:

• Microsoft Office 2003
• Microsoft .NET Framework 1.0
• Internet Information Services (IIS) 5.0
• Microsoft Visual Studio® .NET 2002 (VS .NET)

Anatomy of a Research Task Pane Web Service

Like all Web services, a Research service is an application that uses open standards like XML and SOAP to communicate with a client via an Internet protocol backbone. A Web service doesn't provide a user interface of its own. Rather, a Web service simply receives an XML document from the client (in this case, the Research task pane in Office 2003) and responds by sending another XML document back. The client is responsible for sending an XML document that the service will understand, and parsing the returned XML document for use in an application or for display to the user. If the client is the Research task pane, it automatically handles both sending an appropriate XML document and formatting the Web service's response for display to the user within the Research task pane.

The Research task pane can do much of the work because the Web services it calls are designed specifically to work with it. When you create a Research service, you follow certain rules. For instance, the Web service must contain two functions, Registration and Query, and the XML packets they use to communicate must comply with predefined XML schemas. You can find the full schemas in the Research SDK. Many of the elements and attributes used by the key schemas will be described later in this document.

The Registration function is used to register the Research service with the Research task pane. Once registered, the service is available as a choice in the Show Results From dropdown. When the user installs the Research service as a Research task pane resource, a request is sent to the Registration function. The response is used to make appropriate entries in the Windows Registry, and must be formatted as defined by the Microsoft.Search.Registration.Response.xsd schema.

The Query function is called when the user requests information from the Research service by searching for a term or using a form in the Research task pane. The Research task pane sends an XML packet complying with the Microsoft.Search.Query.xsd schema. The Research service must send a response based on the Microsoft.Search.Response.xsd family of schemas.

The Registration Function

To create a Research service, you create a new ASP.NET Web Service project using Visual Studio .NET. You can store the project in a folder within your IIS default Web site (http://localhost).

Before you can use a Research service, you must register it. An Office 2003 user registers a Research service by calling the Research service's Registration function. Any Research service Registration function uses the urn:Microsoft.Search namespace. The code within the Registration function creates and returns an XML packet in the format required by the Microsoft.Search.Registration.Response schema. Office 2003 uses information from the packet to add a reference for the Web service to the Windows Registry.

Some of the data in the XML packet is used to describe the provider itself. These elements are described in Table 1.

Table 1. Elements that describe the provider

The data within the Service node of the XML packet describes the Research service. The elements are described in Table 2.

Table 2. Elements in the Service node

In Visual Basic .NET, the code to create a Registration Response XML packet might look like this:

Imports System.Web.Services ' automatically added
Imports System.Xml          ' needed to read and create XML packets
Imports System.IO           ' needed to construct the XML packet in memory

<WebService(Namespace:="urn:Microsoft.Search")> _
Public Class MyResearchPane
    Inherits System.Web.Services.WebService

<WebMethod()> Public Function Registration(ByVal regXML As String) As
  String
    Dim ioMemStream As New MemoryStream()
    Dim myXMLwriter As New XmlTextWriter(ioMemStream, Nothing)

    With myXMLwriter
        .Indentation = 4
        .IndentChar = " "
        .WriteStartDocument()
        .WriteStartElement("ProviderUpdate", _
         ns:="urn:Microsoft.Search.Registration.Response")
        .WriteElementString("Status", "SUCCESS")
        .WriteStartElement("Providers")
        .WriteStartElement("Provider")

        .WriteElementString("Message", _
         "Congratulations! You've registered Research Pane Examples!")
        .WriteElementString("Id", _
         "{E545CFA2-E5AC-408a-92D9-E8C8487E6D69}")
        .WriteElementString("Name", "Research Pane Examples")
        .WriteElementString("QueryPath", _
         "http://localhost/StepByStep/Query.asmx")
        .WriteElementString("RegistrationPath", _
         "http://localhost/StepByStep/Registration.asmx")
        .WriteElementString("Type", "SOAP")
        .WriteStartElement("Services")
        .WriteStartElement("Service")
        .WriteElementString("Id", _
         "{942F685E-0935-42c8-80C5-95DB0D129910}")
        .WriteElementString("Name", "Research Pane Examples")
        .WriteElementString("Description", _
         "Research Pane Examples provides a simple example of " & _
         "customizing the Office Research Pane.")
        .WriteElementString("Copyright", _
         "All content Copyright (c) 2003.")
        .WriteElementString("Display", "On")
        .WriteElementString("Category", "INTRANET_GENERAL")

        .WriteEndElement()  ' Service
        .WriteEndElement()  ' Services
        .WriteEndElement()  ' Provider
        .WriteEndElement()  ' Providers
        .WriteEndElement()  ' ProviderUpdate
        .WriteEndDocument()
    End With

    myXMLwriter.Flush()

    ioMemStream.Flush()
    ioMemStream.Position = 0
    Dim iostReader As New IO.StreamReader(ioMemStream)
    Return iostReader.ReadToEnd.ToString
End Function

After you write the Registration function, you can test it by choosing Build and Browse from the menu. You will see the standard Web service test page. After clicking through the Registration link to the Registration test page and clicking the Invoke button, you will see the Response XML packet in the browser window.

Once you've written the Registration function, your Research service is complete enough to register with the Research task pane, but of course it cannot yet return any results. Before you can see a return value, you'll need to create a Query function.

The Query Function

A typical Query Web method accesses a data source, such as a SQL Server database or a Windows SharePoint Services site, to gather information for display in the Research task pane.

The Query function receives an XML packet that conforms to the Microsoft.Search.Query schema. It must return an XML packet that conforms to the Microsoft.Search.Response schema.

The response packet must include at least the elements described in Table 3.

Table 3. Required elements for the XML response packet

The value of the domain attribute of the Response element must match the Service ID GUID you specified in the Registration Response XML packet. This GUID provides the Research task pane with a way of matching the response to your Research service; without it, the Research task pane assumes that your Web service returned no result. The QueryID GUID should be another unique GUID, and needn't match any other number.

If a response is received, the Research task pane looks to the data in the Results node to determine what to display. The response packet reproduced here renders to a single paragraph under the Research Pane Examples heading, as shown in Figure 1.

Figure 1. A query on any word (or no word) results in the same response from the sample Web service.

The Results node usually contains a Content node. The Content node contains elements described in the Microsoft.Search.Response.Content schema, and the values of the elements supplied are rendered as rich text in the Research task pane. The most commonly used Content elements are listed in Table 4.

Table 4. The most commonly used Content elements

The Visual Basic .NET code for a simple Query function might look like this:

<WebMethod()> Public Function Query(ByVal queryXml As String) As String

        Dim queryTerm As String
        Dim ioMemStream As New MemoryStream()
        Dim myXMLwriter As New XmlTextWriter(ioMemStream, Nothing)

        With myXMLwriter
            .Indentation = 4
            .IndentChar = " "
            .WriteStartDocument()

            .WriteStartElement("ResponsePacket", _
             ns:="urn:Microsoft.Search.Response")
            .WriteAttributeString("revision", value:=1)

            .WriteStartElement("Response")

            ' this GUID must match the Registration Service ID

            .WriteAttributeString("domain", _
             value:="{942F685E-0935-42c8-80C5-95DB0D129910}")
            .WriteElementString("QueryID", _
             "{690EF6D8-575D-4897-8F30-293E175C1B99}")
            .WriteStartElement("Range")
            .WriteStartElement("Results")
            .WriteStartElement("Content", _
             ns:="urn:Microsoft.Search.Response.Content")
            .WriteElementString("P", "I heard you!")
            .WriteEndElement() ' Content

            .WriteEndElement() ' Results
            .WriteEndElement() ' Range

            .WriteElementString("Status", "SUCCESS")

            .WriteEndElement() ' Response
            .WriteEndElement() ' ResponsePacket
            .WriteEndDocument()
        End With

        myXMLwriter.Flush()
        ioMemStream.Flush()
        ioMemStream.Position = 0
        Dim iostReader As New IO.StreamReader(ioMemStream)
        Return iostReader.ReadToEnd.ToString
    End Function

After you've entered the code, you can Build and Browse the Query function and invoke the Query method. You can see the XML packet in the browser window.

Registering and Testing the Web Service

Registering and testing the Research service within Office 2003 is easy. You open Word, Excel, or PowerPoint and then the Research task pane by selecting Tools | Research from the main menu. Next, you click the Research options. . . hyperlink at the bottom of the pane, and then the Add Services button.

In the Address text box of the Add Services dialog box, you type in the path to your Registration service, as shown in Figure 2, and click Add. You'll see a setup dialog box and choose the Install button. When you close the Research Options dialog box, the Research service is ready to query.

Figure 2. Add a service by typing the path to your Registration service.

To verify that the Research service has been registered, you drop down the Show results from list in the Research task pane and look for your newly created Research service. You can select it from here if you would like to try querying your Research service.

Once your service is registered, you can continue to make changes to the Query function and test by building the service and then moving over to an Office 2003 product to try it out. There is no need to re-register each time you change the Query function.

Finding Out What the User's Looking For

To find out about specific queries and respond with a relevant result, your Query function needs to parse the XML packet received from the Research task pane.

The structure of the query packet follows the Microsoft.Search.Query schema. The QueryText element's value is the exact word or words entered by the user in the Research task pane. The query packet also provides a Keywords node that parses each individual word and also includes different word forms (the plural form of the word, for example) for each word.

Given the ability to parse the XML packet to find out what the user is querying for, you can use whatever logic or queries necessary to provide an appropriate response. Typical code to extract the QueryText element from the query packet might look like this:

        Dim queryTerm As String
        Dim requestXML As New XmlDocument()
        requestXml.LoadXml(queryXml)

        Dim nsmRequest As New XmlNamespaceManager(requestXML.NameTable)
        nsmRequest.AddNamespace("ns", "urn:Microsoft.Search.Query")

        queryTerm = requestXML.SelectSingleNode( _
         "//ns:QueryText", nsmRequest).InnerText

Adding Data to the User's Document

In addition to text, headings, and hyperlinks, the Research task pane supports certain actions to transfer data from the Research task pane to the user's document. You can easily add Insert and Copy actions to your response, and you can also add support for custom Smart Tags that are installed on the user's machine.

You can use the Actions element to add an Action button to the rendered response, as shown in Figure 3.

Figure 3. The drop-down button shows Copy and Insert choices.

Selecting Copy chores copies information about the item to the clipboard. Selecting Paste chores pastes information about the item into the current document at the cursor location.

To specify the choices you want to see in the Action button, you add the Copy or Insert elements to the Actions node.

The Text element controls the text that you see as the menu choices on the Action button. The Data element defines what data will be copied or inserted in the document if the user selects one of the choices.

In addition to the Copy and Insert elements, you can use the Custom element to add your own Smart Tag to the choices.

Summary

It is easy to create Web services that you can use with the Research task pane in Word, Excel and PowerPoint from Office 2003. You can create functions for registering and querying the Research service, and that you can install a Research service in the Research task pane. The response packet offers many options, and the Research task pane renders those response packets for display for the user. You'll find this aspect of Office 2003 to be both useful and easy in many projects.

© Microsoft Corporation. All rights reserved.