[Source: http://www.oasis-open.org/committees/download.php/16895/wsdm-primer-mows-cd.doc; cache.]

Web Services Distributed Management: MOWS Primer

Committee Draft, February 24, 2006

Document identifier:

wsdm-primer-mows-cd

Location:

http://docs.oasis-open.org/wsdm/wsdm-primer-mows-cd.pdf

Editors:

Bryan Murray, Hewlett-Packard <bryan.murray@hp.com>

Kirk Wilson, Computer Associates Intl. <kirk.wilson@ca.com>

Mark Ellison, Ellison Software Consulting <ellison@ieee.org>

Abstract:

The Web Services Distributed Management: MOWS Primer provides an introduction to the Management Using Web Services (MOWS) specifications directed towards a wide audience of architects, developers, implementers and users.

This primer does not provide a definitive specification of MOWS. Rather, it is intended to provide an easily read and understood summary of the fundamentals for creating and using MOWS-compliant management applications and manageable web services.

Status:

This document is updated periodically on no particular schedule. Send comments to the editor.

Committee members should send comments on this specification to the wsdm@lists.oasis-open.org list. Others should subscribe to and send comments to the wsdm-comment@lists.oasis-open.org list. To subscribe, send an email message to wsdm-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.

For information on whether any patents have been disclosed that may be essential to implementing the MOWS specification, and any offers of patent licensing terms, Please refer to the Intellectual Property Rights section of the WSDM TC web page (http://www.oasis-open.org/committees/wsdm/).

The errata page for this specification is at http://docs.oasis-open.org/wsdm/wd-wsdm-primer-mows-cd-errata.pdf.

Table of Contents

1 Introduction: What is WSDM MOWS?. 3

1.1 Namespaces. 3

2 Web Service as a Manageable Resource. 5

2.1 A Web Service Example. 5

2.2 Associating Manageability and Functional Web service Endpoints. 6

2.2.1 Identification. 6

2.2.2 Manageability Reference. 8

2.3 Identification. 9

2.4 Operational Status. 11

2.4.1 Notifications of Operational Status Changes. 12

2.4.1.1 Supporting Topics. 12

2.4.1.2 Discovering Topics. 12

2.4.1.3 Subscribing to the Operational Status Change Notifications. 13

2.4.1.4 Notification Messages for Operational Status Changes. 13

2.5 Operational State. 14

2.6 Metrics. 15

2.6.1 Representing MOWS Metrics Metadata. 16

2.6.2 Examples MOWS Metrics. 18

2.7 Request Processing State. 19

2.7.1 Subscribing to Processing State Changes. 20

2.7.2 Notification Messages. 21

2.8 Composing Business and Management Functionality. 22

2.8.1 The Basic Printer Web Service. 22

2.8.2 The Printer’s Resource Properties Document 23

2.8.3 Printer WSDL Modifications. 25

3 Consuming Manageability for Web service Resources. 27

3.1 Obtaining Manageability Endpoints for a Web Service. 27

3.2 Determining the Health of a Web Service. 28

3.3 Retrieving Metrics. 29

3.4 Consuming Notifications. 30

3.5 Obtaining Request Processing State Information. 31

4 References. 33

Appendix A. Complete XML Documents. 34

Appendix B. Acknowledgments. 45

Appendix C. Revision History. 46

Appendix D. Notices. 47

1 Introduction: What is WSDM MOWS?

The Web Services Distributed Management (WSDM) specification for the Management Of Web Services (MOWS) [MOWS] provides a means of managing Web services.

MOWS is an extension and application of the WSDM Management Using Web Services (MUWS) [MUWS] specification. MOWS is an extension of MUWS in that MOWS uses and extends the capabilities defined in MUWS. At is simplist level, MOWS uses the same resource properties exposed by MUWS manageability capabilities. For example, the MOWS OperationalStatus capability specifies the same resource property as defined in MUWS. MOWS extends other MUWS manageability capabilities in much the same way as UML classes extend their parent classes. New properties that are special to Web services are added to those properties already defined for MUWS capabilities. For example, the MOWS Metrics capability extends the MUWS Metrics capability with metrics that are appropriate for Web services.

MOWS is an application of MUWS in that any MOWS application must also be fully compliant with the MUWS specification. Within MOWS, the MUWS concept of manageable resource, which is treated generally in MUWS as encompassing any kind of resource that is to be managed, is explicitly identified with Web services. Thus, like any MUWS manageable resource, the manageability of a Web service must be associated with a resource properties document, which exposes (at least) the MUWS Identity capability and the ManageabilityCharacteristics capability. Notice that within MOWS, the manageable resource is logically defined, a Web service, rather than a physical device such as a PDA or printer. To be sure, physical devices may be managed by means of MOWS but only if they are Web service enabled, as you shall see in section 2.8, in which we address the management of a Web service that exposes the interface to a printer.

The focus of MOWS is on Web services as WSDM manageable resources. MOWS defines capabilities, which includes properties, operations, and events, for addressing the manageability requirements of Web services. In so doing, it both uses MUWS as an application framework as well as extending several MUWS capabilities.

NOTE: In this primer, 'manageable resource' is used in the sense of a WSDM manageable resource.

1.1 Namespaces

Common namespaces used throughout this Primer are used with the following prefixes:

wsws-mgr-xs	http://example.org/services/WeatherManagementService.xsd
wsws-mgr-w	http://example.org/services/WeatherManagementService.wsdl
wsws-mgr-md	http://example.com/services/WeatherManagementService.rmd
printer-xs	http://example.org/MyWSPrintersResourceProperties.xsd
printer-w	http://example.org/services/MyWSPrinterService.wsdl
muws-p1-xs	http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd
muws-p2-xs	http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd
muws-ev	http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2-events.xml
mows-xs	http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd
mows-ev	http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows-events.xml
wsrf-rp	http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd
wsrf-rpw	http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl
wsrf-bf	http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-BaseFaults-1.2-draft-02.xsd
wsnt	http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd
wstop	http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd
rmd	http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd
xs	http://www.w3.org/2001/XMLSchema
w	http://schemas.xmlsoap.org/wsdl
s	http://schemas.xmlsoap.org/soap/envelope/
soapw	http://schemas.xmlsoap.org/wsdl/soap/
wsa	http://schemas.xmlsoap.org/ws/2005/08/addressing

Namespace declarations will not be provided in example code (XML) [XML] unless explicitly referred to in the text or is specific to that example. Please refer back to this table for the meaning of namespace prefixes. See Appendix A for an unabridged rendering of the example XML documents.

2 Web Service as a Manageable Resource

2.1 A Web Service Example

In this section, we will use what we have discussed in the Web Services Distributed Management: MUWS Primer to provide the manageability for a manageable resource that is a Web service. Consider a weather station Web service. The weather station might provide such services as reporting the current temperature, barometric pressure, and wind conditions as well as forward looking weather predictions for a specified time period. The following Web service example uses a simple GetCurrentTemperature operation that returns a temperature based upon an altitude.

Note that our weather station Web service is a simple XML Web service, and, therefore, does not require the use of an EPR to reference it. A WSDL document [WSDL] describing a WeatherStation Web service is as follows:

<?xml version="1.0" encoding="utf-8"?>

<w:definitions

. . . <! Standard namespace declaration -->

xmlns:tns="http://example.org/"

targetNamespace="http://example.org/">

<w:types>

<xs:schema elementFormDefault="qualified"

targetNamespace="http://example.org/">

<xs:element name="GetCurrentTemperature">

<xs:complexType>

<xs:sequence>

<xs:element name="altitude" type="xs:double"

minOccurs="1" maxOccurs="1"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="GetCurrentTemperatureResponse">

<xs:complexType>

<xs:sequence>

<xs:element name="GetCurrentTemperatureResult" type="xs:double"

minOccurs="1" maxOccurs="1"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

</w:types>

<w:message name="GetCurrentTemperatureIn">

<w:part name="parameters" element="tns:GetCurrentTemperature" />

</w:message>

<w:message name="GetCurrentTemperatureOut">

<w:part name="parameters" element="tns:GetCurrentTemperatureResponse" />

</w:message>

<w:portType name="WeatherStationPortType">

<w:operation name="GetCurrentTemperature">

<w:input message="tns:GetCurrentTemperatureIn" />

<w:output message="tns:GetCurrentTemperatureOut" />

</w:operation>

</w:portType>

<w:binding name="WeatherStationSoap" type="tns:WeatherStationPortType">

...

</w:binding>

<w:service name="WeatherStation">

<w:port name="WeatherStationPort" binding="tns:WeatherStationSoap">

<soapw:address location="http://example.org/services"/>

</w:port>

</w:service>

</w:definitions>

Note that this Web service does not support manageability; that is, the manageability endpoint for this service is different from the endpoint for the Web service itself (the manageable endpoint). See section 4 of the MOWS specification for information of relationship between manageability and manageable endpoints for Web services.

2.2 Associating Manageability and Functional Web service Endpoints

For our example, we use the name WeatherManagementService for the Web service providing manageability endpoints for a WeatherStation service. Our first task is to specify an XML schema [XML Schema] for the resource properties document [WS-ResourceProperties]. By following the same pattern as used by the examples in the MUWS primer, our namespace URI for the resource properties document XML Schema would be http://example.org/services/WeatherManagementService.xsd.

The reader should review section 2 of the MUWS Primer on the fundamentals of defining a manageability endpoint.

2.2.1 Identification

The endpoint for accessing our WeatherManagementService should include the properties required to support the MUWS Identity capability and the MUWS ManagementCharacteristics capability. As we progress through this example, additional manageability capabilities will be added to this endpoint. An XML Schema for our WeatherManagementService resource properties document that exposes these two capabilities would appear as follows:

<xs:schema

targetNamespace="http://example.org/services/WeatherManagementService.xsd"

. . .

elementFormDefault="qualified" attributeFormDefault="unqualified">

<xs:element name="WeatherManagermentServiceProperties">

<xs:complexType>

<xs:sequence>

<xs:element ref="muws-p1-xs:ResourceId"/>

<xs:element ref="muws-p1-xs:ManageabilityCapability"

maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

Notice that in this example, we have modified the cardinality of the <ManageabilityCapability> element. In the MOWS schema, <ManageabilityCapability> is specified with minOccurs = '0'. However, because we know the manageability endpoint will support the manageability capabilities, we can restrict the resource properties document by removing the minOccurs attribute.

An example of a resource properties document conforming to this schema is as follows:

<wsws-mgr-xs:WeatherManagementServiceProperties . . .>

<muws-p1-xs:ResourceId>

urn:uuid:E3A0B27A-45E0-40af-A15B-1CDC263F24CE

</muws-p1-xs:ResourceId>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics

</muws-p1-xs:ManageabilityCapability>

</wsws-mgr-xs:WeatherManagementServiceProperties>

There is only one manageable resource in this scenario; thus, we do not need a schema to define a resource identifier element for the weather station service.

The relevant sections of the WSDL for the manageability endpoint are as follows:

<w:definitions

targetNamespace="http://example.org/services/WeatherManagementService.wsdl"

. . .>

<w:types>

<xs:schema>

<xs:import namespace="http://example.org/services/WeatherManagementService.xsd"

schemaLocation="http://example.org/services/WeatherManagementService.xsd"/>

<xs:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"

schemaLocation="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"/>

<xs:import namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"/>

</xs:schema>

</w:types>

<w:portType name="WeatherManagementServicePortType"

wsrf-rp:ResourceProperties="wsws-mgr-xs:WeatherManagementServiceProperties">

<w:operation name="GetResourceProperty">

<w:input name="GetResourcePropertyRequest"

message="wsrf-rpw:GetResourcePropertyRequest"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourcePropertyDocument/GetResourcePropertyRequest"/>

<w:output name="GetResourcePropertyResponse"

message="wsrf-rpw:GetResourcePropertyResponse"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourcePropertyDocument/GetResourcePropertyResponse"/>

</w:portType>

<w:binding name="WeatherManagementServiceBinding"

type="WeatherManagementServicePortType">

</w:binding>

<w:service name="WeatherManagementService">

<w:port name="WeatherManagementServicePort">

binding="WeatherManagementServiceBinding">

<soapw:address

location="http://example.org/services/WeatherManagementServiceEndpoint"/>

</w:port>

</w:service>

</w:definitions>

The inclusion of other WSRF-RP operations in the above schema, such as GetMultipleResourceProperties and GetResourceDocument, is left to the discretion of the designer.

For more information of faults, see WS-BaseFaults [WS-BaseFaults].

An end-point reference (EPR) for the manageability endpoint is as follows:

<wsa:EndpointReference

<wsa:Address>

http://example.org/services/WeatherManagementServiceEndpoint

</wsa:Address>

</wsa:EndpointReference>

2.2.2 Manageability Reference

One means by which a management application can obtain the EPR for a manageability endpoint of a weather station Web service is to ask the weather station Web service itself. In order for a weather station Web service to provide this information to clients, its portType must include the GetManageabilityReferences operation. See section 5.1.1.1 in the MOWS specification for more information on the GetManageabilityReferences operation.

This approach of providing a management application with the EPR for a manageability endpoint is not required. Alternative approaches support discovery of the manageability endpoint of a Web service. For example, the inclusion of the EPR in a directory or a registry of manageable resources allows a management application to select the appropriate EPR from the directory or registry. For more information on obtaining the EPR for a manageability endpoint of a web service, see section 4.1 of the MUWS Primer.

In this section, we expand the functional interface of our example weather station Web service. We add the GetManageabilityReferences operation, which returns a set of EPRs. Since our example implements only one manageability endpoint for our weather station Web service, a set containing one EPR will be returned from the GetManageabilityReferences operation of our example Web service.

To incorporate the GetManageabilityReferences operation into the WSDL document describing our example weather station Web service we need to declare a namespace prefix and import the MOWS XML Schema, which defines the IN/OUT elements of the operation and imports the definition of the MUWS Part 1 ManageabilityEndpointReference element. This element is the return value of the GetManageabilityReferences operation. We can define new messages as follow:

</message>

</message>

To make use of these new messages, we must extend the current portType definition of our weather station Web service to include our new operation as follows:

<input name="GetManageabilityReferencesRequest"

message="tns:GetManageabilityReferencesRequest"/>

<output name="GetManageabilityReferencesResponse"

message="tns:GetManageabilityReferencesResponse"/>

</operation>

There is no need to include the wsrf-rp:ResourceProperties attribute within the portType. The GetMangeabilityReferences operation does not require our weather station Web service to be a WS-Resource. It is still a traditional Web service, albeit extended to provide access to its manageability endpoint.

The WeatherStation WSDL, with all required additions highlighted, would appear as follows:

<w:definitions . . .

xmlns:tns="http://example.org/"

targetNamespace="http://example.org/">

<w:types>

<xs:schema elementFormDefault="qualified"

targetNamespace="http://example.org/">

<xs:import namespace="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd" schemalocation="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd">

</xs:schema>

</w:types>

,!-- GetCurrentTermperature messages -->

<w:message name="GetManageabilityReferencesRequest">

<w:part name="body" element="mows-xs:GetManageabilityReferences"/>

</w:message>

<w:message name="GetManageabilityReferencesResponse">

<w:part name="body" element="mows-xs:GetManageabilityReferencesResponse"/>

</w:message>

<w:portType name="WeatherStationPortType">

<w:operation name="GetManageabilityReferences">

<w:input name="GetManageabilityReferencesRequest"

message="tns:GetManageabilityReferencesRequest"/>

<w:output name="GetManageabilityReferencesResponse"

message="tns:GetManageabilityReferencesResponse"/>

</w:operation>

</w:portType>

</w:definitions>

The request to get the ManageabilityReference of our weather station Web service is as follows:

<mows-xs:GetManageabilityReferences/>

The response to the above request is a message containing the EPR of the manageability endpoint of our Web service:

<mows-xs:GetManageabilityReferencesResponse>

<muws-p1-xs:ManageabilityEndpointReference>

<wsa:EndpointReference>

<wsa:Address>

http://example.org/services/WeatherManagementServiceEndpoint

</wsa:Address>

</wsa:EndpointReference>

</muws-p1-xs:ManageabilityEndpointReference>

</mows-xs:GetManageabilityReferencesResponse>

2.3 Identification

Under the scenario where the manageability endpoint and the endpoint of a manageable resource are not the same, a MOWS compliant resource should support the MOWS Identification capability. In contrast to the MUWS Identity capability, the MOWS Identification capability helps to describe the Web service endpoint being managed. See section 5.2.2 of the MOWS specification for more information.

Support for the MOWS Identification capability requires the inclusion of two properties in the schema of the resource properties document. Our example schema is as follows:

<xs:element name="WeatherManagermentServiceProperties">

<xs:complexType>

<xs:sequence>

<xs:element ref="muws-p1-xs:ResourceId"/>

<xs:element ref="mows-xs:EndpointReference"/>

<xs:element ref="mows-xs:EndpointDescriptions"/>

<xs:element ref="muws-p1-xs:ManageabilityCapability"

minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

</xs:element>

The appropriate element statements may be cut-and-pasted from the EndpointIdentificationPropertiesType in the MOWS schema. Notice, however, that again we have modified the schema by removing the minOccurs='0' from the EndpointDescriptions element.

The message exchange pattern for retrieving values of these two new properties is already provided by theGetResourceProperty operation.

The resource properties document should also include the manageability capability URI for the MOWS Identification capability. Our example resource properties document modified to include the two new properties appears as follows:

<wsws-mgr-xs:WeatherManagementServiceProperties . . .>

<muws-p1-xs:ResourceID>

urn:uuid:E3A0B27A-45E0-40af-A15B-1CDC263F24CE

</muws-p1-xs:ResourceID>

<mows-xs:EndpointReference>

<wsa:Address

http://example.org/services/WeatherStation

</wsa:Address>

</mows-xs:EndpointReference>

<mows-xs:EndpointDescriptions>

<mows-xs:description>

http://example.org/service?WSDL

</mows-xs:description>

</mows-xs:EndpointDescriptions>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Identification

</muws-p1-xs:ManageabilityCapability>

</wsws-mgr-xs:WeatherManagementServiceProperties"

TheEndpointDescriptions property provides the URLs to documents describing the weather station Web service.

A manageability consumer is able to request a description of the service being managed as follows:

<wsrf-rp:GetResourceProperty>

mows-xs:EndpointDescriptions

</wsrf-rp:GetResourceProperty>

Since the message in the above exchange is targeted at a WS-Resource, it is necessary to use WS-Addressing [WS-Addressing] in the message exchange. Therefore the appropriate wsa:Action for the GetResourceProperty operation must be included in the SOAP Header [SOAP].

The response for the above request is a message containing the URL(s) of any documents describing the managed Web service:

<wsrf-rp:GetResourcePropertyResponse>

<mows-xs:EndpointDescriptions >

<mows-xs:description>http://example.org?WSDL</mows-xs:description>

</mows-xs:EndpointDescriptions>

</wsrf-rp:GetResourcePropertyResponse>

A manageability consumer is now able to dereference each URL contained in the <description> element.

2.4 Operational Status

The operational status and the operational state (section 2.5) of a Web service are among the properties a manageability consumer may wish to access. In this section, we add a property to our example resource properties document exposing the operational status for our Web service. A manageability consumer can learn whether a managed Web service is available, unavailable or partially available. For example, the Web service may be unavailable because the Web service is shut down for maintenance. Or the Web service may be only partially available because an operation lacks access to a necessary resource. See section 5.2.5 of the MOWS specification for more information about the MOWS Operational Status capability.

Support for the MOWS Operational Status capability requires the inclusion of the OperationalStatus property from MUWS Part 2 into the resource properties document. We modify our example schema by importing the Operational Status capability from the MOWS specification, and by including the MUWS Part 2 OperationalStatus property as follows:

<xs:element name="WeatherManagermentServiceProperties">

<xs:complexType>

<xs:sequence>

...

<xs:element ref="muws-p2-xs:OperationalStatus"/>

</xs:sequence>

</xs:complexType>

</xs:element>

We copy the appropriate element statement from the OperationalStatusPropertiesType definition from Part 2 of the MUWS specification and paste it into our schema.

We want the resource properties instance document for our example endpoint to contain the MOWS manageability capability for this capability. A resource properties document supporting the MOWS OperationalStatus capability appears as follows:

<wsws-mgr-xs:WeatherManagementServiceProperties . . .>

...

<muws-p2-xs:OperationalStatus>

Available

</muws-p2-xs:OperationalStatus>

...

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/OperationalStatus

</muws-p1-xs:ManageabilityCapability>

</wsws-mgr-xs:WeatherManagementServiceProperties"

A manageability consumer is now able to request the operational status of a Web service through the following message exchange:

<wsrf-rp:GetResourceProperty>

muws-p2-xs:OperationalStatus

</wsrf-rp:GetResourceProperty>

The response to the above might appears as follows:

<wsrf-rp:GetResourcePropertyResponse>

<muws-p2-xs:OperationalStatus

Available

</muws-p2-xs:OperationalStatus>

</wsrf-rp:GetResourcePropertyResponse>

2.4.1 Notifications of Operational Status Changes

In addition to retrieving the operational status of a Web service, a manageability consumer can receive a notification when the operational status of a Web service changes. When a critical Web service transitions operational status from available to unavailable, a business disaster may soon follow if a management application fails to discover the situation in a timely manner. Instead of a manageability consumer periodically requesting the operation status from the critical Web service, the Web service or its management service notifies the consumer when a critical status change occurs. For more information on Notifications, see section 2.10 of the MUWS Primer.

2.4.1.1 Supporting Topics

Both MUWS Part 2 and MOWS define TopicSpaces. See section 2.10.4 of the MUWS Primer for more information on Topics. A management service that supports topics should expose the Topic resource property in a resource properties document as follows:

<xs:element name="WeatherManagermentServiceProperties">

<xs:complexType>

<xs:sequence>

...

<xs:element ref="wsnt:Topic"

minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

</xs:element>

The portion of a resource properties instance document exposing resource support for the OperationalStatusCapability topic appears as follows.

<wsws-mgr-xs:WeatherManagementServiceProperties ...>

...

<wsnt:Topic . . .

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatusCapability

</wsnt:Topic>

</wsws-mgr-xs:WeatherManagementServiceProperties"

Notice that the OperationalStatusCapability topic belongs to the MuwsNotificationTopics TopicsSpace (muws-ev).

A manageable resource supporting the OperationalStatusCapability topic is expected to emit a notification upon a change in the operational status of a managed Web service.

2.4.1.2 Discovering Topics

To discover the Topics on which a management service emits notifications, a manageability consumer might first send a GetResourceProperty to the service’s manageability endpoint as follows:

<wsrf-rp:GetResourceProperty>

wsnt:Topic

</wsrf-rp:GetResourceProperty>

The response to the above request is a message containing the list of topics supported by the manageability endpoint and appears as follows

<wsrf-rp:GetResourcePropertyResponse>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatusCapability

</wsnt:Topic>

</wsrf-rp:GetResourcePropertyResponse>

In the above response, the muws-ev:OperationalStatusCapability is found within the list of returned topics. Thus, the manageability consumer can send a subscription for the notification of events pertaining to this topic and manageable endpoint.

2.4.1.3 Subscribing to the Operational Status Change Notifications

Because our weather station Web service manageability endpoint exposes support for at least one topic, the Web service must support the Subscribe operation and must accept SubscribeRequest messages. In the following example message, the manageability consumer indicates that it accepts messages on topics at the URL http://example.org/WSManager:

<wsnt:Subscribe>

<wsnt:ConsumerReference>

<wsa:EndpointReference>

<wsa:Address>

http://example.org/WSManager/

</wsa:Address>

</wsa:EndpointReference>

</wsnt:ConsumerReference>

<wsnt:TopicExpression Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatus

</wsnt:TopicExpression>

</wsnt:Subscribe>

Note that the Schema and WSDL documents for an example management application are not defined in this primer.

The above subscription request does not provide an InitialTerminationTime. Thus the subscription is expected to continue in perpetuity. Also, because the useNotify element was not specified (the default value of this element is 'true', messages sent on the specified topic to a manageability consumer are wrapped in a <Notify> element. The manageability consumer must be prepared to accept this wrapped element.

If the subscription is accepted by the manageability endpoint, then the subscriber receives a response. Our example response appears as follows:

<wsnt:SubscribeResponse>

<wsnt:SubscriptionReference>

<wsa:EndpointReference>

<wsa:Address>

http://example.org/services/WeatherManagementServiceEndpoint

</wsa:Address>

<wsa:ReferenceParameters>

991be01c-e5ca-4d00-811e-b6e29079e7da

</SubscriptionId>

</wsa:ReferenceParameters>

</wsa:EndpointReference>

</wsnt:SubscriptionReference>

</wsnt:SubscribeResponse>

2.4.1.4 Notification Messages for Operational Status Changes

The manageability endpoint of the Web service should produce a notification when the weather station Web service transitions from an Available to an Unavailable state. Notifications regarding manageability capabilities should be raised as Management Events, and include the <Situation> element, as described in section 2.5.1 of the MUWS Part 2 specification. In addition, the payload of this notification is wrapped in ResourcePropertyChangeNotification element, which is defined in section 6.1 of the WS-ResourceProperties specification. An example notification message appears as follows:

<wsnt:Notify>

<wsnt:NotificationMessage>

<wsnt:SubscriptionReference>

<wsa:Address>

http://example.org/services/WeatherManagementServiceEndpoint

</wsa:Address>

</wsnt:SubscriptionReference>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatusCapability

</wsnt:Topic>

. . .

<wsnt:Message>

<muws-p1-xs:ManagementEvent>

. . .

<muws-p2-xs:Situation>

. . .

</muws-p2-xs:Situation>

<wsrf-rp:ResourcePropertyValueChangeNotification>

<wsrf-rp:OldValues>

<muws-p2-xs:OperationalStatus>

Available

</muws-p2-xs:OperationalStatus>

</wsrf-rp:OldValues>

<wsrf-rp:NewValues>

<muws-p2-xs:OperationalStatus>

Unavailable

</muws-p2-xs:OperationalStatus>

</wsrf-rp:NewValues>

</wsrf-rp:ResourcePropertyValueChangeNotification>

</muws-p1-xs:ManagementEvent>

</wsnt:Message>

</wsnt:NotificationMessage>

</wsnt:Notify>

2.5 Operational State

For some Web services, it is sufficient for a manageability consumer to have knowledge only of the operational state for the Web service. The Web service lifecycle [WSLC] specification also provides a state model of Web services. When managing complex Web services, it may be important for the manageability endpoint of a Web service to provide access to the current operational state of the managed Web service. For more information on the MOWS OperationalState capability, see section 5.2.4 of the MOWS specification.

To support the MOWS OperationalState capability we include two properties in the resource properties document schema as follows:

<xs:element name="WeatherManagermentServiceProperties">

<xs:complexType>

<xs:sequence>

...

<xs:element ref="mows-xs:CurrentOperationalState"/>

<xs:element ref="mows-xs:LastOperationalStateTransition"

minOccurs="0"/>

</xs:sequence>

</xs:complexType>

</xs:element>

As in previous examples, we copy-and-paste the appropriate element statements from the EndpointOperationalStatePropertiesType, defined in the MOWS specification. (Because LastOperationalStateTransition information may not always be available, we retain the minOccurs='0' in this case. For more information on the MUWS StateTransitionType, see section 3.2.3 in Part 2 of the MUWS specification.)

Our resource properties document should also contain the manageability capability URI for this capability.

A resource properties document containing the new properties supporting the MOWS OperationalState capability would appear as follows:

<wsws-mgr-xs:WeatherManagementServiceProperties ...>

...

<mows-xs:CurrentOperationalState>

<mows-xs:BusyState>

<mows-xs:UpState/>

</mows-xs:BusyState>

</mows-xs:CurrentOperationalState>

<mows-xs:LastOperationalStateTransition>

<muws-p2-xs:StateTransition Time="2005-06-11T10:02:35Z">

<muws-p2-xs:EnteredState>

<mows-xs:Upstate/>

</muws-p2-xs:EnteredState>

<muws-p2-xs:PreviousState>

<mows-xs:SaturatedState>

<mows-xs:DownState/>

</mows-xs:SaturatedState>

</muws-p2-xs:PreviousState>

</muws-p2-xs:StateTransition>

</mows-xs:LastOperationalStateTransition>

...

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/OperationalState

</muws-p1-xs:ManageabilityCapability>

</wsws-mgr-xs:WeatherManagementServiceProperties"

The OperationalState property shows that the Web service is currently in the Busy state, which is a form of the Up-state. The Web service is busy processing requests, but may accept new requests. As the optional (but recommended) LastOperationalStateTransition shows, the current state is a result of recovering from a previous state of saturated (down).

A Manageability consumer may now request the operational state of a Web service as follows:

<wsrf-rp:GetResourceProperty>

mows-xs:CurrentOperationalState

</wsrf-rp:GetResourceProperty>

The response to the above request might appears as follows:

<wsrf-rp:GetResourcePropertyResponse>

<mows-xs:CurrentOperationalState >

<mows-xs:BusyState>

<mows-xs:UpState/>

</mows-xs:BusyState>

</mows-xs:CurrentOperationalState>

</wsrf-rp:GetResourcePropertyResponse>

2.6 Metrics

The metrics pertaining to a Web service is of major interest to a manageability consumer responsible for the performance of the Web service. In this section we add MUWS and MOWS properties supporting the metrics of a Web service. The MOWS Metrics capability extends the MUWS Metrics capability. Thus, manageability endpoints supporting the MOWS Metrics capability also must support the MUWS Metrics capability. (See section 2.8 of the MUWS Primer for more information on extended WSDM capabilities.) For more information about the MOWS Metrics manageability capability, see section 5.2.3 in the MOWS specification.

We include the following properties in the resource properties document schema:

<xs:element name="WeatherManagementServiceProperties">

<xs:complexType>

<xs:sequence>

...

<xs:element ref="muws-p2-xs:CurrentTime"/>

<xs:element ref="mows-xs:NumberOfRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfFailedRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfSuccessfulRequests" minOccurs="0"/>

<xs:element ref="mows-xs:ServiceTime" minOccurs="0"/>

<xs:element ref="mows-xs:MaxResponseTime" minOccurs="0"/>

<xs:element ref="mows-xs:LastResponseTime" minOccurs="0"/>

</xs:sequence>

</xs:complexType>

</xs:element>

The muws-p2-xs:CurrentTime property may be copied from the MetricsPropertiesType in Part 2 of the MUWS schema. The MOWS properties may be copied from the EndpointMetricPropertiesType in the MOWS schema. Notice that we have retained the cardinality of minOccurs='0' for each metric. Thus, our manageability endpoint may choose not to expose some metrics, for example, if it does not have a value for the metric rather than publishing a zero.

Further metrics may be logically derived from these metrics. For example, it would be possible to calculate the average response time as the NumberOfRequests / ServiceTime. In using multiple metrics in a calculation, it is necessary to insure that the metrics have been collected on comparable time scales. The result of NumberOfRequests / ServiceTime would be meaningless if the metrics were gathered over different lengths of time.

In a resource properties instance document, metric properties must be qualified by either a ResetAt datetime attribute, a LastUpdated datetime attribute, or a Duration attribute (see section 2.7.2 in the MUWS Primer for more information on these attributes). The attributes that may qualify a specific metric is constrained by the semantics of that metric. The semantics of metrics is described by means of their metadata. (See also section 2.11.2 in the MUWS Primer for further information on metric metadata.)

2.6.1 Representing MOWS Metrics Metadata

The metadata of MOWS metrics is defined in section 5.2.3.2 of the MOWS specification The following table below summarizes the metadata for the MOWS metrics.

MOWS Metric Property	Type	Metadata: ChangeType	Metadata: TimeScope	Metadata: GatheringTime
NumberOfRequests	IntegerCounter	Counter	SinceReset Interval	OnChange
NumberOfSuccessful Requests	IntegerCounter	Counter	SinceReset Interval	OnChange
NumberOfFailed Requests	IntegerCounter	Counter	SinceReset Interval	OnChange
ServiceTime	DurationMetric	Gauge	SinceReset Interval	OnChange
MaxResponseTime	DurationMetric	Gauge	SinceReset Interval	OnChange
LastResponseTime	DurationMetric	Gauge	PointInTime	OnChange

This information is expressed in a metadata document. Section 2.11 in the MUWS Primer describes the structure of a metadata document. The metadata description of the MOWS metric properties is as follows:

<rmd:Property path="mows-xs:NumberOfRequests"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:NumberOfFailedRequests"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:NumberOfSuccessfulRequests"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:ServiceTime"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:MaxResponseTime"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:LastResponseTime"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>PointInTime</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

See Appendix A for a complete metadata document for the WeatherStation service manageability endpoint.

2.6.2 Examples MOWS Metrics

The resource properties document of a managed Web service must conform to the metadata specification of the MOWS metrics. For example, a resource properties document that exposes the first five MOWS metric properties as TimeScope='SinceReset' would expose the MOWS metrics with ResetAt and LastUpdated attributes as follows:

<wsws-mgr-xs:WeatherManagementServiceProperties ...>

...

<muws-p2-xs:CurrentTime>2005-06-14T14:25:21.6589722-04:00</muws-p2-xs:CurrentTime>

<mows-xs:NumberOfRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">1556</mows-xs:NumberOfRequests>

<mows-xs:NumberOfSuccessfulRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">1549</mows-xs:NumberOfSuccessfulRequests>

<mows-xs:NumberOfFailedRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.1881806-04:00">7</mows-xs:NumberOfFailedRequests>

<mows-xs:ServiceTime ResetAt="2005-06-13T14:24:20.2582128-04:00" LastUpdated="2005-06-14T14:24:58.2181944-04:00">PT3H28M13.52S</mows-xs:ServiceTime>

<mows-xs:MaxResponseTime ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-13T16:12:36.3763419-04:00">PT12.02S</mows-xs:MaxResponseTime>

<mows-xs:LastResponseTime LastUpdated="2005-06-13T14:24:58.2582128-04:00">PT0.015S</mows-xs:LastResponseTime>

...

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p1-xs:ManageabilityCapability>

</wsws-mgr-xs:WeatherManagementServiceProperties>

On the other hand, if a resource properties document treats the first five MOWS metric properties as TimeScope='Interval', then the preceding resource properties document snippet would use the Duration attribute rather than the ResetAt attribute as follows (where the duration of the collecting the data is the last 24 hours):

<muws-p2-xs:CurrentTime>2005-06-14T14:25:21.6589722-04:00</CurrentTime>

<mows-xs:NumberOfRequests LastUpdated="2005-06-14T14:24:58.2582128-04:00" Duration="PT24H">1556</mows-xs:NumberOfRequests>

<mows-xs:NumberOfSuccessfulRequests LastUpdated="2005-06-14T14:24:58.2582128-04:00" Duration="PT24H">1549</mows-xs:NumberOfSuccessfulRequests>

<mows-xs:NumberOfFailedRequests LastUpdated="2005-06-14T14:24:12.1881806-04:00" Duration="PT24H">7</mows-xs:NumberOfFailedRequests>

<mows-xs:ServiceTime LastUpdated="2005-06-14T14:24:58.2181944-04:00" Duration="PT24H">PT3H28M13.52S</mows-xs:ServiceTime>

<mows-xs:MaxResponseTime LastUpdated="2005-06-13T16:12:36.3763419-04:00" Duration="PT24H">PT10.02S</mows-xs:MaxResponseTime>

While the GetResourceProperty operation may be used to retrieve a single metric, we recommend that management applications support and use the GetMultipleResourceProperties operation for requesting metrics. For example, it is desirable for a management application to receive data on the NumberOfRequests, NumberOfSuccessfulRequests, and NumberOfFailedRequests for the same time period and interval. The span of time involved in separate requests for each metric might produce less consistent results. In our example, a management application would request metrics via the following exchange:

<wsrf-rp:GetMultipleResourceProperties>

<wsrf-rp:ResourceProperty>

muws-p2-xs:CurrentTime

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

mows-xs:NumberOfRequests

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

mows-xs:NumberOfSuccessfulRequests

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

mows-xs:NumberOfFailedRequests

</wsrf-rp:ResourceProperty>

</wsrf-rp:GetMultipleResourceProperties>

If the TimeScope='SinceReset' for the requested metrics, then a response to the above request appears as follows:

<wsrf-rp:GetMultipleResourcePropertiesResponse>

<muws-p2-xs:CurrentTime>

2005-06-14T14:25:21.6589722-04:00

</muws-p2-xs:CurrentTime>

<mows-xs:NumberOfRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">

1556

</mows-xs:NumberOfRequests>

<mows-xs:NumberOfSuccessfulRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">

1549

</mows-xs:NumberOfSuccessfulRequests>

<mows-xs:NumberOfFailedRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.1881806-04:00">

</mows-xs:NumberOfFailedRequests>

</wsrf-rp:GetResourceMultiplePropertiesResponse>

2.7 Request Processing State

A manageability consumer may also wish to be notified of the state of a request that is being processed by a Web service. The processing states of a request are Received, Processing, Failed, and Completed.

For example, let us assume that a GetCurrentTemperature request that has been sent to our weather station Web service changes state from Processing to Completed. A manageability consumer can subscribe to notifications whenever a request changes processing state.

The manageability consumer may receive notifications for:

§ All processing state changes as they occur

§ A select sub-set of such notifications, for example, the manageability consumer may receive notifications only for transitions to the Failed or Completed states

§ A 'digest' or "history" of state transitions the request underwent.

See section 5.2.6 of the MOWS specification for more information regarding the RequestProcessingState manageability capability.

The MOWS RequestProcessingState capability requires no new properties be included in our resource properties document. However, our resource properties document should include a statement indicating that the RequestProcessingState capability is supported. This statement appears as follows:

<wsws-mgr-xs:WeatherManagementServiceProperties . . .>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/RequestProcessingState

</muws-p1-xs:ManageabilityCapability>

</wsws-mgr-xs:WeatherManagementServiceProperties"

Our resource properties document should also specify what Topics are supported for emitting management events. As an example, support for emitting notifications for all request processing state changes is specified using the mows-ev:RequestProcessingObservations topic and appears as follows:

<wsws-mgr-xs:WeatherManagementServiceProperties ...>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Simple">

mows-ev:RequestProcessingStateCapability

</wsnt:Topic>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Simple">

mows-ev:RequestProcessingObservations

</wsnt:Topic>

</wsws-mgr-xs:WeatherManagementServiceProperties

Use the TopicExpression/Concrete dialect, described in section 7.2 of the WS-Topics specification, when specifying support for a subtopic. For example, supporting notifications of digests would require a topic specification as follows:

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Concrete">

mows-ev:RequestProcessingObservations/Digest

</wsnt:Topic>

2.7.1 Subscribing to Processing State Changes

In order to subscribe to the RequestProcessingObservations topic, our request appears as follows:

<wsnt:Subscribe>

<wsnt:ConsumerReference>

...

</wsnt:ConsumerReference>

<wsnt:TopicExpression

Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Simple">

mows-ev:RequestProcessingObservations

</wsnt:TopicExpression>

</wsnt:Subscribe>

If we subscribe to a digest of request processing state changes, then the topic specification in our request appears as follows:

<wsnt:TopicExpression

Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Concrete">

mows-ev:RequestProcessingObservations/Digest

</wsnt:TopicExpression>

The response to the above subscription request is described in section 2.7.2 of this primer.

2.7.2 Notification Messages

Notifications emitted on the RequestProcessingObservations topic must contain at most one element referring to the new state of a request. For example either RequestReceivedState or RequestProcessingState would appear. This constraint is expressed in the StateTransition/EnteredState element in our example as follows:

<wsnt:Notify>

<wsnt:NotificationMessage>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Simple">

mows-ev:RequestProcessingObservations

</wsnt:Topic>

<wsnt:Message>

<muws-p1-xs:ManagementEvent ReportTime="2005-06-16T08:24:34.7940060-04:00">

.. . .

<muws-p2-xs:Situation>

. . .

</muws-p2-xs:Situation>

<mows-xs:RequestProcessingNotification CurrentTime="2005-06-16T08:24:34.7940060-04:00">

<mows-xs:Request>

. . .

</mows-xs:Request>

<mows-xs:StateInformation>

<muws-p2-xs:StateTransition Time="2005-06-16T08:24:34.7940060-04:00">

<muws-p2-xs:EnteredState>

<mows-xs:RequestCompletedState/>

</muws-p2-xs:EnteredState>

<muws-p2-xs:PreviousState>

<mows-xs:RequestProcessingState/>

</muws-p2-xs:PreviousState>

</muws-p2-xs:StateTransition>

</mows-xs:StateInformation>

</mows-xs:RequestProcessingNotification>

</muws-p1-xs:ManagementEvent>

</wsnt:Message>

</wsnt:NotificationMessage>

</wsnt:Notify>

The above notification describes a transition from ProcessingState to CompletedState for a particular request. Notice that exactly one occurrence of the <RequestProcessingNotification> element is stipulated by the MessagePattern element of the RequestProcessingObservations Topic definition as follows:

<wstop:Topic name="RequestProcessingObservations"

messageTypes="muws-p1-xs:ManagementEvent">

//muws-p1-xs:ManagementEvent[muws-p2-xs:Situation/muws-p2-xs:SituationCategory//muws-p2-xs:ReportSituation and muws-p2-xs:Severity="1" and count(mows-xs:RequestProcessingNotification)=1]

</MessagePattern>

...

</wstop:Topic>

See the MOWS Schema for the definition of the <RequestProcessingNotification> element.

2.8 Composing Business and Management Functionality

The examples presented in sections 2.2 through 2.7 of this primer rely upon a manageability endpoint that is independent of and separate from the endpoint for our managed Web service. In this section we address a scenario in which business functionality (the endpoint for our manageable Web service) and management capability (the manageability endpoint) are composed together into the same endpoint. To compose a management and a functional endpoint, each endpoint must be a WS-Resource. Up to this point in the MOWS primer, our example of a weather station Web service is not itself a WS-Resource. Thus a separate WS-Resource to manage our weather station Web service was necessary. In this section our examples are based upon the composition of business functionality and management capability into the same endpoint.

Consider an example of a a printer resource enabled as a Web-service. The printer may have a business/functional interface consisting of the operation Print(…). The argument to this operation may be a URL to the location of the document that is to be printed. Such a printer could offer its printing service at an enterprise level.

The Web service endpoint for the printer could be a WS-Resource. This architecture would allow the Web service interface of the printer to support management functions in addition to the Print service. Some of the management capabilities supported by the WS-Resource may, in fact, be related to specific printer management functionality such as exposing available toner capacity (printer properties) and printed page counts (printer metrics).

Moreover, because this printer presents a Web service interface, it is possible to include MOWS management capabilities to manage the printer’s Web service through the same endpoint. Both the clients of the printer Web service and management applications take advantage of the same Web service endpoint. For additional information about this example, see section 2.2 in the MOWS specification.

2.8.1 The Basic Printer Web Service

The basic printer Web service in our example is the MyWSPrinterService and provides a Print operation. This operation accepts a URL and has no return argument. An example of the WSDL describing this service appears as follows:

<w:definitions

. . .

xmlns:tns="http://example.org/"

targetNamespace="http://example.org/">

<w:types>

<xs:schema elementFormDefault="qualified"

targetNamespace="http://example.org/">

<xs:element name="Print">

<xs:complexType>

<xs:sequence>

<xs:element name="documentURL" type="xs:anyURI"

minOccurs="1" maxOccurs="1"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</w:types>

<w:message name="PrintIn">

<w:part name="parameters" element="tns:Print" />

</w:message>

<w:portType name="MyWSPrinterServicePortType">

<w:operation name="Print">

<w:input message="tns:PrintIn" />

</w:operation>

</w:portType>

<w:binding name="MyWSPrinterServiceSoap"

type="tns:MyWSPrinterServicePortType">

...

</w:binding>

<w:service name="MyWSPrinterService">

<w:port name="MyWSPrinterServicePort" binding="tns:MyWSPrinterSoap">

<soapw:address location="http://example.org/services"/>

</w:port>

</w:service>

</w:definitions>

2.8.2 The Printer’s Resource Properties Document

A target namespace for the schema in the resource properties document of our example Printer resource is http://example.org/MyWSPrintersResourceProperties.xsd. The schema for the resource properties document includes both MUWS and MOWS manageability capabilities. However, the MOWS Identification capability does NOT need to be supported. This is because all MOWS management capabilities are provided at the same endpoint as the managed Web service, thus there is no need to provide identification for the endpoint of the Web service. However, the resource should support the MUWS Description capability.

In addition, a PrinterManageabilityCapability is defined that provides access to the resource property TonerLevel. Moreover, manageability consumers are likely to have interest in the current state of the printer. Therefore, the PrinterManageabilityCapability should also include a resource property, PrinterState that exposes the current state of the printer. PrinterState is defined as either Off-Line or On-Line. If the PrinterState is On-Line, then it is either Printing or Idle. PrinterState is an extension of the MUWS Part 2 State capability and is described in our example by the URI http://example.com/capabilities/MyWSPrintersResource/PrinterState. See section 5.2 of the MUWS primer for information on extending the State capability and defining a domain specific State taxonomy. Although recommended in Part 2 of the MUWS specification, a resource property representing state transitions is not considered to be useful to manageability consumers in this case.Therefore, a resource property representing state transistions is omitted here. Also, our example omits MUWS Part 2 Relationship capabilities. For additional information on the Relationships capability, see section 2.13 of the MUWS Primer.

For the sake of simplicity and readability, namespace declarations and import statements in our example schema are omitted where standard namespace prefixes are used. Our example schema appears as follows:

<xs:schema

targetNamespace="http://example.org/MyWSPrintersResourceProperties.xsd"

...

elementFormDefault="qualified" attributeFormDefault="unqualified">

<xs:simpleType name="TonerLevelType">

<xs:restriction base="xs:string">

<xs:enumeration value="Very low"/>

<xs:enumeration value="Low"/>

<xs:enumeration value="Adequate for normal operating conditions"/>

<xs:enumeration value="Full"/>

</xs:restriction>

</xs:simpleType>

<xs:element name="TonerLevel" type="printer-xs:ToneLevelType"/>

<xs:complexType name="PrinterStateType">

<xs:complexContent>

<xs:extension base="muws-p2-xs:StateType"/>

</xs:complexContent>

</xs:complexType>

<xs:element name="Off-Line">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType" />

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="On-Line">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType" />

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="Printing">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType">

<xs:sequence>

<xs:element ref="printer-xs:On-line" />

</xs:sequence>

</xs:restriction>

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="Idle">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType">

<xs:sequence>

<xs:element ref="printer-xs:On-line" />

</xs:sequence>

</xs:restriction>

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="PrinterState" type="printer-xs:PrinterStateType"/>

<xs:element name="MyWSPrintersResourceProperties">

<xs:complexType>

<xs:sequence>

<xs:element ref="muws-p1-xs:ResourceId"/>

<xs:element ref="muws-p2-xs:Caption" maxOccurs="unbounded"/>

<xs:element ref="muws-p2-xs:Description" maxOccurs="unbounded"/>

<xs:element ref="muws-p2-xs:Version" minOccurs="0"/>

<xs:element ref="muws-p2-xs:OperationalStatus"/>

<xs:element ref="mows-xs:CurrentOperationalState"/>

<xs:element ref="mows-xs:LastOperationalStateTransition"

minOccurs="0"/>

<xs:element ref="muws-p2-xs:CurrentTime"/>

<xs:element ref="mows-xs:NumberOfRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfFailedRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfSuccessfulRequests" minOccurs="0"/>

<xs:element ref="mows-xs:ServiceTime" minOccurs="0"/>

<xs:element ref="mows-xs:MaxResponseTime" minOccurs="0"/>

<xs:element ref="mows-xs:LastResponseTime" minOccurs="0"/>

<xs:element ref="muws-p1-xs:ManageabilityCapability"

maxOccurs="unbounded"/>

<xs:element ref="wsnt:Topic"

minOccurs="0" maxOccurs="unbounded"/>

<xs:element ref="printer-xs:TonerLevel"/>

<xs:element ref="printer-xs:PrinterState"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

The support of additional ManageabilityCapabilities, such as MOWS RequestProcessingState, and specific Topics are left to the discretion of the designer.

Our example resource properties document containing information relevant to the PrinterManageabilityCapability appears as follows:

<printer-xs:MyWSPrinterServiceProperties . . .>

<printer-xs:TonerLevel>Low</printer-xs:TonerLevel>

<printer-xs:PrinterState>

<printer-xs:Printing>

<printer-xs:On-Line/>

</printer-xs:Printing>

</printer-xs:PrinterState>

...

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State
</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://example.com/capabilities/MyWSPrintersResource/PrinterState
</muws-p1-xs:ManageabilityCapability>

</printer-xs:MyWSPrinterServiceProperties>

Notice that the ManageabilityCharacteristics list provides the URI of the PrinterState capability we defined above. Because this capability is an extension of the MUWS Part 2 State capability, ManageabilityCharacteristics must also expose the MUWS Part 2 State capability as described in section 2.8 of the MUWS Primer.

2.8.3 Printer WSDL Modifications

The WSDL for our example MyWSPrinterService now needs to support the resource properties document and GetResourceProperty within the same portType as the Print operation. The printer’s interface does not need to support GetManageabilityReferences for the same reason that the WS-Resource does not need to support the MOWS Identification capability. We need not support these capabilities since the manageability and manageable endpoints are one and the same.

<w:definitions

targetNamespace="http://example.org/services/MyWSPrinterService.wsdl"

...>

<w:types>

<xs:schema>

...

<xs:element name="Print">

<xs:complexType>

<xs:sequence>

<xs:element name="documentURL" type="xs:anyURI"

minOccurs="1" maxOccurs="1"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

</w:types>

<w:message name="PrintIn">

<w:part name="parameters" element="printer-w:Print" />

</w:message>

<w:portType name="MyWSPrinterServicePortType"

wsrf-rp:ResourceProperties="printer-xs:MyWSPrintersResourceProperties">

<w:operation name="Print">

<w:input message="printer-w:PrintIn" />

</w:operation>

<w:operation name="GetResourceProperty">

<w:input name="GetResourcePropertyRequest"

message="wsrf-rpw:GetResourcePropertyRequest"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourcePropertyDocument/GetResourcePropertyRequest"/>

<w:output name="GetResourcePropertyResponse"

message="wsrf-rpw:GetResourcePropertyResponse"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourcePropertyDocument/GetResourcePropertyResponse"/>

FAULTS

</w:portType>

<w:binding> ... </binding>

<w:service name="MyWSPrinterService">

<w:port name="MyWSPrinterServicePort"

binding="...">

<soapw:address

location="http://example.org/services/MyWSPrinterServiceEndpoint"/>

</w:port>

</w:service>

</w:definitions>

3 Consuming Manageability for Web service Resources

In this section we address issues of the consumer of the services provided by the manageability endpoint of a Web service.

3.1 Obtaining Manageability Endpoints for a Web Service

The endpoint of a managed Web service may not be the same endpoint that supports that endpoint’s manageability, as illustrated in our weather station Web service example in sections 2.1 through 2.7 of this primer. On the other hand, the endpoint of a managed Web service may itself be a manageability endpoint, as illustrated in our printer Web service example in section 2.8 of this primer. This section will address how a manageability consumer can discover the manageability endpoint for a Web service under these different architectures. For general information on obtaining the EPR to a manageability endpoint of a manageable resource, see section 4.1 of the MUWS primer.

The standard means of finding the reference to a Web service endpoint is through a registry of Web services, e.g., a UDDI registry or other type of service registry. Depending on how a registry is constructed, a request to the registry may return a URL or an EPR. Determining whether the referenced endpoint is manageability endpoint, or to get to that endpoint’s manageability endpoint (if one exists), may employ several strategies.

For example, if the WSDL document describing the endpoint can be retrieved, the manageability consumer may determine if the endpoint either

· supports a resource properties document on its portType, or

· specifies the GetManageabilityReferences operation

Or the consumer can first just try sending a GetManageabilityReferences request to the endpoint.

If the Web service provides the GetManageabilityReferences operation, then the endpoint is (at least) a managed Web service endpoint and the management interface for the Web service can be determined from the response. If a fault is returned, the manageability consumer could next send a GetResourceProperty request asking from the muws1:ResourceID to the Web service. A successful reponse means that the Web service is a manageability endpoint that manages another Web service or a manageability endpoint that shares the same endpoint address as the managed Web service.

To determine what type of endpoint is being addressed, the management consumer can request the endpoint’s EndpointReference property (of the MOWS Identification capability) and check that that EndpointReference is the same as the endpoint for the Web service. If the endpoint supports manageability but does not support the MOWS Identification capability, then it is highly likely that the managed and manageability endpoints are the same.

If the portType supports a resource properties document, then the URL or EPR retrieved from the registry points to a WS-Resource. However, this WS-Resource may not comply with MUWS as a manageability endpoint. To determine whether an endpoint is a manageability endpoint, a manageability consumer can:

· verify from the <types> element of the WSDL document that the ResourceId element is supported in the first level children of the resource properties document, or

· request the muws1:ResourceId property as described above

If inspection of the WSDL document is not possible and requests for the MUWS ResourceId fail, either the Web service does not have a manageability interface or some other means of locating the manageability endpoint will need to be used. An alternative might be to access other registries in the environment or other discovery mechanisms as described in section 4.1 of the MUWS primer.

3.2 Determining the Health of a Web Service

A typical pursuit of a manageability consumer is monitoring the 'health' of a Web service. Information about the health of a Web service is provided by the MOWS Operational Status and State properties.

A manageability consumer may periodically request the status or state of a Web service using a GetResourceProperties or GetMultipleResourceProperties message exchange with the manageability endpoint of a Web service. However, a more likely scenario is a manageability consumer requesting a subscription to the events related to operational status and state of a Web service. For additional information on subscribing to events, see section 2.4.1 in the MUWS primer. When a manageability consumer receives notification of a status change, it can then request the current state of the Web service. Thus a manageability consumer may refine its understanding of the health of a Web service while eliminating uneccessary message exchanges. For example, upon receiving a notification that a Web service is Available, a manageability consumer may inquire as to the service’s current state, as follows:

<wsrf-rp:GetResourceProperty>

mows-xs:CurrentOperationalState

</wsrf-rp:GetResourceProperty>

A response to the above request appears as follows:

<wsrf-rp:GetResourcePropertyResponse>

<mows-xs:CurrentOperationalState>

<mows-xs:IdleState>

<mows-xs:Upstate/>

</mows-xs:IdleState

</mows-xs:CurrentOperationalState>

</wsrf-rp:GetResourcePropertyResponse>

The Web service is available (Up) but currently is Idle. A manageability consumer may then decide to schedule another request in ten minutes, for example, to determine whether the Web service is still Idle or has transitioned to the BusyState.

A manageability consumer may need to respond to a more serious situation if a resource reports a status change from Available to Unavailable. Upon receiving such a notification a manageability consumer may again request the CurrentOperationalState and receive a response as follows:

<wsrf-rp:GetResourcePropertyResponse>

<mows-xs:CurrentOperationalState>

<mows-xs:SaturatedState>

<mows-xs:DownState/>

</mows-xs:SaturatedState

</mows-xs:CurrentOperationalState>

The response above provides a manageability consumer with a deeper understanding of why a Web service is unavailable. In particular, the current state or a Web service is Saturated and its resources are no longer available for the handling of functional requests. A Web service may be Unavailable due to an administrator stopping the Web service or due to a system crash or internal processing error. This state information can be retrieved by the manageability consumer for display on a management console or for further manipulation as suits the monitoring and health application.

For example, a manageability consumer displays state transition information as a further aid to a console operator in addressing the problem as follows:

<wsrf-rp:GetResourceProperty>

mows-xs:LastOperationalStateTransition

</wsrf-rp:GetResourceProperty>

As an example, a response to the above request identifying the previous state of the Web service before transitioning to the Unavailable state appears as follows:

<wsrf-rp:GetResourcePropertyResponse>

<mows-xs:LastOperationalStateTransition>

<muws-p2-xs:StateTransition Time="2005-16-11T12:30:35Z">

<muws-p2-xs:EnteredState>

<mows-xs:StoppedState>

<mows-xs:DownState/>

</mows-xs:StoppedState>

</muws-p2-xs:EnteredState>

<muws-p2-xs:PreviousState>

<mows-xs:IdleState>

<mows-xs:UpState/>

</mows-xs:IdleState>

</muws-p2-xs:PreviousState>

</muws-p2-xs:StateTransition>

</mows-xs:LastOperationalStateTransition>

In our example response above, the Web service was administratively stopped and transitioned into the stopped state from a previous state of idle.

3.3 Retrieving Metrics

For a manageability consumer to make use of the MOWS Metrics capability, the manageability endpoint of a Web service should implement the GetMultipleResourceProperties operation as described in section 2.4.1 of the MUWS primer. This operation allows a management application to retrieve related metric properties in a single request. By retrieving the values of related metrics in a single request, a manageability consumer is likely to see more consistent results than by retrieving each metric value in a separate GetResourceProperty message exchange. For example, the MOWS metric properties NumberOfRequests, NumberOfFailedRequests, and NumberOfSuccessfulRequests are best compared and analyzed when these metric values are derived for a similar collection interval. An example of a SOAP message a manageability consumer sends to the manageability endpoint of a Web service to retrieve current values for these three metric properties appears as follows:

<wsrf-rp:GetMultipleResourceProperties>

<wsrf-rp:ResourceProperty>

muws2-xs:CurrentTime

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

mows-xs:NumberOfRequests

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

mows-xs: NumberOfFailedRequests

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

mows-xs: NumberOfSuccessfulRequests

</wsrf-rp:ResourceProperty>

</wsrf-rp:GetMultipleResourceProperties>

The WSDM specification recommends that each request for metric properties also include a request for the MUWS Part 2 CurrentTime property.

An example of a typical response to our request appears as follows:

<wsrf-rp:GetMultipleResourcePropertiesResponse>

<wsrf-rp:ResourceProperty>

<muws2-xs:CurrentTime>2005-06-14T14:25:21.6589722-04:00</CurrentTime>

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

<mows-xs:NumberOfRequests ResetAt="2005-06-14T14:24:58.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">1556</NumberOfRequests>

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

<mows-xs:NumberOfFailedRequests ResetAt="2005-06-14T14:24:58.2181944-04:00" LastUpdated="2005-06-14T14:24:58.1881806-04:00">7</NumberOfFailedRequests>

</wsrf-rp:ResourceProperty>

<wsrf-rp:ResourceProperty>

<mows-xs:NumberOfSuccessfulRequests ResetAt="2005-06-14T14:24:58.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">1549</NumberOfSuccessfulRequests>

</wsrf-rp:ResourceProperty>

</wsrf-rp:GetMultipleResourcePropertiesResponse>

Our example response above was derived from the Resource Properties Document in section 2.6 of the MUWS primer.

A manageability consumer may use this information to display a graphic like a bar or pie chart, of the requests processed by a Web service and indicate the number of successful and failed requests within the time interval as designated by the @ResetAt and @LastUpdated attributes. The MOWS metric properties of ServiceTime, MaxResponseTime, and LastResponseTime may be used by a manageability consumer in a similar fashion.

A manageability consumer may request to be notified if the value of a metric exceeds a threshold. For example, a manageability consumer may wish to be notified when the value of the NumberOfFailedResponses property exceeds ten within any collection interval. To subscribe for such a notification, a manageability consumer sends a request to the manageability endpoint as follows:

<wsnt:Subscribe>

...

<wsnt:TopicExpression Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

mows-ev:NumberOfFailedRequests

</wsnt:TopicExpression>

<wsnt:Selector

Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">

boolean(mows-xs:NumberOfFailedRequests > "10")

</wsnt:Selector>

</wsnt:Subscribe>

In the request above, the <wsnt:Selectort> element specifies the XPath expression [XPath] upon which the content of a notification is evaluated by the Notification Producer before it is sent to a subscriber. In the request above, the expression, mows-xs:NumberOfFailedRequests > 10, must be true for a notification to be sent to this subscriber.

Notice that the first notification is generated for this subscription when the value of the NumberOfFailedRequests metric is 11. However, further notifications are generated for this subscription when this value becomes 12, and then 13, and so on.

3.4 Consuming Notifications

Notifications provide a critical tool for a manageability consumer. Different topics as specified by MOWS and MUWS are relevant to different types of management application as follow:

Management Application	MUWS / MOWS Topic	Relevance
Distribution Applications	Status	Confirm successful installation (e.g., Status='Available')
Topology Applications	Status / State Relationships	Supplement console display with current status / state Display network topology on this console. Note: this topology may be dynamic as resources and relationships are created on the network.
Configuration Applications	Identification / Configuration	Reveal configuration of managed services
Event and Automation Applications	Status / State/ RequestProcessing	Notifications are triggers for automation
Monitoring and Performance Applications	Status / State / Metrics	Monitoring status and state of a resource in real time.

For a manageability consumer to consume notifications, it must implement an event Listener. Many modern programming languages such as Java and C# provide mechanisms for supporting events and subscriptions.

3.5 Obtaining Request Processing State Information

As described in section 2.7 of the MUWS primer, a manageability consumer can subscribe to notifications related to changes of state of each request processed by a managed Web service. The manageability consumer may subscribe to receive notification messages related to:

each of the state changes during the processing of a request

a subset of the state changes during the processing of a request

a digest (history) of the state changes for the processing of a request

The type of notification a manageability consumer wishes to receive depends upon the functional requirements and design of the consumer.

In addition to a manageability consumer subscribing to a specific topic offered by a managed resource, a manageability consumer may also specify additional filters on a subscription to further refine the content of notifications it wishes to receive. There are three types of selection criteria to filter a generated notification. These selection criteria are: TopicExpression, Precondition and Selector. The TopicExpression filter as used in this primer appears as follows:

<wsnt:Subscribe>

...

<wsnt:TopicExpression

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatus

</wsnt:TopicExpression>

</wsnt:Subscribe>

Notice that this example uses the Simple Topic Expression dialect to subscribe to events related to the MUWS Operational Status, an event associated with the MOWS OperationalStatusCapability topic. For additional information, see section 2.6 of the MUWS primer.

A manageability consumer may also qualify a subscription in order to receive notifications only from producers exposing a specific property. An example of such a filter appears as follows:

<wsnt:Subscribe>

...

<wsnt:TopicExpression

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatus

</wsnt:TopicExpression>

<wsnt:Precondition

Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">

boolean(mows-xs:NumberOfFailedRequests>"10")

</wsnt:Precondition>

</wsnt:Subscribe>

For our example subscription above, a notification of an event on the OperationalStatus property is sent to a manageability consumer only if the current number of failed requests on a managed Web service is greater than ten. Notice that unlike the TopicExpression filter, the ProducerProperties filter uses XPath 1.1 to formulate selection criteria.

Finally, a manageability consumer may also qualify subscriptions in order to receive a notification only if specific content exists in a notification message. An example appears as follows:

<wsnt:Subscribe>

...

<wsnt:TopicExpression

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatus

</wsnt:TopicExpression>

<wsnt:Selector

Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">

//muws1:ManagementEvent[muws2:Situation/muws2:Message/wsrf-rp:ResourcePropertyValueChangeNotificaiton/wsrf-rp:NewValue/muws2:OperationalStatus='Unavailable']

</wsnt:Selector>

</wsnt:Subscribe>

For our example subscription above, a notification of an event on the OperationalStatus property is sent to a manageability consumer only if the value of the OperationalStatus property has changed to Unavailable. This information is buried 'deep' within the MUWS ManagementEvent structure.

Also, notice that both the Precondition filter and the Selector filter may be specified for a subscription. In this case a notification is sent to a manageability consumer only if the conjunction of the respective selection criteria is satisfied. Alternatively, if the TopicExpression element is omitted, a notification message on any topic is sent to a manageability consumer that meets the selection criteria expressed by the ProducerProperties filter and/or the MessageContent filter.

Finally, if a manageability consumer desires complete information about a processed request and if a manageability endpoint supports such a subscription, then it is possible for a manageability consumer to subscribe to these topics using a specification of attachments, mows-ev:RequestProcessingObservationsWithAttachments. When attachments are specified, a notification producer should attempt to attach any input document, etc. to a generated notification.

4 References

[MOWS] Igor Sedukhin, Web Services Distributed Management:Management of Web Services (WSDM-MOWS) 1.0, OASIS Committee Draft, December 2004, http://docs.oasis-open.org/wsdm/2004/12/cd-wsdm-mows-1.0.pdf

[MUWS] William Vambenepe, Web Services Distributed Management:Management using Web Services (MUWS 1.0) Part 1, OASIS Committee Draft, December 2004, http://docs.oasis-open.org/wsdm/2004/12/wsdm-muws-part1-1.0.pdf

William Vambenepe, Web Services Distributed Management:Management using Web Services (MUWS 1.0) Part 2, OASIS Committee Draft, December 2004, http://docs.oasis-open.org/wsdm/2004/12/wsdm-muws-part2-1.0.pdf

[SOAP] Don Box, et al., Simple Object Access Protocol (SOAP) 1.1, W3C Note, May 2000, http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

[WS-Addressing] Don Box, et al., Web services Addressing (WS-Addressing), W3CMember Submission, August 2004, http://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/

[WS-BaseFaults] Steve Tuecke, et. al., Web Services Base Faults 1.2 (WS-BaseFaults), Oasis Working Draft, November, 2004, http://docs.oasis-open.org/wsrf/2004/11/wsrf-WS-BaseFaults-1.2-draft-03.pdf

[WS-ResourceProperties] Steve Graham, et al., Web Services Resource Properties 1.2 (WS-ResourceProperties), OASIS Working Draft, June 2004, http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-04.pdf

[WSDL] Erik Christensen, et al., Web services Description Language (WSDL) 1.1, W3C Note, March 2001, http://www.w3.org/TR/wsdl

[WSLC] Hao He, et al., Web Service Management: Service Lifecycle, W3C Note, February 2004, http://www.w3.org/TR/2004/NOTE-wslc-20040211/

[XML] Tim Bray, et al., Extensible Markup Language (XML) 1.0 (Third Edition), W3C Recommendation, February 2004, http://www.w3.org/TR/REC-xml

[XML Schema] Henry S. Thompson, et al. XML Schema Part 1: Structures, W3C Recommendation, May 2001, http://www.w3.org/TR/xmlschema-1/

Paul V. Biron, et al. XML Schema Part 2: Datatypes, W3C Recommendation, May 2001, http://www.w3.org/TR/xmlschema-2/

[XPath] James Clark, et al., XML Path Language (XPath) Version 1.0, W3C Recommendation, November 1999, http://www.w3.org/TR/1999/REC-xpath-19991116

Appendix A. Complete XML Documents

XML Schema for the separate WeatherManagementService manageability endpoint.

<?xml version="1.0" encoding="utf-8"?>

<xs:schema

targetNamespace="http://example.org/services/WeatherManagementService.xsd"

xmlns:wsws-mgr-xs="http://example.org/services/WeatherManagementService.xsd"

xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"

xmlns:mows-xs="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"

xmlns:wsnt="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified" attributeFormDefault="unqualified">

<xs:import

namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"/>

<xs:import

namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"/>

<xs:import

namespace="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"/>

<xs:import

namespace="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd">

schemaLocation="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd "/>

<xs:element name="WeatherManagermentServiceProperties">

<xs:complexType>

<xs:sequence>

<xs:element ref="muws-p1-xs:ResourceId"/>

<xs:element ref="mows-xs:EndpointReference"/>

<xs:element ref="mows-xs:EndpointDescriptions"/>

<xs:element ref="muws-p2-xs:Caption" maxOccurs="unbounded"/>

<xs:element ref="muws-p2-xs:Description" maxOccurs="unbounded"/>

<xs:element ref="muws-p2-xs:Version"/>

<xs:element ref="muws-p2-xs:OperationalStatus"/>

<xs:element ref="mows-xs:CurrentOperationalState"/>

<xs:element ref="mows-xs:LastOperationalStateTransition"

minOccurs="0"/>

<xs:element ref="muws-p2-xs:CurrentTime"/>

<xs:element ref="mows-xs:NumberOfRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfFailedRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfSuccessfulRequests" minOccurs="0"/>

<xs:element ref="mows-xs:ServiceTime" minOccurs="0"/>

<xs:element ref="mows-xs:MaxResponseTime" minOccurs="0"/>

<xs:element ref="mows-xs:LastResponseTime" minOccurs="0"/>

<xs:element ref="muws-p1-xs:ManageabilityCapability"

maxOccurs="unbounded"/>

<xs:element ref="wsnt:Topic" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

An example of a resource properties document conforming to this schema might appear as:

<?xml version="1.0" encoding="utf-8"?>

<wsws-mgr-xs:WeatherManagementServiceProperties

xmlns:wsws-mgr-xs="http://example.org/services/WeatherManagementService.xsd"

xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"

xmlns:mows-xs="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"

xmlns:wsnt="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"

xmlns:muws-ev="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2-events.xml"

xmlns:mows-ev="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows-events.xml"

xmlns:wsa="http://schemas.xmlsoap.org/ws/2005/08/addressing">

<muws-p1-xs:ResourceId>

urn:uuid:E3A0B27A-45E0-40af-A15B-1CDC263F24CE

</muws-p1-xs:ResourceId>

<mows-xs:EndpointReference>

<wsa:Address>http://example.org/services/WeatherStation</wsa:Address>

</mows-xs:EndpointReference>

<mows-xs:EndpointDescriptions>

<mows-xs:description>

http://example.org/service?WSDL

</mows-xs:description>

</mows-xs:EndpointDescriptions>

<muws-p2-xs:Description xml:lang="en-US">

Manageability endpoint for Weather Station Web Service.

</muws-p2-xs:Description>

<muws-p2-xs:Version>

Version 1.4.2, January 2005

</muws-p2-xs:Version>

<muws-p2-xs:OperationalStatus>

Available

</muws-p2-xs:OperationalStatus>

<mows-xs:CurrentOperationalState>

<mows-xs:BusyState>

<mows-xs:UpState/>

</mows-xs:BusyState>

</mows-xs:CurrentOperationalState>

<mows-xs:LastOperationalStateTransition>

<muws-p2-xs:StateTransition Time="2005-06-11T10:02:35Z">

<muws-p2-xs:EnteredState>

<mows-xs:Upstate/>

</muws-p2-xs:EnteredState>

<muws-p2-xs:PreviousState>

<mows-xs:SaturatedState>

<mows-xs:DownState/>

</mows-xs:SaturatedState>

</muws-p2-xs:PreviousState>

</muws-p2-xs:StateTransition>

</mows-xs:LastOperationalStateTransition>

<muws-p2-xs:CurrentTime>2005-06-14T14:25:21.6589722-04:00</muws-p2-xs:CurrentTime>

<mows-xs:NumberOfRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">1556</mows-xs:NumberOfRequests>

<mows-xs:NumberOfSuccessfulRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.2582128-04:00">1549</mows-xs:NumberOfSuccessfulRequests>

<mows-xs:NumberOfFailedRequests ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-14T14:24:58.1881806-04:00">7</mows-xs:NumberOfFailedRequests>

<mows-xs:ServiceTime ResetAt="2005-06-13T14:24:20.2582128-04:00" LastUpdated="2005-06-14T14:24:58.2181944-04:00">PT3H28M13.52S</mows-xs:ServiceTime>

<mows-xs:MaxResponseTime ResetAt="2005-06-13T14:24:20.2181944-04:00" LastUpdated="2005-06-13T16:12:36.3763419-04:00">PT12.02S</mows-xs:MaxResponseTime>

<mows-xs:LastResponseTime LastUpdated="2005-06-13T14:24:58.2582128-04:00">PT0.015S</mows-xs:LastResponseTime>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

muws-ev:OperationalStatusCapability

</wsnt:Topic>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple">

mows-ev:RequestProcessingStateCapability

</wsnt:Topic>

<wsnt:Topic

Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Simple">

mows-ev:RequestProcessingObservations

</wsnt:Topic>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Identification

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/OperationalStatus

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/OperationalState

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/RequestProcessingState

</muws-p1-xs:ManageabilityCapability>

</wsws-mgr-xs:WeatherManagementServiceProperties>

WSDL document for the separate WeatherManagementService manageability endpoint.

<?xml version="1.0" encoding="utf-8"?>

<w:definitions

targetNamespace="http://example.org/services/WeatherManagementService.wsdl"

xmlns:wsws-mgr-w="http://example.org/services/WeatherManagementService.wsdl"

xmlns:wsws-mgr-xs="http://example.org/services/WeatherManagementService.xsd"

xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

xmlns:wsrf-rp="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"

xmlns:wsrf-rpw="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl"

xmlns:wsntw="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl"

xmlns:rmd="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd"

xmlns:wsws-mgr-md="http://example.com/services/WeatherManagementService.rmd"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:wsa="http://schemas.xmlsoap.org/ws/2005/08/addressing"

xmlns:soapw="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:w="http://schemas.xmlsoap.org/wsdl/">

<w:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl"

location="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl"/>

<w:import

namespace="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl"

location="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl"/>

<w:import namespace="http://schemas.xmlsoap.org/ws/2005/08/addressing"

location="http://schemas.xmlsoap.org/ws/2005/08/addressing/ws-addr.xsd"/>

<w:types>

<xs:schema>

<xs:import namespace="http://example.org/services/WeatherManagementService.xsd"

schemaLocation="http://example.org/services/WeatherManagementService.xsd"/>

<xs:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"

schemaLocation="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"/>

<xs:import namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"/>

<xs:import namespace="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd"

schemaLocation="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd"/>

<xs:import namespace="http://example.com/services/WeatherManagementService.rmd"

schemaLocation="http://example.com/services/WeatherManagementService.rmd"/>

</xs:schema>

</w:types>

<w:portType name="WeatherManagementServicePortType"

wsrf-rp:ResourceProperties="wsws-mgr-xs:WeatherManagementServiceProperties"

rmd:metadataDescriptor="wsws-mgr-md:WSWSManagementServiceDescriptor"

rmd:metadataDescriptorLocation="http://example.com/services/WeatherManagementService.rmd http://example.com/services/metadata/WeatherManagementService.rmd">

<w:operation name="GetResourceProperty">

<w:input name="GetResourcePropertyRequest"

message="wsrf-rpw:GetResourcePropertyRequest"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyRequest"/>

<w:output name="GetResourcePropertyResponse"

message="wsrf-rpw:GetResourcePropertyResponse"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyResponse"/>

<w:fault name="ResourceUnknownFault"

message="wsrf-rpw:ResourceUnknownFault"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/>

<w:fault name="InvalidResourcePropertyQNameFault"

message="wsrf-rpw:InvalidResourcePropertyQNameFault"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/InvalidResourcePropertyQNameFault"/>

</w:operation>

<w:operation name="Subscribe">

<w:input message="wsntw:SubscribeRequest"

wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeRequest"/>

<w:output message="wsntw:SubscribeResponse"

wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeResponse"/>

<w:fault name="ResourceUnknownFault"

message="wsntw:ResourceUnknownFault" />

<w:fault name="SubscribeCreationFailedFault"

message="wsntw:SubscribeCreationFailedFault"/>

<w:fault name="TopicPathDialectUnknownFault"

message="wsntw:TopicPathDialectUnknownFault"/>

</w:operation>

<w:operation name="GetCurrentMessage">

<w:input message="wsntw:GetCurrentMessageRequest"

wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageRequest"/>

<w:output message="wsntw:GetCurrentMessageResponse"

wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageResponse"/>

<w:fault name="ResourceUnknownFault"

message="wsntw:ResourceUnknownFault" />

<w:fault name="InvalidTopicExpressionFault"

message="wsntw:InvalidTopicExpressionFault" />

<w:fault name="TopicNotSupportedFault"

message="wsntw:TopicNotSupportedFault" />

<w:fault name="NoCurrentMessageOnTopicFault"

message="wsntw:NoCurrentMessageOnTopicFault" />

</w:operation>

</w:portType>

<w:binding name="WeatherManagementServiceBinding"

type="wsws-mgr-w:WeatherManagementServicePortType">

<soapw:binding

transport="http://schemas.xmlsoap.org/soap/http"

style="document"/>

<w:operation name="GetResourceProperty">

<soapw:operation style="document"/>

<w:input>

<soapw:body use="literal"/>

<soapw:header message="pdaw:ToHeader" part="document" use="literal"/>

</w:input>

<w:output>

<soapw:body use="literal"/>

</w:output>

<w:fault>

<soapw:fault name="ResourceUnknownFault" use="literal"/>

</w:fault>

<w:fault>

<soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/>

</w:fault>

</w:operation>

<w:operation name="Subscribe">

<soapw:operation style="document"/>

<w:input>

<soapw:body use="literal"/>

<soapw:header message="pdaw:ToHeader" part="document" use="literal"/>

</w:input>

<w:output>

<soapw:body use="literal"/>

</w:output>

<w:fault>

<soapw:fault name="ResourceUnknownFault" use="literal"/>

</w:fault>

<w:fault>

<soapw:fault name="InvalidStatusFault" use="literal"/>

</w:fault>

<w:fault>

<soapw:fault name="SubscribeCreationFailedFault"/>

</w:fault>

<w:fault>

<soapw:fault name="TopicPathDialectUnknownFault"/>

</w:fault>

</w:operation>

<w:operation name="GetCurrentMessage">

<soapw:operation style="document"/>

<w:input>

<soapw:body use="literal"/>

<soapw:header message="pdaw:ToHeader" part="document" use="literal"/>

</w:input>

<w:output>

<soapw:body use="literal"/>

</w:output>

<w:fault>

<soapw:fault name="ResourceUnknownFault" use="literal"/>

</w:fault>

<w:fault>

<soapw:fault name="InvalidTopicExpressionFault"/>

</w:fault>

<w:fault>

<soapw:fault name="TopicNotSupportedFault"/>

</w:fault>

<w:fault>

<soapw:fault name="NoCurrentMessageOnTopicFault"/>

</w:fault>

</w:operation>

</w:binding>

<w:service name="WeatherManagementService">

<w:port name="WeatherManagementServicePort">

binding="WeatherManagementServiceBinding">

<soapw:address

location="http://example.org/services/WeatherManagementServiceEndpoint"/>

</w:port>

</w:service>

</w:definitions>

The metadata document for the Weather Service manageability endpoint is:

<?xml version="1.0" encoding="utf-8"?>

<rmd:Definitions

xmlns:rmd="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd"

xmlns:wsws-mgr-w="http://example.org/services/WeatherManagementService.wsdl"

xmlns:wsws-mgr-xs="http://example.org/services/WeatherManagementService.xsd"

xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"

xmlns:mows-xs="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"

targetNamespace="http://example.com/services/WeatherManagementService.rmd">

<rmd:MetadataDescriptor

name="WSWSManagementServiceDescriptor"

interface="wsws-mgr-w:WSWSManagementServicePortType"

wsdlLocation="http://example.com/services/WeatherManagementService.wsdl

http://example.com/wsdl/WSWSIdentification.wsdl">

<rmd:Property path="muws-p1-xs:ResourceId"

mutability="constant"

modifiability="read-only'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="muws-p1-xs:Description"

mutability="mutable"

modifiability="read-write'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="muws-p1-xs:Caption"

mutability="mutable"

modifiability="read-write'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="muws-p1-xs:Version"

mutability="mutable"

modifiability="read-write'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description

</muws-p2-xs:Capability>

<rmd:StaticValues>

<muws-p1-xs:Version>Version 1.4.2, January 2005</muws-p1-xs:Version>

</rmd:StaticValues>

</rmd:Property>

<rmd:Property path="muws-p1-xs:ManageabilityCapability"

mutability="constant"

modifiability="read-only'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics

</muws-p2-xs:Capability>

<rmd:StaticValues>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://example.org/capabilities/TranslateableDescription

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://example.org/capabilities/ServerConnectionMetrics

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://example.org/capabilities/DeviceState

</muws-p1-xs:ManageabilityCapability>

<muws-p1-xs:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Relationships

</muws-p1-xs:ManageabilityCapability>

</rmd:StaticValues>

</rmd:Property>

<rmd:Property path="muws-p2-xs:CurrentTime"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:NumberOfRequests"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:NumberOfFailedRequests"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:NumberOfSuccessfulRequests"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:ServiceTime"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:MaxResponseTime"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="mows-xs:LastResponseTime"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType>

<muws-p2-xs:TimeScope>PointInTime</muws-p2-xs:TimeScope>

<muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics

</muws-p2-xs:Capability>

</rmd:Property>

<rmd:Property path="muws-p2-xs:OperationalStatus"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus

</muws-p2-xs:Capability>

<rmd:ValidValues>

<muws-p2-xs:OperationalStatus>Available</muws-p2-xs:OperationalStatus>

<muws-p2-xs:OperationalStatus>PartiallyAvailable</muws-p2-xs:OperationalStatus>

<muws-p2-xs:OperationalStatus>Unavailable</muws-p2-xs:OperationalStatus>

<muws-p2-xs:OperationalStatus>Unknown</muws-p2-xs:OperationalStatus>

</rmd:ValidValues>

</rmd:Property>

<rmd:Property path="mows-xs:CurrentOperationalState"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/State

</muws-p2-xs:Capability>

<muws-p2-xs:Capability>

http://example.org/capabilities/OperationalState

</muws-p2-xs:Capability>

<rmd:ValidValues>

<mows-xs:CurrentOperationalState>

<mows-xs:IdleState><mows-xs:UpState/></mows-xs:IdleState>

</mows-xs:CurrentOperationalState>

<mows-xs:CurrentOperationalState>

<mows-xs:BusyState><mows-xs:UpState/></mows-xs:BusyState>

</mows-xs:CurrentOperationalState>

<mows-xs:CurrentOperationalState>

<mows-xs:StoppedState><mows-xs:DownState/></mows-xs:StoppedState>

</mows-xs:CurrentOperationalState>

<mows-xs:CurrentOperationalState>

<mows-xs:CrashedState><mows-xs:DownState/></mows-xs:CrashedState>

</mows-xs:CurrentOperationalState>

<mows-xs:CurrentOperationalState>

<mows-xs:SaturatedState><mows-xs:DownState/></mows-xs:SaturatedState>

</mows-xs:CurrentOperationalState>

</rmd:ValidValues>

</rmd:Property>

<rmd:Property path="mows-xs:LastOperationalStateTransition"

mutability="mutable"

modifiability="read-only'>

<muws-p2-xs:Capability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/State

</muws-p2-xs:Capability>

<muws-p2-xs:Capability>

http://example.org/capabilities/OperationalState

</muws-p2-xs:Capability>

</rmd:Property>

</rmd:MetadataDescriptor>

</rmd:Definitions>

The schema for the resource properties document for the printer:

<?xml version="1.0" encoding="utf-8"?>

<xs:schema

targetNamespace="http://example.org/MyWSPrintersResourceProperties.xsd"

xmlns:printer-xs="http://example.org/MyWSPrintersResourceProperties.xsd"

xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"

xmlns:mows-xs="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"

xmlns:wsnt="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified" attributeFormDefault="unqualified">

<xs:import

namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"/>

<xs:import

namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"/>

<xs:import

namespace="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"/>

<xs:import

namespace="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"/>

schemaLocation="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"/>

<xs:simpleType name="TonerLevelType">

<xs:restriction base="xs:string">

<xs:enumeration value="Very low"/>

<xs:enumeration value="Low"/>

<xs:enumeration value="Adequate for normal operating conditions"/>

<xs:enumeration value="Full"/>

</xs:restriction>

</xs:simpleType>

<xs:element name="TonerLevel" type="printer-xs:ToneLevelType">

<xs:complexType name="PrinterStateType">

<xs:complexContent>

<xs:extension base="muws-p2-xs:StateType"/>

</xs:complexContent>

</xs:complexType>

<xs:element name="Off-Line">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType" />

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="On-Line">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType" />

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="Printing">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType">

<xs:sequence>

<xs:element ref="printer-xs:On-line" />

</xs:sequence>

</xs:restriction>

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="Idle">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="printer-xs:PrinterStateType">

<xs:sequence>

<xs:element ref="printer-xs:On-line" />

</xs:sequence>

</xs:restriction>

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element name="PrinterState" type="printer-xs:PrinterStateType"/>

<xs:element name="MyWSPrintersResourceProperties">

<xs:complexType>

<xs:sequence>

<xs:element ref="muws-p1-xs:ResourceId"/>

<xs:element ref="muws-p2-xs:Caption" maxOccurs="unbounded"/>

<xs:element ref="muws-p2-xs:Description" maxOccurs="unbounded"/>

<xs:element ref="muws-p2-xs:Version"/>

<xs:element ref="muws-p2-xs:OperationalStatus"/>

<xs:element ref="mows-xs:CurrentOperationalState"/>

<xs:element ref="mows-xs:LastOperationalStateTransition"

minOccurs="0"/>

<xs:element ref="muws-p2-xs:CurrentTime"/>

<xs:element ref="mows-xs:NumberOfRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfFailedRequests" minOccurs="0"/>

<xs:element ref="mows-xs:NumberOfSuccessfulRequests" minOccurs="0"/>

<xs:element ref="mows-xs:ServiceTime" minOccurs="0"/>

<xs:element ref="mows-xs:MaxResponseTime" minOccurs="0"/>

<xs:element ref="mows-xs:LastResponseTime" minOccurs="0"/>

<xs:element ref="muws-p1-xs:ManageabilityCapability"

minOccurs="0" maxOccurs="unbounded"/>

<xs:element ref="wsnt:Topic"

minOccurs="0" maxOccurs="unbounded"/>

<xs:element ref="printer-xs:TonerLevel"/>

<xs:element ref="printer-xs:PrinterState"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

Appendix B. Acknowledgments

The following people made contributions to the WSDM MUWS Primer Version 1.0: Vaughn Bullard, Fred Carter, David Cox, Zulah Eckert, Mark Ellison, Heather Kreger, Frederico Maciel, Bryan Murray, Kirk Wilson with special thanks to Kirk Wilson, Bryan Murray and Mark Ellison as editors.

The following individuals were members of the committee while the WSDM MUWS Version 1.1 specification was developed and approved by the technical committee: Guru Bhat, Jeff Bohren, Vaughn Bullard, Winston Bumpus, Fred Carter, Michael Clements, David Cox, Zulah Eckert, Mark Ellison, John Fuller, Tony Gullotta, Heather Kreger, Richard Landau, Frederico Maciel, Tom Maguire, David Melgar, Bryan Murray, Richard Nikula, Mark Peel, Mitsunori Satomi, Thomas Studwell, William Vambenepe, Zhili Zhang.

Appendix C. Revision History

Rev	Date	By Whom	What
CD	2006-02-24	Kirk Wilson	Title chnages
final_wd	2006-01-27	Kirk Wilson	Prepare WD for TC vote
wd-mows-7	2006-01-27	Kirk Wilson	Add References in text; completed Reference section Add Acknowledge section
wd-mows-6	2005-12-16	Kirk Wilson	Edit XML in Appendix A
wd-mows-5	2005-11-16	Kirk Wilson	Continuation of version 4 with Simplication of example code
wd-mows-4	2005-11-16	Kirk Wilson	Editorial corrections as result of F2F including: Change of example name Simplication of example code Simplication of text (remove verbose text) Rewrite sections 1 and 3.1
wd-mows-3	2005-10-26	Kirk Wilson	Table of contents to show 5 levels
wd-mows-2	2005-10-20	Kirk Wilson, Mark Ellison	Added material for Appendix A; standardized ns prefixes Applied Mark Ellison’s edits for readability of the text
wd-mows-1	2005-09-29	Kirk Wilson	Separated MOWS chapters from from wd-wsdm-primer. Added Introduction section. Changed references to 'this primer' to 'the MUWS Primer' where appropriate.

Appendix D. Notices

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an 'AS IS' basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.