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

---

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.

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

 

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.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:

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:

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:

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:

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:

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:

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:

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:

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

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

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:

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:

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:

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:

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:

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:

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

The response to the above might appears as follows:

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:

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

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:

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

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:

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:

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:

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:

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: