.gif)
Note: This documentation is preliminary and is subject to change.
Activities are a contextual service to access and retrieve service information from any webpage. An Activity is described using the OpenService Format.
Similar to how the OpenSearch Description describes a search provider, the OpenService Format can be used to describe any type of service provider.
- Description - The service interface that specifies the functionality of a service provider.
- File - The specific description of a service provider based off of the template for the type of service it provides.
This document covers the minimum properties necessary to enable the publication and consumption of an Activity.
OpenService Format
The OpenService format describes the core set of properties for a service.
Example:
This is an example of how to describe a map Activity using the OpenService Format.
<?xml version="1.0" encoding="UTF-8"?>
<openServiceDescription
xmlns="http://www.microsoft.com/schemas/openservicedescription/1.0">
<homepageUrl>http://maps.live.com</homepageUrl>
<display>
<name>Map with Windows Live</name>
<icon>http://www.live.com/favicon.ico</icon>
</display>
<activity category="map">
<activityAction context="selection" >
<preview action=" http://maps.live.com/geotager.aspx">
<parameter name="b" value="{selection}" />
<parameter name="clean" value="true" />
<parameter name="w" value="320" />
<parameter name="h" value="240" />
</preview>
<execute action=" http://maps.live.com/default.aspx">
<parameter name="where1" value="{selection}" type="text" />
</execute>
</activityAction>
</activity>
</openServiceDescription>The 'OpenServiceDescription' element
The root node of the OpenService document.
Parent: None
Requirements: The element must appear exactly once as the root node of the document.
Namespace - This namespace defines all of the elements in this specification. http://www.microsoft.com/schemas/openservicedescription/1.0
The 'homepageURL' element
Contains the URL of the homepage of the service provider.
Parent: openServiceDescription
Requirements: There must be only be one instance of this element
The 'display' element
Contains the display properties that are presented to the user.
Parent: openServiceDescription
Requirements: There must be only be one instance of this element
The 'name' element
Contains the name of the service. It should be able to standalone and succinctly describe the service.
It is recommended to lead with the verb followed by the name of the service.
Parent: display
Requirements:
- There must be only be one instance of this element
- The value must contain 50 or fewer characters of plain text
Examples:
<name>Map with Windows Live</name>
<name>Define with Encarta</name>
The 'icon' element
Contains a URL that identifies the location of the icon that can be used in association with the service.
Parent: display
Requirements: There can be zero or one instance of this element
Example:
<icon>http://www.live.com/favicon.ico</icon>
The 'description' element
Contains a brief description of the service.
Parent: display
Requirements:
- There can be zero or one instance of this element
- The value must contain 250 or fewer characters of plain text
Activity Description
This section covers the Activity description.
The 'activity' element
Contains the information specific to the Activity service.
Parent: openServiceDescription
Requirements: There can be zero or one instance of this element
The 'category' attribute
Contains the type of Activity. This is used in conjunction of the domain of the homepageUrl element as the identification of an Activity.
Requirements: The value must be plain text.
It is recommended to reuse a category that that other similar providers use. For example, all map providers should use the "map" category.
Example:
<activity category="map">
The 'activityAction' element
Contains the information to the specific context.
Parent: activity
Requirements: There must be at least one instance of this element
The 'context' attribute
Contains what the Activity should act on: the user selection, the current document, or the selected URL.
Requirements:
- There may be one instance of this attribute
- The value must be either "selection", "document", or "link"
- The default value is "selection"
Example:
<activityAction context="selection">
The 'preview' element
Contains the information for previewing a webpage. The returned content must be HTML that fits within a 320 width x 240 height window.
Parent: activityAction
Requirements: There can be one instance of this element
The 'action' attribute
Contains the URL template to get the webpage to preview the Activity. The Activity URL Template section contains more detail.
Requirements: There must be one instance of this attribute
The 'method' attribute
Contains the type of HTTP submission for previewing the webpage.
Requirements:
- There may be one instance of this attribute
- The value must be either "get" or "post"
- The default value is "get"
The 'enctype' attribute
Contains the type of content for submitting data to the server as defined by HTML form submission.
Requirements:
- There may be one instance of this attribute
- The value must be a supported Content-Type
- The default value is "application/x-www-form-urlencoded"
The 'accept-charset' attribute
Contains the character encoding to use for submitting data to server as defined by HTML form submission.
Requirements:
- There may be one instance of this attribute
- The value must be a supported charset
- The default value is "text"
The 'execute' element
Contains the information for executing an Activity.
Parent: activityAction
Requirements: There can be one instance of this element
The execute element uses the same set of attributes as the preview element.
The 'parameter' element
Contains the parameter name and values to for the action URL. The parameter value can reference an Activity variable. The Activity URL Template section contains more detail.
Parent: preview, execute
Requirements: There can zero or one instances of this element
The 'name' attribute
Contains the name of the parameter to use.
Requirements: There must be one instance of this attribute
The 'value' attribute
Contains the value of the parameter to use. The value can reference an Activity variable.
Requirements: There must be one instance of this attribute
The 'type' attribute
Contains how to transform the Activity variable {selection}.
Requirements:
- There can be zero or one instance of this attribute
- The value must be either "text" or "html"
- The default value is "text"
Example:
<parameter name="body" value="{selection}" type="html" />.gif)
Security Alert If you create an Activity that uses a {selection} parameter of type "html", then the service must be explicitly set up to correctly sanitize and handle arbitrary HTML input. Web services that allow arbitrary input without filtering or encoding are susceptible to HTML/script injection attacks. For more information, see the "Selection Types" section of
Activities in Internet Explorer 8.
Activity URL Template
The Activity URL template represents to pass content to the service provider. There are two ways to define parameters in a URL template: inline and form-based parameters.
Examples
This is an example of an Activity URL template using inline parameter.
<execute action="http://encarta.msn.com/encnet/refpages/search.aspx?q={selection}" />This is an example of an Activity URL template using form-based parameter.
<execute action="http://encarta.msn.com/encnet/refpages/search.aspx">
<parameter name="q" value="{selection}" type="html" />
</execute>Variables
Variables are properties within the webpage. Variables are referenced using brackets {}.
| The {selection} variable | Represents the user selection within the webpage. |
| The {documentUrl} variable | Represents the URL of the webpage where the Activity is invoked. |
| The {documentTitle} variable | Represents the title of the webpage where the Activity is invoked. |
| The {documentDomain} variable | Represents the top-level domain of the documentUrl variable. |
| The {documentHost} variable | Represents the fully-qualified domain of the documentUrl variable. |
| The {link} variable | Represents the URL of the user selected URL. |
| The {linkText} variable | Represents the text of the user selected URL. |
| The {linkRel} variable | Represents the relationship of the user selected URL. |
| The {linkType} variable | Represents the MIME type of the user selected URL. |
| The {linkDomain} variable | Represents the top-level domain of the user selected URL. |
| The {linkHost} variable | Represents the fully-qualified domain of the user selected URL. |
Optional variables
All variables are treated as required unless it the modifier "?". An optional variable that cannot be resolved is treated as an empty string for an inline parameterized URL. In a form-based parameterized URL the entire parameter element is ignored.
Example of an optional variable in an inline parameterized URL:
<execute action="http://encarta.msn.com/encnet/refpages/search.aspx?q={selection?}" />Extensibility
The OpenService format and Activity description can be extended through using W3C XML Namespace Spec .gif)
convention. The XML namespace must be distinct from the OpenService namespace.
Licensing Information
Microsoft's copyrights in this specification are licensed under the Creative Commons Attribution-Share Alike License (version 3.0). To view a copy of this license, please visit http://creativecommons.org/licenses/by-sa/3.0 . There is a separate patent promise called the Microsoft Open Specification Promise available to parties interested in implementing software that conforms to this specification. This patent promise is available at this location: http://www.microsoft.com/interop/osp/default.mspx.
Revisions
There are no revisions at this time.