Research Library Technical Specification

Note  This is a draft version of the documentation for the Microsoft Office Research Service SDK and may contain inaccuracies. The complete, detailed version of the documentation for the Microsoft Office Research Service SDK will be available in late 2003.

Overview

The Research Library in Microsoft Office allows developers to create their own research services. For example, a company has a repository of data that they want to provide to their internal users. Another company has a repository of articles that they want to provide to their customers. The Research Library allows each of these companies to develop a service that functions within Office applications, allowing their Office customers to easily access their services while working on Office documents, and the data returned can not only be rich in content, but it can be interactive as well.

Research services can also markup their results with smart tags, allowing users to do anything smart tags can do. For example, a user is writing an analyst report in Word about his company and wants to incorporate data about the company's stock performance. Today, the user would open a browser, and copy and paste that information directly into his document, a multiple-step process. However, with the Research Library, a research service could allow the user to search for stock information directly inside of Word. When he locates the data he wants to insert, he can use a smart tag, shown within the research results, to insert the data into his document. (For more information on Smart Tags, you may download the Smart Tag Software Developer Kit from MSDN at

A href http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/MSDN-FILES/027/001/652/msdncompositedoc.xml

Understanding the Research Library Feature

The Research Library feature provides this functionality using formatted XML packets. Once a service is registered on a user's machine, the user can generate queries, which Office sends onto the service (via SOAP). A research service receives a basic query packet, an XML string that adheres to the query protocol schema. Then the research service processes the query and returns the results of the query using one of the authorized results schemas.

Users can show the Research Library pane several different ways. They can select Research Library from the Tools menu or click on the Research Library icon on the toolbar

Initially, users must register your service on their machine. Once registered, users can initiate searches for your service. When users initiate searches, Office sends query packets to your service. The following diagram shows the order of the XML schema packets.

Image of XML schema packets

When Office receives a response from your service with the results of the search, the Office application from which the user initiated the search displays the results in the Research Library pane. An example of the Research Library pane is shown below.

Image of the screen Research Library

Architecture

There are two basic scenarios where a research service can be used: on a client machine, in an intranet, or through the Internet. Users positioned behind a corporate firewall can access services on the Internet directly through a client application, such as Word or Excel, or can access research services indirectly through a server within their corporate intranet.

Image of servers on a corporate intranet

Scenarios

  1. Server-based (Intranet).    The Research Library can talk to any arbitrary server via the search protocols to be defined later in this document. An intranet server could be registered with the Office applications in order to allow content from such a server to be displayed within the Research Library
  2. Server-based (Internet).    Same as above, but the server is located on the Internet. Getting Started.

Getting Started

Setting up and maintaining a Research Library service is a relatively easy process. If you already have a repository of data, you can:

  1. Register your service
  2. Process user queries
  3. Return responses

Registering a Research Library Service

There are several ways you can register a Research Library service: using a URL or an installation program. This section covers the recommended way of registering, using a URL.

When you provide your users with a URL, they can enter that URL into the Add Service dialog to register your service on their machine. For this to function properly, you must have a SOAP function called Registration located at the URL that you give your users. As shown in Example 1 below, the Registration function takes a String and returns a String.

Example 1: Registration Function Syntax
[WebMethod] Public String Registration(String) (C#)
<WebMethod> Public Function Registration(reg as String) as String (VB. Net)

The String passed into the Registration function conforms to the RegistrationRequest schema. (The RegistrationRequest schema is shown on page Error! Bookmark not defined.)

The String passed back from the Registration function must conform to the RegistrationResponse schema (shown on page Error! Bookmark not defined.). The RegistrationResponse schema contains all the registration information needed for the Office application to create the registry entries for your research service.

Updating the Registration Settings

When you register your service using the above method, the Framework will periodically request providers to update their registration information. Information is updated at the provider level. This is performed automatically, whereas if you are registering a service using a custom installation, you will need to provide a custom update application if the service registration settings change.

The information we will need to get from the provider are those pieces of data with a "Yes" in the Data received from provider column.

Processing Queries

The second step in setting up a Research Library service is to develop a way in which to process the queries you receive from your users. To do this, you need to create a SOAP function named Query. "This function, as shown in the syntax example below, takes a String and returns a String."

[WebMethod] Public String Query(String) (C#)
<WebMethod> Public Function Query(reg as String) as String (VB)

The Office application from which your users access your service calls this Query function and passes in a String comprised of XML data that adheres to the XML QueryPacket schema, shown on page 7. The Query function you create needs to process this String and then return a String that adheres to the Response schemas.

Symmetry between Query and Response

We expect that providers will adhere to the following rules to maintain the symmetry between the query and the response:

  1. Inside the Query element, the query originator (Office in this case) will declare the namespaces it supports for the response within the SupportedFormats element. The Response that corresponds to that query must contain only elements in the supported namespaces within its Results tag. This ensures that a query originator that uses this system can declare any arbitrary format that it supports; if the provider supports the format it can return the appropriate results and if it doesn't it can acknowledge the request but return an error.
  2. For every Query inside a QueryPacket the provider must return a Response inside the ResponsePacket. This is used by Office to send multiple queries up at once, directed at different domains or services within the provider. If a provider only has one domain that Office is aware of it will receive a simple QueryPacket that contains only one Query. In other words, Office will only send more than one Query in a QueryPacket if the provider registers multiple domains or services with Office via the registration protocol
  3. For every Range inside a Query there must be a range inside the Response corresponding to that Query. Multiple ranges can be used by a query originator to ask for multiple result types. A result type groups results into meaningful categories which need to have meaning to the query originator and the provider. Office will request only a single range per query.

Appendices

Appendix A: Registering a service using an installation program

You can register a service by using an installation program which writes settings the following settings described below.

Warning  The paths for the registry entries described below, as well as their names, are subject to change.

Registry Settings

The Research Library settings are stored under the HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\ResearchLibrary\Sources key, which will contain a list of all available services. The services will be grouped according to their provider. The name of each provider sub-key is a GUID (Globally Unique Identifier) unique to the provider. (For more information on GUIDs, see http://msdn.microsoft.com/library/default.asp? url=/library/en-us/msi/tref_7kf8.asp.)

Provider Values

Each provider will have the following values

Each provider will also have service or source sub-keys, whose name is also a GUID

Service Values

Registry setting for each service has the following attributes:

Source Categorization Scheme

Following is a list of categories. These categories are represented in the XML schema as enumerations.

Registry Settings Hierarchy

The registry key hierarchy for an arbitrary source looks like the following.

[HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\ResearchLibrary\ Sources\<Provider GUID>]
"ProviderName"="<Name>"
"Revision"=dword:<Revision Number>
"Type"="<Provider Type>"
"AboutPath"="<Path>"
"QueryPath"="<Path>"
"IsDeleted"="dword:<1 or 0>"

[HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\ResearchLibrary\ Sources\<Provider GUID>\<Service GUID>]
"ServiceName"="<Service UI Name>"
"ServiceId"="<Service Internal Name>"
"Description"="<Short Description Text>"
"AboutPath"="<Path>"
"TermsOfUse"="<Copyright String>"
"TermsOfUsePath"="<Path>"
"IsDeleted"="dword:<1 or 0>"
"Display"="<Current Display Status>"
"CategoryId"="<Category Index>"
"SortOrder"=dword:<Sort Order>
"OptionsPath"="<Path>"
"Parental"="<Supported | Unsupported>"
Example (matches the Registration Response example)
[HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\ResearchLibrary\ Sources\{03CDCBF6-B291-4104-BE41-EA8707DB4762}
"ProviderName"="XYZ Business Services"
"Revision"=dword:1
"Type"="SOAP
"AboutPath"="<Path>"
"RegistrationPath"="http://www.xyzservice.com/query.asmx"
"QueryPath"=" http://www.xyzservice.com/query.asmx"
"IsDeleted"="dword:<1 or 0>"

[HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\ResearchLibrary\ Sources\<Provider GUID>\{C35FDDD1-6C18-403c-9E23-A9976C305543}]
"ServiceName"="<Service UI Name>"
"ServiceId"="<Service Internal Name>"
"Description"="<Short Description Text>"
"AboutPath"="http://www.xyzservice.com/about"
"TermsOfUse"="All content Copyright (c) XYZ company."
"Display"="On"
"CategoryId"="dword:"
"Parental"="true"

Appendix B: Developing a Translation Service

Translation Service provider is expected to register itself under Translation category. (See Category ID table) Office client will have additional UI to allow user to choose to translate a portion of the document, or whole document.

Service Value

Notes

  1. Every language pair must be registered as a separate Service. So English to Japanese translation and Japanese to English translation will be a separate service.
  2. Every translation service must specify a Translation Source Type (1,2).
Translation Source Type
  1. Translate Via a Research Library Request:    When Office Customers request to get a word, phrase, sentence, or paragraphs translated (a "Research Library Request"), application will send the query in a protocol described through out the spec.
  2. Translate Via a Whole Document Request:    When Office Customers request to get an entire document translated (a "Whole Document Request"), application will upload the HTML documents to the Service via HTTP(S). This requires only one way communication, Office Customer sending document to Translation Service Provider's server. When translating a Whole Document Request, the Services is required to:
    A) Use SSL:    Use SSL to protect the privacy of the document
    B) Return a Results Page.    Return a Results Page that shall be hosted by Service provider.
©2003-2004 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at: http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp