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.
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
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.
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.
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.
Setting up and maintaining a Research Library service is a relatively easy process. If you already have a repository of data, you can:
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.
[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.
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.
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.
We expect that providers will adhere to the following rules to maintain the symmetry between the query and the response:
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.
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.)
Each provider will have the following values
Each provider will also have service or source sub-keys, whose name is also a GUID
Registry setting for each service has the following attributes:
Following is a list of categories. These categories are represented in the XML schema as enumerations.
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>"
[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"
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.
Notes