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

---

Document identifier:

wsdm-primer-muws-cd

Location:

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

Editors:

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

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

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

Abstract:

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

This primer does not provide a definitive specification of the WSDM. Rather, it is intended to provide an easily read and understood summary of the fundamentals for creating and using WSDM-compliant manageability consumers and manageable resources.

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 this 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/wsdm-primer-cd-errata.pdf.

1      Introduction. 5

1.1 Namespaces. 5

2      Building a Manageable Resource. 7

2.1 The Resource. 7

2.2 Exposing Resource Identity. 7

2.2.1 The Resource Properties Document 7

2.2.2 The WSDL Document 9

2.2.3 Example SOAP Messages. 11

2.3 Adding a WSDM Capability. 13

2.3.1 Modifying the Resource Properties Document 14

2.3.2 Examples of Description Capability Messages. 15

2.4 Manageability Characteristics. 16

2.5 Adding Property Access Operations. 17

2.5.1 Modifying the WSDL Document 17

2.5.2 Example of Property Access Operation Messages. 21

2.6 Operational Status. 23

2.7 Metrics. 24

2.7.1 A Scenario for PDA Metrics. 25

2.7.2 Metric Datatypes and Exposing Metrics. 25

2.8 Extending a Capability. 27

2.9 Adding Resource-specific Operations and Properties. 28

2.9.1 Adding Resource-specific Properties. 28

2.9.2 Adding Resource-specific operations. 28

2.10 Notifications. 29

2.10.1 Changes to the Resource Properties Document 30

2.10.2 Changes to the WSDL Document 30

2.10.3 ManagementEvent Format 31

2.10.3.1 Example. 33

2.10.4 Creating a TopicSpace. 34

2.10.4.1 Topics for Resource-Specific Metrics. 34

2.11 Building and Exposing a Metadata Document 35

2.11.1 Constructing PDA Device Metadata. 37

2.11.2 Metric Metadata. 39

2.11.2.1 PDA Resource-specific Metrics. 40

2.11.2.2 Example PDA Resource Properties Document with Metrics. 42

2.12 State. 43

2.12.1 State Model Metadata. 47

2.13 Advertising a Resource. 48

2.14 Operable Collections. 49

3      Building Relationships. 52

3.1 WSDM Relationships and UML Associations. 52

3.1.1 Defining a Relationship Type. 53

3.2 The Relationship Capability. 54

3.2.1 Relationships in the Resource Properties Document 54

3.2.2 Querying Relationships by Type: WSDL Modifications. 55

3.2.2.1 An Example using QueryingRelationshipsByType. 56

3.2.3 Relationship Events. 57

3.2.4 Relationship Metadata. 59

3.2.5 Guidelines for Supporting the Relationships Capability. 59

3.3 Accessing Relationships as WS-Resources. 60

3.3.1 Accessing a MUWS Relationships as a WS-Resource. 60

3.3.2 Treating Relationships as Standalone Resources. 61

4      Managing MUWS Resources. 63

4.1 Discovering Resources. 63

4.1.1 Explicit Configuration. 63

4.1.2 Resource Advertisement and Registries. 63

4.1.2.1 UDDI 64

4.1.2.2 ServiceGroup. 64

4.1.2.3 Relationship Registries. 64

4.1.3 Using The MUWS Relationship Capability. 64

4.1.3.1 Discovering Resources from Relationships. 65

4.1.3.2 Monitoring Relationships. 66

4.1.4 Summary. 66

4.2 Managing and Monitoring. 67

4.2.1 Discovering Manageability Capabilities. 67

4.2.2 Using Manageability Capabilities. 67

4.2.2.1 Determining Resource Identity. 67

4.2.2.2 Obtaining Description and State Information. 69

4.2.2.3 Configuring the Manageable Resource. 70

4.2.2.4 Querying and Traversing Relationships. 70

5      Further Considerations. 72

5.1 Defining a Taxonomy in WSDM.. 72

5.1.1 Steps for Constructing a Taxonomy. 74

5.2 Alternate Means of Accessing Manageability. 74

5.3 FCAPS Discussion. 75

5.4 The Web Services Platform.. 75

5.4.1 Initial Focus. 76

5.4.1.1 Properties. 76

5.4.1.2 Meta Data. 76

5.4.1.3 Addressing. 76

5.4.1.4 Notification. 77

5.4.1.5 Versioning. 77

5.4.1.6 Security. 77

5.4.1.7 Registration, Discovery and Location. 78

5.4.2 Future Focus. 78

5.4.2.1 Policy. 78

5.4.2.2 Name Resolution. 78

5.4.2.3 Transaction. 79

5.4.2.4 Flow.. 79

5.4.2.5 Negotiation. 80

6      References. 81

Appendix A. Complete XML Documents. 83

Appendix B. Acknowledgments. 103

Appendix C. Revision History. 104

Appendix D. Notices. 107

 

After reading this primer, the reader should be prepared to understand and implement the MUWS standard and the specification supporting the MUWS standard, such as WS-ResourceProperties [WS-ResourceProperties] and WS-BaseNotification [WS-BaseNotification]. The primary goal of the WSDM primer is to provide the reader with examples and to explain the use of the WSDM standards to achieve Information Technology (IT) management goals.

This primer addresses the experienced developer or architect wishing to learn how to construct the necessary XML documents related to MUWS, including XML schema [XML Schema], WSDL [WSDL], and SOAP [SOAP] messages supporting the MUWS message exchange patterns (MEPs). A basic familiarity with the MUWS and MOWS specifications is assumed. Explanations of concepts covered in the MUWS and MOWS specifications are generally not repeated in this document.

This document will provide concrete examples of how the necessary XML documents [XML] specified by MUWS are constructed. It helps the reader understand which elements must be included in a particular document in order to achieve a desired goal. While the WSDM specifications provide an abstract description of necessary XML documents, this primer provides concrete illustrations of those XML documents.

The reader should observe that neither the WSDM specifications nor this primer describe the physical, runtime construction of necessary XML documents as rendered within program code. Choosing an appropriate design and toolkit for the system hosting an implementation of the MUWS MEPs is beyond the scope of this primer.

Examples are developed throughout this primer of the following three main types of XML documents as used by MUWS:

§         XML representations of manageable resources described using XML Schema, as well as descriptions of the messages exchanged

§         Descriptions of the Message Exchange Patterns exposed by a manageability endpoint using WSDL

§         Examples of SOAP messages exchanged between a manageability consumer and the manageability endpoint of manageable resource

At this point, before continuing with this primer, the reader is encouraged to review the MUWS specification . Reading the MUWS specification at this point will help to fill-in some detail omitted from the preceding overview. Finally, reading the MUWS specification establishes a proper context for the remainder of this primer.

1.1 Namespaces

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

pda	http://example.org/services/MyPdaDevice.xsd
pdaw	http://example.org/services/MyPdaDevice.wsdl
pdae	http://example.org/MyPdaTopics.xml
pda-rmd	http://example.com/services/MyPdaDevice.rmd
relext	http://example.org/services/GatewayRelationship.xsd
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
exh	http://example.org/services/localDefinitions.xsd
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
wsntw	http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl
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
pbm	http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-pbm.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) 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.

 

This chapter of the primer illustrates how a set of features, including MUWS required properties, is provided for a manageable resource. This chapter also illustrates the message exchanges required to access the provided properties of a manageable resource.

In this chapter, we will add features to a manageability endpoint one step at a time. This step-wise approach is similar to how a developer would naturally implement and maintain the features of a manageability endpoint. Thus, the target namespace will not be changed for every section. By the conclusion of this chapter, will build up a complete implementation of a manageability endpoint. The final WSDL and schema documents as used for an example deployment are located in the Appendix of this primer.

2.1 The Resource

We will use the same endpoint for all of our examples. Thus want to start with a name we can use in each example. We will use a PDA as our resource and use the name MyPdaDevice as the basis for names in our examples.

2.2 Exposing Resource Identity

The Identity capability is the only required feature of a MUWS compliant manageability endpoint [MUWS Part 1]. To support the Identity capability a manageability endpoint implements the ResourceId property and the GetResourceProperty message exchange. Thus the simplest possible MUWS compliant manageability endpoint supports only the features of the Identity capability.

The MUWS specification requires the ResourceId property have a value that is unique across space and time. When different manageability consumers discover and identify resources in different ways, a unique value of the ResourceId property is useful to determine whether two endpoint references actually refer to the same manageable resource.

In a limited number of circumstances it may not be possible to define a unique and consistent value for the ResourceId property of a manageable resource. If this circumstance is present, then the CorrelatableProperties capability as defined in the MUWS specification may be used in determining whether two manageable resources discovered and identified by two different manageability consumers actually represent the same manageable resource.

In order to use the CorrelatableProperties capability it is necessary for the manageability endpoint to implement the GetResourceProperty message exchange as defined by the WS-ResourceProperties specification.

2.2.1 The Resource Properties Document

In the first step towards implementing a manageability endpoint we create a resource properties document schema for the resource properties to be supported. This schema is defined with a namespace under the control of the organization responsible for the schema. In our examples we assume that our organization controls the “example.org” domain. While it is not required, it is very handy if the schema document can be placed such that the namespace can be dereferenced. A namespace can be dereferenced if its URL can be used by a web browser to retrieve and view the schema document. For our example, we will place our schema document on the example.org server at the path “/services/MyPdaDevice.xsd”.

It is possible to just use the resource properties document already defined in MUWS part 1 for our simple first example. However, since we know we want to add additional capabilities to our manageability endpoint for our resource in subsequent examples, we define our own resource properties document schema.

The ResourceId property is already defined in the MUWS schema within the IdentityPropertiesType complexType. An easy approach to achieve the right property reference is the following:

§         Create an empty complexType and sequence

§         Identify an element referring to the ResourceId property in the MUWS schema containing IdentityPropertiesType

§         Cut-and-paste the identified element into the empty complexType sequence created in step 1

This approach helps assure that any minOccurs and maxOccurs attributes are correctly defined.

By following this approach we can define the MyPdaDeviceProperties element. The name of the element can be whatever is appropriate for the type of resource and is not specified by MUWS. For our example, the schema appears as follows:

Key aspects of our schema include:

§         the target namespace

§         the definition of XML namespace prefixes

§         the import of any foreign XML schemas

§         the local definitions

Next, we create one additional schema document that helps manageability consumers differentiate among representations of a resource.

In our example, we use a SOAP header as an aid in the differentiation of resource representations. Thus, we need to describe the SOAP header in an XML schema. By describing the resource selector element within a separate document and XML namespace we allow the same resource selector element to be used to select any resource, even if it is not a MyPdaDevice in the example.org domain. If instead, we had decribed the resource selector element within the MyPdaDeviceProperties schema, then we would find it awkward to use the same resource selector element to select resources of a type other than MyPdaDevice.

2.2.2 The WSDL Document

Now that we have a complete resource properties document schema we can define the WSDL document for the manageability endpoint in our simple example.

As described in the previous section for the resource properties document schema, we use a namespace within "example.org". Similar to the resource properties document schema, it is very handy to be able to dereference the namespace used in the WSDL to retrieve the actual WSDL document. Thus, we choose a target namespace we are able to derefernce.

Since we do not define any new operations for our simple manageable resource we do not need to describe any messages in our schema document. Our WSDL document simply references schemas as published with the WS-ResourceProperties specification to describe the appropriate message elements.

The entire WSDL document for our example appears as follows::

The key points regarding our example WSDL document are as follows:

WSDL Elements	Meaning of WSDL Element	Notes
targetNamespace=	the target namespace	This is the URI of the namespace that is created by means of this document.
xmlns:nnnn=	the definition of XML namespace prefixes	These definitions encompass all namespaces of those elements that are defined elsewhere than in this document.
<w:import ...>	the import of foreign WSDL documents	The import of foreign WSDL documents is done outside of the WSDL types section, and the import of foreign XML schema documents is done inside the WSDL types section within the schema element. This organization complies with a recommendation made by the WS-I Basic Profile 1.1.
<w:types> ... </w:types>	the WSDL types section	We do not define a target namespace for the embedded schema in the WSDL types section. This is not a problem as we have not defined anything in the types section. Rather, the types section is used only to import other foreign XML schema documents.
<w:portType ...> ... </w:portType>	the portType section	The portType “MyPdaDevicePortType” includes the attribute “wsrf-rp:ResourceProperties” to refer to the schema definition for the resource properties of our simple resource. The only required operation on our portType is “GetResourceProperty”. This operation can be cut-and-pasted from the GetResourceProperty portType as defined in the WS-ResourceProperties specification. For our example, the wsa:Action attribute is present for messages defined for the operation. The presence of the wsa:Action attribute allows us to avoid any ambiguity caused by aggregating this operation into a larger portType defined in a different XML namespace. As a general rule, it is a good idea to follow this practice for Web services that support the WS-Addressing specification.
<w:binding ...>   ... </w:binding>	the binding section	The binding in our WSDL document is for SOAP 1.1 over HTTP. Any binding may be used as appropriate for the environment in which the endpoint is deployed.
<w:service ...>   ... </w:service>	the service section	The service in our WSDL document includes a single port that uses the binding defined in our WSDL document. An example endpoint address is included for the port. Remember to change this address to something appropriate for your environment. Additional port definitions may be added for services that can accept alternative message channels. For example, a second port definition could be added referencing the same binding with an SSL based endpoint URL.

2.2.3 Example SOAP Messages

We now have a complete description for the manageability endpoint of the resource in our example. With this description, developers can write the code to support the necessary message exchanges. In order to communicate with an endpoint it is necessary for a manageability consumer to obtain a wsa:EndpointReference (EPR) to the manageability endpoint for the resource. In this step we assume that a manageability consumer receives an EPR from the manageability endpoint using some out-of-band technique. The set of information and their values in the EPR will vary between implementations. This variationis not important, as a manageability consumer needs only to follow the rules specified in the WS-Addressing specification [WS-Addressing] for formatting messages sent to the referenced manageability endpoint. An example of a message is constructed with an EPR appears as follows:

The presence or absence of the ReferenceProperties element in the EPR depends upon the needs and implementation of an endpoint. If a SOAP header is required by the endpoint in order to select the target resource representation for a message, then the ReferenceProperties element is required. If an endpoint can differentiate between resource representations without a SOAP header, then the ReferenceProperties element is not required.

For our example, we assume it is necessary to send a SOAP header to differentiate between resource representations at an endpoint. This SOAP header element is defined in the namespace “http://example.org/services/localDefinitions.xsd” as created in section 2.2.1 of the MUWS Primer. Although it is permitted, it is not necessary for this element to have the same name or value as the MUWS ResourceId property. In our example we use distinct values for the WS-Addressing ReferenceProperty and the MUWS ResourceId.

An example request message to retrieve the value of the MUWS ResourceId property appears as follows:

In our example SOAP message, the SOAP header elements, including the headers indicated in the ReferenceProperties element appear in order to comply with the WS-Addressing specification. If we wish to retrieve the value of the ResourceId property from any other resource, then the only parts of the message that need to be changed are derived from the correct mapping of the contents of an EPR into the associated SOAP headers of our example SOAP message. In our example SOAP message the SOAP Body contains the GetResourceProperty request.

An example response message for the above request appears as follows:

In our example response, the SOAP headers appear in order to comply with the WS-Addressing specification and in order to comply with the values in the header of the request message. The SOAP Body contains a GetResourceProperty response with the value of the ResourceId property for a resource representation. The particular value and form of the contents for a ResourceId property depend upon the implementation of a given manageability endpoint.

Faults can be returned from any manageability endpoint and are usually based on a misunderstanding, assumption, or error on the part of a manageability consumer. For example, a fault message would result if a manageability consumer requested the retrieval of the muws-p2-xs:Relationship property from our simple endpoint because it does not know about this property. Our example fault message appears as follows:

Notice that we use a fault message that complies with the WS-BaseFaults [WS-BaseFaults] specification.

At this point in the primer we have completed our example definition of a very simple manageability endpoint that is fully compliant with the MUWS specification.

2.3 Adding a WSDM Capability

Now that we have covered the minimum functionality required of a manageability endpoint, we wish to add another manageability capability to the enpoint in our example. For the purposes of this primer, we want our first additional capability to be easy to understand and implement. Thus we choose to add the MUWS Description capability to our resource.

The MUWS Description capability defines properties which we need to add to the resource properties document schema. Since the MUWS Description capability does not define any new operations we do not need to modify the WSDL document. See section 2.5, "Adding Property Access Operations", of this primer to see how to add an operation to a manageability endpoint.

Adding a manageability capability involves modifying the resource properties document schema in order to define the properties for the capability. Adding a manageability capability may also involve modifying the WSDL document in order to define the message exchanges for the capability. The MUWS Description capability defines three properties (Caption, Description, and Version). Of course, it is possible to support additional resource-specific description properties which are added in the same way.

In this and in subsequent sections of this primer we discuss only the modifications to the documents we created for our example in section 2.2, "Exposing Resource Identity". The final documents, containing the cumulative set of capabilities presented in our examples in this primer are located in the appendix of this primer.

2.3.1 Modifying the Resource Properties Document

The properties of the MUWS Description capability are defined in part 2 of the MUWS [MUWS Part 2] schema. We want to modify portions of our example MyPdaDevice schema to add support for the properties of the MUWS Description capability. In particular, we want to:

§         add a declaration for the XML namespace prefix to use for the MUWS part 2 schema

§         add an import for the MUWS part 2 schema

§         add a reference to the Description, Caption, and Version properties

There is a cardinality associated with the Caption, Description, and Version properties. A resource may have zero, one, or many instances of the Description and Caption properties.A resource may have zero or one instance of the Version property.

The new XML namespace prefix is added to the other prefix declarations in the root schema element as follows:

The new schema import statement is added after the import statement for the MUWS part 1 schema as follows:

Finally, the new references to the Description, Caption, and Version property elements are added to the resource properties document schema for MyPdaDevice. Since the WS-ResourceProperties specification says that the order of property elements in the document schema is not relevant, we just add the Description, Caption, and Version property elements at the end of our existing list.

The addition of these property references provides a good example of why this primer encourages the developer to copy-and-paste from the MUWS XML schema. Notice the presence of the minOccurs and maxOccurs attribute for each property element is very important and must have a correct value in order to comply with the MUWS specification.

With these few changes to the resource properties document schema, we have added the properties for the Description capability. Once support for these properties is implemented a manageability consumer is able to retrieve their value(s) using the GetResourceProperty message exchange. If a manageable resource has no caption, no description, or no version then the manageability consumer receives a GetResourcePropertyResponse element with no child element. If a manageable resource has many instances of captions or descriptions, then the manageability consumer receives a GetResourcePropertyResponse element with a child element for each instance of the requested property.

We have now added the MUWS Description capabilty to our example manageability endpoint.

2.3.2 Examples of Description Capability Messages

We now take a look at some example messages for accessing the MUWS Description capability.

As discussed in section 2.2.3, the SOAP header in a MUWS message is driven by the need to comply with the WS-Addressing regarding rules on the use of EPRs, and the WS-Addressing rules for the formatting of a response message to a given request message. For this reason, we only provide examples of the contents of the SOAP Body. We do this in order to highlight where differences exist within the MUWS messages.

For this example, we assume our manageable resource has 2 instances of the Description property, no instances of the Caption property, and one instance of the Version property. These properties appear in the resource properties document for our resource as follows

Since the request is very similar for all of the properties and the request is the same as in section 2.2.3, we show only one request example as follows:

The response message to this request returns a list of Description property instances. If a manageable resource does not have any instance of the Description property, the corresponding response contains a GetResourcePropertyResponse element with no child element. If there are many instances of the Description property, then the response contains many instances of the the Description property element. The Version and Caption properties follow similar rules. Notice that there is at most one instance of the Version element. Consider the example response:

And the alternate example of a response:as follows:

In the XML above, the first response is the result of a request for the Caption property on a resource that has no Caption property instance.

MUWS does not specify a particular format for the Version property. Resources have widely varying versioning formats. If the Version property is not present for a manageable resource, then the response would appear the same as for the Caption property.

2.4 Manageability Characteristics

In this section we discuss the MUWS ManageabilityCharacteristics capability. This capability is the only one defined by MUWS describing information about the manageability support for a resource rather than describing information about the resource itself. The MUWS ManageabilityCharacteristics capability contains just one property, ManageabilityCapability. This property describes what management functionality the manageability endpoint of a resource offers a manageability consumer. The ManageabiltyCapability property describes a set of URIs. Each URI identifies a capabilitiy that is defined in a specification and supported by the manageability endpoint of a resource.

Because a resource may expose multiple manageability capabilities, this property can occur multiple times in a resource properties document. Specification of this property in the resource property schema, therefore, is as follows:

Each occurrence of the <ManageabilityCapability> element in an instance of a resource properties document specifies a URI for a different capability exposed by the resource. Each URI is defined by MUWS, MOWS, or another resource manageability specification. Since a capability can be extended into a resource or a domain specific capability the ManageabilityCapability property should contain a URI for each and every manageability capability supported by the resource, including any capability that was extended. Thus, we have an example ManageabilityCapability property instance as follows:

At this point in the primer the manageability endpoing for the resource in our example only supports three capabilities. As we further develop this manageable resource we will add additional manageability capability URIs to this list.

The ManageabilityCharacteristics capability is useful for enabling scaleable discovery and course grained introspection of resources. With a list of the manageability capabilities for a set of manageable resources, a manageability consumer can easily answer a questions like, ‘Which resources can be configured?’ A resource that can be configured is a possible candidate for becoming part of an autonomic loop.Given a hundred resources, a manageability consumer can use the ManageabilityCharacteristics capability to determine what high level capabilities are provided by a resource and quickly decide whether to continue detailed introspection of the Schema and WSDL interfaces, or simply to categorize the resource within a high level topology browser and defer further introspection until drill down on the resource is actually performed. By using the ManageabilityCharacteristics capability, a manageability consumer eliminates the need to perform large scale comparisons on operation and property patterns in order to identify signs and markers for certain interfaces. Section 4.1 of this primer discusses the discovery of resources. This section shows how convenient it is to register manageable resources so that a manageability consumer has the ability to search for and to discover a manageable resource based upon the ResourceIdentity and ManageabilityCharacteristics capabilities.

2.5 Adding Property Access Operations

In the previous sections of this chapter, we added the properties of the MUWS Identity, Description, and ManageabilityCharacteristics capabilities to our resource properties document schema. Also, we presented examples of message exchanges retrieving the value of a single resource property using the GetResourceProperty operation.

In this section of the primer, we will add new property access operations. The new property access operations we define will allow a manageability consumer to retrieve the values of multiple resource properties, to modify the value of multiple resource properties, and to query the resource properties document using a query expression language such as XPath [XPATH]. In this section we will discuss how to modify the WSDL document in our example and present some example message exchanges for our new property access operations. Developers are encouraged to refer to the WS-ResourceProperties specification for more detail.

2.5.1 Modifying the WSDL Document

If we wish to add a new property access operation then we need to modify our WSDL document. In particular we wish to add three property access operations, as follows:

§         GetMultipleResourceProperties

§         SetResourceProperties

§         QueryResourceProperties

These three operations are already defined by the WS-ResourceProperties specification. In our example, all we need do is copy-and-paste these three property access operations from the portType definition in the WS-ResourceProperties WSDL document into our portType definition in our WSDL document and add the necessary bindings.

Since we do not define a new property access operation, there is no change to the import of foreign WSDL and schema documents. There is no change to the service element of the WSDL document in our example. The portions of the WSDL document that we need to modify are the portType and the binding. A complete WSDL document for our example is provided in appendix A of this primer.

We define a WSDL portType that includes all three property access operations in addition to the required GetResourceProperty operation as follows:

As discussed in section 2.2.2 of this chapter, it is a good practice to add the wsa:Action attribute to messages we define for property access operations. This practice allows us to avoid any ambiguity caused by the aggregation of operations into a larger portType that is defined in a different XML namespace.

Now that we have the new operations in our portType definition, we need to bind these new operations to a message channel protocol in use by our manageability endpoint. For our example, we use SOAP 1.1 over HTTP, as follows:

2.5.2 Example of Property Access Operation Messages

Now that we have modifyied our WSDL document, developers can write code to support the message exchanges for the operations.

Consider the resource properties document, introduced in section 2.3 as follows:

The GetMultipleResourceProperties operation is used to retrieve property values for all three of the Description capability properties in a single message exchange. The request message contains a list of ResourceProperty elements. Each ResourceProperty element contains an xs:QName corresponding to the QName of a resource property element defined in our resource properties document schema.

The SOAP body of a GetMultipleResourceProperties request message to retrieve the values for all three MUWS Description capability properties appears as follows:

And the response apeears as follows:

Notice that the muws-p2-xs:Caption property is not added as a child element of the response message. This is because the muws-p2-xs:Caption property is defined in the schema with minOccurs=”0” and there is no current instance of the property. Since there are two instances for muws-p2-xs:Description property both are added as child elements of the response message.

So far in this chapter, we have discussed how a manageability consumer uses the GetResourceProperty and GetMultipleResourceProperties operations to retrieve values of resource properties for a managed resource. In contrast to these two operations, the SetResourceProperties operation allows a manageability consumer to change values of multiple resource properties in a single request. There are three ways to change the value of a resource property as follows:

·         insertion,  by means of an <Insert> element

·         updating,  by means of an <Update> element

·         deletion,  by means of a <Delete> element

Each type of change is modeled as a separate type of component within a SetResourceProperties request message.

To demonstrate the use of the SetResourceProperties operation, we choose to update both the English and the French descriptions for the resource in our example. The resource property values we wish to change need be defined as modifiable. As specified in MUWS, the Description element is modifiable.

The request message appears as follows:

If the update is successful, then the updated resource properties document appears as follows:

And the response message appears simply as follows:

If, for some reason, a manageability endpoint can not update the muws-p2-xs:Description property, then a SetResourcePropertyRequestFailedFault is raised and sent as follows:

Other faults are defined for the SetResourceProperties operation. Developers should read the WS-ResourceProperties specification and decide which fault to raise for a given situation.

In our example, the last property access operation we wish to add is called QueryResourceProperties. This operation allows a manageability consumer to query the resource properties document using a query expression language such as XPath. As a simple example, we wish to know if the MyPdaDevice resource in our example is version 1.4.2. The request message we send to the manageability endpoint to evaluate the query expression against the root element of the MyPdaDevice resource properties document appears as follows:

Notice that namespace prefixes may be used within query expressions. The namespace prefixes that are in context for the QueryResourceProperty element may be used in a query expression. In the example above, we assume the muws-p2-xs prefix is declared on the SOAP envelope element. The query expression in the above request conforms to the XPath 1.0 language, as specified by the URI string in the Dialect attribute. The other well-known dialect identified by the WS-ResourceProperties specification is:

            http://www.w3.org/TR/2003/WD-xpath20-20031112

This dialect corresponds to the XPath 2.0 (working draft) language.

For the example resource properties document in our example, the above query expression evaluates as true. Thus the response message appears as follows:

2.6 Operational Status

The Operational Status capability provides a means to convey the health of an application in a generic manner.This manageability capability contains only one property, OperationalStatus. The OperationalStatus property is added to our resource properties document as follows:

The OperationStatus property can have one of four values as follow:

·         Available:     the resource accepts new requests and performs as expected

·         Unavailable: the resource s not accepting new requests and is not performing as expected

·         PartiallyAvailable: the operational status of the resource requires further inspection. The resource may be degraded due to errors, or may be in the process of honoring a quiese. This is a neutral operational status with no associated ‘goodness’ or ‘badness’

·         Unknown:     the operational status of the resource cannot be determined

While it is up to the designers and developers of a resource to choose the conditions and resource states changes (see section 2.12) causing a change in OperationalStatus, the semantics of the four possible values for this property should remain consistent.

When the OperationalStatus property changes value, a WS-RF property change event is sent to each subscriber of the ‘muws-p2-xs:OperationalStatus’ topic. Each subscriber of the ‘muws-ev:OperationalStatusCapability’ topic is also sent a notification. For more information on these event topics, see section 2.10, "Notifications". An example of an OperationalStatus change notification is presented in section 2.10.3.1 of this primer.

When the OperationalStatus property is available and the Operational Status capability is supported, the ManageabilityCapability property should expose this as follows:

Notice the OperationalStatus property is read only since it reflects the current status of a resource. Control of the current status of a resource should be achieved indirectlly via extension of the State capability.

The resource properties document for the PDA in our example appears as follows:

2.7 Metrics

This section defines how to represent metrics and the metadata necessary to correctly process and interpret a metric value. WSDM MUWS, of itself, does not define any management metrics. The metrics appropriate for a managed resource are specified by the model of that resource. Thus, as is illustrated below, the metrics of a resource are accommodated within MUWS by extending the Metrics capability. See section 2.8 of this primer for more information on extending capabilities.

MUWS defines one property pertaining to Metrics, the current time, specified as follows:

and indicates support for the metrics capability with the following ManageabilityCapability:

2.7.1 A Scenario for PDA Metrics

Manageable resource must define their own model of the metrics it wishes to expose through MUWS facilities. Therefore, to make use of the MUWS Metric capability it is necessary to define a resource specific metric capability. The following sections of this primer (sections 2.8 through 2.11) will describe the WSDM facilities that must be brought into play in order to define a resource specific metric capability.

When we define a resource-specific Metric capability we must extend the MUWS Metric capability. We extend the MUWS Metric capability in order to tie the resource-specific metric model into the MUWS architectural framework. To describe this extension, we present four metrics for our PDA device as follows:

§         FailedConnections. This metric tracks the number of failed attempts at establish a connection with a server.

§         MessagesReceived: This metric tracks the number of messages received by the PDA within the last 30 minutes relative to the last message received. Unlike the FailedConnection metric, the MessagesReceived metric is a “moving window” on the number of received messages based on when the last message was received.

§         AverageResponseTime: This metric provides the average response time for the PDA over the last 10 minutes. This metric is recalculated every 2 minutes. The AverageResponseTime metric also provide a moving window on average response, but unlike MessagesReceived, this metric is recalculated on a predefined periodic basis.

§         MemoryInUse: This metric provides the manageability consumer with the percentage of power remaining in the battery whenever the manageability consumer queries for this resource property.

Let us further assume that the manageability consumer wants to reset the count of FailedConnections after the problem has been resolved that prevented the PDA from connecting to the server. Therefore, the PDA manageability endpoint must expose a ResetServerConnectionMetric operation. Furthermore, our manageability consumer wishes to be informed—in real time—whenever an attempt to connect to a server fails. This last requirement brings into play Subscriptions and Notifications, presented in section 2.10 of this primer. In our example, the manageability consumer will subscribe to the manageability endpoint of our PDA device to receive notifications concerning failed attempts to establish a server connection for our PDA device. Finally, for reporting purposes, we would like the management consumer to group metrics related to remote devices into the same group of metrics.

2.7.2 Metric Datatypes and Exposing Metrics

The preceding scenario involves three metric datatypes: FailedConnections and MessagesReceived are counters and therefore have non-negative integer values; AverageResponseTime is a duration, and MemoryInUse is a percentage. These three types are typical metric datatypes, but we need to define them before we can use the metrics in the schema of the our resource properties document.

To define metric datatypes, however, requires understanding more about how metric data has to be exposed. Notice that the preceding metrics involve special considerations. For example, FailedConnections are counted from the time that the counter is reset by the manageability consumer, but that MessagesReceived and AverageResponseTime are calculated within a specified window (i.e., duration of 30 minutes and 10 minutes respectively). For metric values to carry proper semantics, it is necessary to qualify metric data with attributes regarding the conditions under which the data was collected or calculated. In WSDM, metric data can be qualified with the following attributes:

§         ResetAt, which indicates the time at which the value of the metric property was reinitialized

§         LastUpdated, which indicates the most recent time at which the value of the metric property was updated

§         Duration, which indicates the time over which the value of a metric property was collected, counted, or measured previous to the LastUpdated time.

These attributes are defined in the MOWS Schema in an attributeGroup named MetricAttributes. Definition of metric datatypes MUST include an attribute reference to this group. Thus we can define the three datatypes used in the PDA Metric Scenario as follows:

Thus, data on FailedConnections may be reported as follows, which reports 5 connection failures since July 1, 2005 12:01:16 (PM, GMT), with the last connection failure occurring at 12:25:53 on August 11, 2005):

Notice that not all three metric attributes are relevant to each metric property. In this case, the collection interval is not predefined as a duration. Thus, the durration attribute is not reported. The collection interval must be calculated from the currentTime less the ResetAt time. Note that all times are relative to the resource. In order to rationalize the time stamps, the CurrentTime property must be retrieved with the metrics. This is why CurrentTime underlies all metric capabilities and is specified in the MUWS Metrics capability.

The appropriate attributes for a metric are defined by the metadata on the metric, specifically metadata defining the metrics relationship to the time in which is collected. Metric metadata is explained in section 2.11.2. Metadata for the PDA metrics, and thus the relevant attributes that qualify our four metics, is presented in section 2.11.2.1. Exposing metadata (section 2.11) is the final step in developing PDA Metrics. In following section (section 2.8) we begin by defining the steps involved in extending a WSDM capability.

2.8 Extending a Capability

We can extend a manageability capability by adding semantics, resource-specific properties, operations, or events. If a capability is extended to create a new capability, then the extended capability supports the same semantics, behaviors, properties, operations, and events as the base capability and adds some behaviors, properties, operations and events. The specification for an extended capability must clearly identify what capabilities it extends or requires. We need to clearly identify the base capabilities extended by a new capability since this information is not available on a resource or in metadata at this time.

To extend a capability or to define any new capability we perform a series of steps as follow:

§         Define a URI for our extended capability using a namespace we control. Like any capability, an extended capability is identified by a URI.

§         Add a new instance of the ManageabilityCapability property. When a resource supports our extended capability, the ManageabilityCapabilities property of the resource must include a URI for the base capability and a URI for the extended capability.

§         Define all properties supporting our extended capability in a schema document. Notice this schema document does not need to be resource-specific since some properties of our extended capability may already be defined within other schema documents. Thus we can simply import properties as defined elsewhere.

§         Define each message exchange for accessing our extended capability in a WSDL document. Some message exchanges may be defined within other WSDL documents. We can simply import message exchanges as defined elsewhere.

§         Define a new TopicSpace document that includes a Topic for our extended capability. If new events can be generated by our capability then we add the requisite topics to the TopicSpace document. For a discussion on creating a TopicSpace, see section 2.10.4 in this primer.

§         Document our extended capability in a specification, making sure we indicate which capabilities this new capability extends and any other capabilities required in support of our extended capability. At this time MUWS does not define a template for extending a capability. We want to be sure to document the semantics of all new properties, operations, and notifications. For additional information, see section 2.11, "Building and Exposing a Metadata Docment".

An extended capability allows any manageability consumer lacking support for a particular extended capability to manage the resource from a perspective of the base capability. Thus a manageability consumer that is limited in this way can still manage a resource using all features of the base capability. However, such a manageability consumer is not able to access advanced features of the extended capability. A manageability consumer supporting a particular extended capability is able to use enhanced features offered by the extended capability for enhanced manageability of a resource.

To begin extending the MUWS Metric capability we define a URI for the new capability within our example domain, http://example.org/capabilities/PDAMetrics. When this capability is included in an instance of the resource properties document for a resource, this URI and the URI identifying the MUWS Metric capability should be reported. In our example, this appears as follows:

2.9 Adding Resource-specific Operations and Properties

The MUWS specification defines many properties and operations that are common to all types of resources. Thus, for many resources we do not need to define additional resource-specific properties and operations. However, in some cases it is desirable to define operations specific to the monitoring or controlling of some unique aspect of a resource. Likewise, in some cases it is desirable to define properties that represent some unique characteristic of the state of a resource.

A resource-specific operation is exposed by adding its definition to the operations of a WSDL document. An operation that is unique to a particular device is defined directly in the WSDL document for that device. We would add the definition of an operation that is unique to the MyPdaDevice to the WSDL document in our example. In cases where an operation also applies in general to a set of devices we may wish to define the operation in a WSDL file that is shared by the set of devices, and then cut-and-paste the definition of the operation into the device-specific WSDL file.

In this section we add two properties and an operation that are somewhat arbitrary. However, in the next section we will extend a previously defined capability and include these two properties and operation within the extended capability. Since we add only properties and message exchanges that are resource-specific, these changes do not result in a new capability.

2.9.1 Adding Resource-specific Properties

In section 2.3.1 we modified our resource properties document by adding resource properties defined in the MUWS schema. In this section we add the new properties to the resource properties document as described in our scenario in section 2.7.1.

Include the following resource property declarations in the schema of the resource properties document.

Notice that to support reusability of these metric datatypes, we should include the metric datatype definitions (see section 2.7.2) in our schema for localDefinitions (exh:).

2.9.2 Adding Resource-specific operations

We must also add an operation to reset the values of our two PDA metrics. Operations are specified in the WSDL. A property access operation that is not specific to a resource references the definition of the reset operation in other WSDL and schema documents. Operations specific to a resource must have a type created to represent the message, and the WSDL message elements must be created. The message on the wire contains the operation name as specified within the element in the schema document. For our example, we start with the schema in the resource properties document and create the request and response message types as follow:

We can now define the message structures in the WSDL document for our PDA resource. Since we already import the schema for our PDA there is no reason to add a new import statement. We add the message and operation structures as follows:

In the above WSDL, notice the inclusion of the ResourceUnknownFault. This fault should be added to all operations. If there is a resource-specific fault, then it should be defined as a message and included within the WSDL as well.

Add the new operation to the binding in the same way as we added the operations in section 2.5.1. See Appendix A of this primer for the complete WSDL document.

2.10 Notifications

In addition to allowing manageability consumers to retrieve information from manageability endpoints, MUWS allows a manageability consumer to register to receive notifications of events pertaining to a manageable resource. For example, a manageability consumer can be notified when a threshold is reached in a particular metric or when a new relationship is created for a resource. For additional information about relationships see chapter 3, "Building Relationships".

The notification used by MUWS is defined by the WS-Notification family of specifications, which consists of three specifications. The WS-BaseNotification [WS-BaseNotification] specification describes messages for creating subscriptions and for managing those subscriptions. The common structure for notifications is defined within this specification.

The WS-Topics [WS-Topics] specification describes a means for exposing a hierarchical model of potential events. MUWS defines specific event topics corresponding to a management domain. Examples of a notification topic and its corresponding event are as follow:

§         Creation or destruction of a new relationship.

§         Creation or destruction of a manageable resource and/or a manageability endpoint.

§         Changes to properties exposed by a manageability capability.

WS-Topics is intended for use with other topics as defined within other specifications as well as with domain-specific topics. For more information on Topics, see section 2.10.4.

The WS-BrokeredNotification [WS-BrokeredNotification] specification describes a means to relieve an event producer from the burden of propagating event notification messages and from the overhead of handling subscription messages. Thus, WS-BrokeredNotification facilitates scalable systems architecture for managed resources that produce notifications through the delegation of these tasks to a broker. While MUWS allows use of the brokered notification mechanism as appropriate to a manageable resource it does not require support of brokered notification. For details on the WS-Notification family of specifications, we suggest a reading of the specifications and documentation as published by the OASIS WS-Notification technical committee.

2.10.1 Changes to the Resource Properties Document

A common use case of notifications for systems management is the monitoring of changes to the state of a resource as exposed by its resource properties document. The monitoring of changes to the state of a resource is achieved through the ResourcePropertyValueChangeNotification mechanism as defined in the WS-ResourceProperties specification. For each property in a resource properties document, a topic is created. Each topic name is based upon its associated property name. A manageability endpoint indicates its ability to provide a notification on change of a property by including the corresponding topic name in its list of supported topics.

WS-BaseNotifications defines three properties that must appear in the resource properties document of a managed resource supporting notifications. Thus, we add these XML elements to the resource properties document for our PDA device as follow:

Notice the namespace of these elements is the same as defined for WS-BaseNotification. It is necessary to declare and import the "wsnt" namespace as in previous examples, incorporating a foreign namespaces. See Appendix A of this primer for a complete Schema for our PDA example that declares and imports the "wsnt" namespace form the WS-BaseNotification specification. All topics supported by a resource should be included in the Topics resource property. See section 2.10.4.1 for an example.

Since the Notification capability is not a MUWS capability, we do not add a new instance of the ManageabilityCapability property.

2.10.2 Changes to the WSDL Document

When supporting notifications, we must add the Subscribe message exchange pattern to our WSDL document. The necessary operations are defined in the WSDL document for the WS-BaseNotification specification. We just copy-and-paste these operations and add the necessary XML namespace declarations and imports. In our example, the “wsntw” XML namespace is imported from the WSDL document for the WS-BaseNotification specification and appears as follows:

Notice that wsa_Actions was also imported for our WSDL example. We also need to add the Subscribe and GetCurrentMessage operations to the binding section of our WSDL document. Notice that these operations are added in the same way as other operations. A complete WSDL specification, including the bindings, for our example is located in Appendix A of this primer.

2.10.3 ManagementEvent Format

MUWS Part 1 defines the base ManagementEventType. This type is used for all events emitted by a MUWS compliant resource. The muws-p1-xs:ManagementEventType defines three elements and one attribute. The relevant fragment of the MUWS Part 1 schema appears as follows:

Notice that the structure of the ManagementEventType provides extensibility for both elements and attributes from other namespaces. MUWS Part 2 makes use of this extensibility by adding an additional element to the three elements defined in the structure above.

Of the three elements defined in the ManagementEventType, the two required elements are muws-p1-xs:ManagementEvent/EventId and muws-p1-xs:ManagementEvent/SourceComponent.

The EventId uniquely identifies an event to distinguish it from similar events that may have occurred involving the same resource.

The SourceComponent provides a reference to the manageable resource involved in the event. Notice the SourceComponent may contain a different reference than the resource reporting the event. For example, router "A" may observe that an adjacent router "B" is not responding. Router "A" may report the problem it observes involving router "B". In this case, router "A" is the reporter and router "B" is the source. Since most events are generated by the resource involved in the event, the ReporterComponent element is not necessary if it refers to the same resource as the SourceComponent element.

The attribute, muws-p1-xs:ManagementEvent@ReportTime is optional yet recommended. This attribute provides the UTC report time of an event. The report time may be different from the time at which an event actually occurred. For example, a router that restarts due to an internal failure may not report the failure until self-restart is complete. In this case, the ReportTime is different from than the actual time of the internal failure event.

MUWS Part 2 adds the Situation element, This element is a container for the specifics of an event. The Situation element contains  a number of elements. However, the most critical and only REQUIRED element is SituationCategory. This element provides a canonical categorization of an event into one of twelve general categories. These twelve categories are defined in the muws-p2-xs:Situation/muws-p2-xs:SituationCategory element. These categories are further clarified in Appendix F of MUWS Part 2.

The SituationCategory element provides a means for a manageability consumer to quickly categorize an event and facilitates the correlation of multiple events involving multiple resources. Industry experience has shown that an effective root-cause analysis of complex operational problems in a multi-tier environment can be reduced from hours or more to just minutes through simple correlation heuristics using the SituationCategory element.

Keep in mind that the value provided by the SituationCategory element, is only as good as the implementation of a manageable resource. If an implementation takes a lazy approach and categorizes every event as an OtherSituation, then the value provided by the SituationCategory element is rendered useless. Thus, an accurate categorization of an event is important when implementing MUWS Events. The categories defined in the MUWS specification are ordered so that more critical categories are listed ahead of less critical categories. For example, an event categorized as an AvailabilitySituation is considered more critical than an event categorized as a StartSituation. The primary reason for this ordering of categories is to provide some guidance for categorizing events. When ambiguity exists in regard to the categorization of an event for a manageable resource, it is generally recommended to use the more critical category.

Finally, muws-p2-xs:Situation includes a number of optional elements as follow:

SituationTime – the time an event actually occurred – this is RECOMMENDED.

SuccessDisposition – a qualification of the SituationCategory. For example, a StartSituation that failed has a SuccessDisposition of UNSUCCESSFUL.

Priority – the relative importance of an event. Priority is distinct from Severity. See Severity below for a description of this distinction.

Severity – the relative effect an event has on the operational status of a resource. Severity values are based upon Perceived Severity as defined within the Distributed Management Task Force (DMTF) CIM Alert Indication. A more critical severity identifies an event causing an involved resource to become severely constrained. A less critical severity identifies an event allowing an involved resource to remain fairly functional. The distinction between Severity and Priority we illustrate by example. Consider a disk drive that crashes within a RAID storage system. The severity for this event may be less critical because the RAID storage system contains spares and is fully capable of compensating for a crashed disk. Also, the performance of the RAID storage system is not affected. By contrast, the priority of this event is more critical since a disk has completely failed, reducing the pool of available spares by one. If the failed disk is not replaced to replenish the pool of spares, then the ability of the RAID storage system to self heal is further jeopardized if more disks crash . In this example, a manageability consumer could recognize the overall business impact of an event and take appropriate action to order and replace the crashed disk drive.

Message – In general, this element is a human readable text message providing the details of an event. A message may simply be displayed on a management console or may be further parsed by a manageability consumer as needed by its management applications.

SubstitutableMsg – This element along with its associated attributes and elements appears when a message contains data and formatting controls cataloged elsewhere. The MsgId attribute provides a reference to the message in a catalog. The MsgIdType attribute identifies the type of catalog to use. Note that in general, the manufacturer of a resource supplies message catalogs. For example, a message of the form: “Disk drive %s, LUN:%d, Head:%d, Track: %d has failed.” The Value for an event instance might be: “Hitachi IC25N080ATMR04-0”, 2, 4, 217; producing the final message: Disk drive Hitachi IC25N080ATMR04-0, LUN:2, Head:4, Track: 217 has failed.” The SubstitutableMsg element is especially useful if a message needs rendering in different languages. A manageability consumer can configure a language specific catalog and the same message can be meaningfully represented in any supported language.

2.10.3.1 Example

Consider a situation in which a manageability consumer wishes to be informed whenever a PDA device goes off line and is no longer available. The PDA device may be temporarily unavailable due to the downloading of software or due to a management query. In order to inform the manageability consumer, a resource must emit a notification when the OperationalStatus property, as described in section 2.6 transitions from the Available state to the Unavailable state. Changes to the resource properties of a resource are reported by means of the <ResourcePropertyValueChangeNotification> element, which is defined in the [WSRF-RP] specification. This element provides both the old value (Available) and new value (Unavailable).

A notification with a SituationCategory of AvailabilitySituation as emitted by the manageability endpoint of our PDA device appears as follows:

A MUWS ManagementEvent serves as the payload of a WS-Notification message.

2.10.4 Creating a TopicSpace

MUWS defines a topic for each capability that produces an event. An implementer of a manageable resource, wants to create one or more additional topics covering any event unique to  a resource..The biggest choice for an implementer is deciding upon the granularity of the additional resource-specific topics. If we make our topics too fine-grained then a manageability consumer may need to specify several topics in an event subscription list. If we make our topic definitions too coarse-grained then a manageability consumer may receive notification of unwanted events.

Fortunately, we are able to specify subtopics and use the power of XPATH expressions to provide fine-grain topics while also supporting a means for a manageability consumer to generalize on a few, broadly defined topics.

Our first step is to create a TopicSpace to define a namespace for our topics. A TopicSpace can be defined in either a WSDL or another configuration file in XML document format. Next, we define our resource-specific topics within the TopicSpace wrapper,.

For example, when creating notification topics for our PDA device, we provide a notification on a change to the battery charged condition. The battery charged condition can be grouped into five states: Fully Charged, Half Charged, Critical Level, Discharged, and Removed. To support both general as well as fine-grained notifications, our Topics definition appears as follows:

In this example, a manageability consumer can subscribe on BatteryCondition and receive notification of every event related to a change in battery condition. As an alternative, a manageability consumer can subscribe on an individual subtopic, such as BatteryCriticalLevel and/or BatteryDischarged. A manageability consumer can subscribe on the select set of subtopics that are of interest.

2.10.4.1 Topics for Resource-Specific Metrics

In this section we return to our PDA device and its resource-specific metrics example. When we add a capability with a new event to a manageability endpoint, we add a corresponding Topic to the set of Topics for our resource. By doing so, we describe the event for the added capability.

For our PDA metrics, we want an event specifically for notification of server connection failures as described in section 2.7.1). It is good practice to define a topic for each event associated with a capability that is available to a subscriber. When an event is indicated on a subtopic, the event should also be indicated on the base topic. The Topic structure may be defined as follows.

Notice that the wstop:MessagePattern prevents multiple notifications from being emitted on the same event.

The portion of the resource properties document for our PDA device exposing support for the PDAMetrics properties as well the ServerConnectionFailure topic follows:

2.11 Building and Exposing a Metadata Document

In this section we use the WS-Resource Metadata Descriptor specification [WS-RMD], as submitted to the OASIS WS-Resource Framework Working Group, to describe the metadata for the manageability endpoint for our PDA example.

The MUWS specification defines metadata elements for its capabilities, properties, operations, and events. This metadata provides static information associated with a manageability endpoint for a resource and provides a manageability consumer with an improved understanding of the semantics for exposed capabilities. Metadata describes the behavior of the manageability endpoint for a manageable resource. Since it is static, even if metadata is changed there is no change in the behavior of the manageability endpoint for a resource. Thus, metadata cannot be used to control a resource. The MUWS specification states that metadata elements should be maintained in a separate Metadata document that can be queried with XPath, but MUWS does not prescribe a schema for metadata documents.

WS-RMD has a simple, extensible structure defining some basic metadata elements for properties and allowing additional metadata elements. The WS-RMD document is associated with the Resource PortType with two attributes, rmd:metataDescirptor and metadataDescriptorLocation as follows:

Notice the “pda-rmd” prefix refers to the metadata namespace. We declare this namespace in a metadata document as described in section 2.11.1, Constructing PDA Device Metadata. This metadata document contains a GED, MyPdaDeviceMetadataDescriptor, providing the metadata for the resource properties of our PDA device. Notice the metadataDescriptorLocation attribute provides both the full pda-md namespace name as well as the physical location of this metadata document.

WS-RMD provides the general purpose metadata indicated by the MUWS specification as follow:

Mutability indicates a property value may change over time.

Modifiability indicates a property value can be set directly or as a side-effect of some other action

Valid Values provide the set of valid property values

Valid Range provides a range of valid property values

Static Values provide a set of permanent property values

Notifiability indicates a notification is sent on a change to the property value

MUWS defines two additional metadata elements that apply to all properties and operations as follow:

Capability provides a list of the properties and operations supported by a particular capability. This MUWS metadata element allows a manageability consumer to inspect the details of a manageability capability.

ValidWhile indicates when a property or operation is valid for query or execution. This MUWS metadata element allows a manageability consumer to understand the expected behavior of a manageability capability.

A manageability consumer can use XPath dialect to describe the assertions on a resource that must evaluate to true. An example of an assertion is the value of some related properties. State and Status are especially useful properties in this regard. Notice it does not make sense to make an assertion based upon the values of many properties, like metrics, since these values are not valid when a resource is not in the running state.

MUWS defines one additional metadata element that applies to all operations as follows:

PostCondition indicates how a manageability consumer can double check that a particular operation has completed successfully.

Notice that the MUWS PostCondition metadata element follows the same format as ValidWhile.

2.11.1 Constructing PDA Device Metadata

Consider the resource properties, other than metrics, of our PDA device as developed so far. We create a WS-RMD compliant document for MyPdaDevice as follows:

Notice our MetadataDescriptor, PdaDeviceMetadataDescriptor is highlighted above. This fragment is directly drawn from the MUWS specification. Also notice that both WS-RMD and MUWS metadata attributes are defined within the <rmd:Property> element.

Finally, notice that the Version and ManageabilityCapability metadata elements are populated with a list of static values. These values allow a manageability consumer to inspect static manageability information about a resource when the resource is not instantiated. These values also allow a manageability consumer to find a resource supporting a given capability and to see a detailed list of all supporting properties and operations for a capability. In the above example, the list of ManageabilityCapability properties do not change at runtime for the resource.

2.11.2 Metric Metadata

Metadata provides a useful means to describe the behavior and characteristics of metric properties defined for a resource. Metric metadata is specified via six elements. These elements are extensions specified in MUWS Part 2. These elements are as follow:

Element	Use
Capability	identifies the property as a metric
GatheringTime	indicates the circumstance under which the value of a metric is updated
CalculationInterval	when the associated GatheringTime is 'periodic', provides the frequency with which the value of a metric is collected
MetricGroup	identifies a metric as included within one or more groupings of metrics
ChangeType	indicates how the value of a metric is interpreted
TimeScope	indicates if the value of a metric is collected over some elapsed period of time

ChangeType and Timescope are required metadata elements for a metric property and are described in detail as follow:

ChangeType     indicates how the value of a metric is interpreted. A metric property conforms to a behavior as indicated by its ChangeType. The possible behaviors are as follow:

Counter            The value only increases across successive inspections.

Gauge              The value may increase or decrease across successive inspections.

Unknown         The change behavior for the value is not known or cannot be described

TimeScope       indicates if the value of a metric is collected over some elapsed period of time. This metadata element indicates which metric attributes qualify its value. The TimeScope of a metric property must be characterized in one of three ways as follow:

Interval            The value was collected over some time interval prior to its last update. The Duration attribute provides the elapsed time of the interval and the LastUpdated attribute provides the time at which the interval ended..

PointInTime     The value was collected at a single point in time. The LastUpdated attribute provides the time at which the collection occurred.

SinceReset      The value was collected since the last reset of a resource, or since the manageable resource first started collecting data on this metric, whichever is most recent. The ResetAt and CurrentTime values are used to calculate the elapsed time of the collection interval and the time at which the interval ended. It is recommended the LastUpdated attribute be used to provide the time at which the most recent event occurred.

The following table summarizes when to use the attributes of a metric as indicated by its TimeScope. A a represented a required attribute and a r represents an impermissible use of an attribute):

TimeScope	ResetAt	LastUpdated	Duration	Notes
Interval	permitted	a	a	Metric collection interval (value of the Duration attribute) is up to the time of the last update (LastUpdated value)
PointInTime	r	a	r	Other attributes must not be used
SinceReset	a	recommended	r	Use ResetAt time and CurrentTime to calculate the collection interval The LastUpdated attribute specifies the time during the collection interval at which the most recent event occurred

The metadata for a metric property must also specify a GatheringTime for the value of a metric. GatheringTime is an enumeration indicating the circumstance under which the value of a metric is updated. GatheringTime may be one of four values as follow:

OnChange       The value is updated whenever a change occurs.

Periodic           The value is updated on a regularly scheduled basis.

OnDemand      The value is updated whenever a request for the metric is processed.

Unknown         It is unknown when the value is updated.

If the GatheringTime=”Periodic”, then the muws-p2-xs:CalculationInterval must also be specified to indicate the interval at which the metric is updated.

2.11.2.1 PDA Resource-specific Metrics

The resource-specific metric properties of our PDA device are identified in section 2.7.1 of this primer. Our metrics must be defined in terms of the appropriate metric metadata elements, as discussed above. A summary of our PDA metric and associated metadata elements is as follows:

PDA Metric	ChangeType	TimeScope	GatheringTime
FailedConnections	Counter	SinceReset	OnChange
MessagesReceived	Gauge	Interval Duration=30 mins	OnChange
AverageResponseTime	Gauge	Interval Duration=10 mins	Periodic CalcInterval=2 mins
MemoryInUse	Gauge	PointInTime	OnDemand

In addition to the specification of resource-specific metric metadata, our PDA metrics must be tagged with the capabilities they support. In this primer, our PDA metrics are tagged as supporting the Metrics and PDAMetrics capabilities. We also define a MetricGroup to group together all metrics related to a remote device. The metadata for our PDA resource-specific metric properties follows:

2.11.2.2 Example PDA Resource Properties Document with Metrics

The resource properties document, as provided by the manageability endpoint of a PDA, might expose run-time metric values as follow:

Given an understanding of our metric metadata, the interpretation of this information by a manageability consumer is straightforward.

A manageability consumer can draw several conclusions based upon a comparison of this metric information with the currentTime including the following:

·         Within the past 2 months 11 day and approximately 30 seconds, this PDA experienced 5 connection failures, with the last one occurring July 25.

·         This PDA has received no messages in the last 4 seconds

·         In the half hour before that last message, this PDA received 14 messages.

·         The average response time experienced by this PDA between 12:20 and 12:30 was .0107 seconds

·         The average response time was calculated approximately 1 minute (56 seconds) before the manageability consumer made its request

·         When the request was made, the manageability endpoint for this PDA calculated the MemoryInUse metric as well as determined that memory in use is 66% of total capacity

Notice that the semantics of MessagesReceived and AverageResponseTime metrics permit a ResetAt attribute. Consider the ResetAt attribute information as follows:

Notice the ResetAt time occurred during the 30 minute duration in which the MessagesReceived metric was collected. This means the count of 5 messages occurred during the 11 minutes 7 seconds between the ResetAt time and the LastUpdated time. Since the occurrence of a reset is a real possibility during the collection interval of a metric, a manageability consumer must accommodate any reset when interpreting or presenting metrics. For example, the manageability consumer may report the metric information as partial or reject the metric information as invalid.

2.12 State

The MUWS State capability provides an extensible means of exposing the current state and state model of a resource. The state model of a resource is identified by a URI and there is no XML representation for a state model itself. Note that a state model may be standardized and that a standard state model can be extended into a resource-specific state model. Also note that a state model may be entirely resource-specific.

MUWS capabilities like Configuration and Metrics follow a pattern that we use and extend as we create appropriate XML that exposes the state of a resource. As with the MUWS Configuration and Metric capabilities, the MUWS State capability defines some standard schema types for common elements of a State capability. These common elements include the State property types, transition descriptions, and events. A complete example of a well-defined State capability is presented in the OperationalState example in section 3.2.4.1 of MUWS Part 2.

To extend the MUWS State capability we must define a name for each state property, transition, state, and state model. A state property has a type of ‘muws:CategoryType’. A state property can be sub-typed to expose a more specific state when the MUWS State capability is extended.

This primer recommends that designers define both a  property exposing the current state of a resource as well as a property exposing the state immediately prior to the last state transition. This practice allows a manageability consumer to determine how long a resource has been in the current state as well as its prior state. A manageable resource should emit a notification in the event a state transition occurs.

It is a usual practice for the value of a resource-specific State property to be restricted to a relatively limited and static set of possible values. In section 2.12.1, State Model Metadata, we describe how to predefine the set of possible values in the metadata document for our PDA device.

Typically, a resource-specific State property is a read-only value and some resource-specific operations are used to effect a change to the state of a resource.

In our example, we describe the DeviceState model for our PDA device. We want to expose the Off, Initializing, and Connected states of our PDA resource. We also want to expose the ServerConnected, NetworkConnected, Synchronizing, and Idle substates of the Connected state.

These potential values are described for our PDA device as follow:

We can also restrict the valid values of DeviceState using schema. This allows a manageability consumer to validate exposed DeviceState information for our PDA device. An example of validating schema for DeviceState follows:

Thus, a state transition might appear as follows:

See section 5.1, Defining Taxonomies in WSDM, for more information on defining the taxonomy in the schema above.

If the valid transitions for our PDA device are as follow:

Previous State	Current State
Off	Initializing
Initializing	Connected
Connected	Synchronizing
Synchronizing	Idle
Idle	Synchronizing
Idle	Off
Synchronizing	Off
Connected	Idle

Then the state diagram describing these transitions is as follows:

Thus, the XML for a transition from Off to Initializing is as follows:

This information is sent as part of a notification of the state change event. A state event occurs whenever a transition is made and is published on the StateCapability topic. A manageability consumer can use the topic name to filter the content of a state event. We recommend a topic be defined per capability. Since we have just defined a new capability, DeviceState, that extends the State capability, we should also define a DeviceState topic. We can publish events on the DeviceState topic as well.

So the resource properties document for our PDA device now exposes two new properties, DeviceState and LastDeviceStateTransition. We also update the ManageabilityCapabilities property to expose the capability URI for muws:State and pda:DeviceState. Based upon the definitions of state provided above, an instance of the resource properties document for our PDA device might appear as follows:

Usually, the state of a resource is changed by invoking an appropriate operation rather than by directly manipulating the state property of a manageable resource. This approach helps ensure there is only one appropriate way to change the state of a manageable resource. For example, we can define a 'Shutdown' operation that changes the state of our PDA device. The Shutdown operation is defined in the WSDL document for our PDA device. In the schema of the resource properties document for our PDA device, we define the elements involved in the Shutdown operation as follow:

The WSDL for the Shutdown operation follows:

See Appendix A of this primer for the complete WSDL definition of this operation, including bindings.

2.12.1 State Model Metadata

The state model of our PDA device is exposed in its metadata document. Valid values for the DeviceState property are listed to provide a manageability consumer with an understanding of the state model of our PDA device. This state model in our metadata follows:

Notice the metadata for the Shutdown operation in the XML above. This metadata associates the Shutdown operation with the State capability. The Shutdown operation is not idempotent as its invocation affects the behavior of our PDA device. The Shutdown operation has a ValidWhile element and a PostCondition element as described in section 2.11, "Building and Exposing a Metadata Document". The ValidWhile element indicates that the Shutdown operation is valid only if the current state of our PDA device is not ‘Off’. The PostCondition element indicates that when the Shutdown operation is complete, the current state of our PDA device is ‘Off’.

2.13 Advertising a Resource

By advertising the existence of a resource we facilitate the discovery of the resource by a manageability consumer. The existence of a resource is made known in several ways. In this section we discuss the Advertisement capability as defined in part 2 of the MUWS specification. Section 3.2 of this primer, "The Relationship Capability", presents other useful methods a manageability consumer can use to discover the existence of a resource.

While the MUWS Advertisement capability does not define any properties or operations, it does define four notification topics. There is a topic for resource creation and a topic for resource discovery. There is also a topic for resource destruction and a topic for loss of a resource connection. While events published on the ManageableResourceCreation topic indicate that a resource was created, events published on the ManageabilityEndpointCreation topic indicate that a manageability endpoint for an existing resource was created. Events published on the two destruction topics have a similar meaning.

The Advertisement capability can be exposed by any resource having knowledge of the creation or destruction of some other resource. Examples of resources that should expose the Advertisement capability include ServiceGroups, Registries, and the UDDI. If we consider a subscription as a resource, then any resource that supports the WS-BaseNotification Subscribe operation could also support the Advertisement capability. This is because a resource is created every time a manageability consumer invokes the Subscribe operation.

2.14 Operable Collections

When a manageability consumer is responsible for a large number of resources, it is often desirable to group the resources into an operable collection. An operable collection is useful when organizing a resource map, aggregating a status for an administrative domain, an enterprise business application, or an autonomous system consisting of a complex set of inter-related processes.

An operable collection is also useful when a manageability consumer wishes to invoke an operation on all of or a subset of the resources in an operable collection. With WSDM, we suggest an operable collection of resources should be represented as, and accessible as a WS-ServiceGroup [WS-ServiceGroup]. A WS-ServiceGroup may be extended to support additional operations having collection-specific semantics. An operation may apply to the collection itself, as when a collection is cloned, or an operation may apply to each member of an operable collection, as when a "start" operation is invoked.

When we develop an operation that applies to each member of an operable collection, the operation may be invoked directly on each member as a pass through, or a start operation that is supported by the manageability endpoint of each member of an operable collection. For example, a start operation is supported by the manageability endpoint of the operable collection itself as well as by each member of the operable collection. This approach is represented as follows:

Alternatively, we can develop an operation that is translated from a generic form into a resource-specific form for a member of the operable collection. Thus, the 'start' operation on an operable collection could invoke an 'initialize' operation on one member and an 'instantiate' operation on another member.

Since it may be difficult to design a general purpose distributed operation with consistent semantics for each member of an operable collection, we must consider and accommodate any resource-specific behavior of a member.

Thus, the targeted members of an operation dictate various handling methods in the processing of the distributed operation such as dealing with failures, and differing transactional semantics. Some considerations we need to address when implementing a distributed operation for an operable collection are as follow:

Targets – It is often useful to distribute an operation to a subset of members in an operable collection. Selecting the subset of members targeted by an operation can be achieved by adding a rule or a list identifying each target of an operation in its input message. Alternatively, a manageability consumer could first query the operable collection and populate a new collection with just the targeted members. The manageability consumer could then simply invoke an operation on the new operable collection containing just the targeted members. Targeting approaches such as this allow a 'pass through' type operation signature on an operable collection to continue to match the operation signature on its targeted members.

Responses – A distributed operation can return its response(s) to a manageability consumer in different ways. A distributed operation can be implemented to form a synchronous response as when all responses from all targets are collected and then returned to a manageability consumer boxcarred or summarized in a single response message to a manageability consumer. Alternatively, a distributed operation can be implemented to form an asynchronous response as when each response from each target is individually returned to a manageability consumer. If a distributed operation implements an asynchronous response, then the manageability consumer is responsible for correlating each response with its target as well as for handling any missing response(s) from a target.

Transactional semantics A distributed operation may be implemented such that no association exists between operations on its target members. For example, an operation on a target can fail without affecting other operations on this or other targets. Alternatively, a distributed operation may be implemented such that each operation on its target members is part of a single transaction. For example, if one operation on a target fails, then the entire distributed operation is rolled back for any successfully completed or outstanding operation on its targets.

Serialized operations – Some operations can be sent to every target member of an operable collection at the same time. If the targeted members of an operable collection are few, then it may be appropriate to execute the distributed operation on the targets one at a time, waiting for each operation on a target to complete before initiating another operation on a target.

An operable collection is exposed as a WS-ServiceGroup interface. For our ‘Start’ operation we want to return a response that summarizes the responses from the operation(s) on each target and that provides an overall indication for the distributed operation. Our example 'Start' operation may not complete successfully unless all members start. Our example 'Start" operation is exposed as follows:

Notice that the interface above simply uses the WS-RF ResourceProperties interfaces, the WS-RF Add and Destroy operations, plus our new ‘Start’ operation for the application startup group. If a ‘Start’ operation is expected to be supported on all members of an operable collection, then we suggest creating a content rule for this portType as follows:

Notice that if we create an operable collection as a WS-ServiceGroup, then we do not also need a normative specification. This is true since we simply rely upon a common Web services application development practice by extending WS-ServiceGroup.

The existence of a relationship between resources is considered important information for any manageability consumer. This chapter illustrates how to build relationships into the resource properties document of a manageable resource. This chapter also illustrates how a manageability consumer queries a manageable resource for its relationships and how a manageability consumer accesses information about a relationship that is itself represented by a WS-Resource.

The Relationship capability may be exposed by a WS-Resource that is not also a WSDM manageable resource. In other words, a WS-Resource exposing the Relationship capability may not also expose the MUWS Identity capability. In WSDM, a MUWS relationship is a management related concept that is important when managing a resource rather than when using the functional or business aspects of a resource. Notice that a WS-Resource exposing the Relationship capability is not also required to support the WSDM management model. Nevertheless, if a WS-Resource reporting a relationship is also a WSDM manageable resource, then the WS-Resource should include the relevant manageability capability URI among its ManageabilityCharacteristics.

The two capabilities related to relationships as defined in MUWS Part 2 are the MUWS Relationship capability discussed in section 3.2 below and the RelationshipResource capability discussed in section 3.3.2 below.

3.1 WSDM Relationships and UML Associations

The Unified Modeling Language (UML) [UML] specifies several types of relationships between model elements, including association, dependency, generalization and realization. A UML association is represented as a line connecting model elements. While the UML allows an association to connect three or more elements, the typical representation of a UML association connects just two class elements.

In MUWS, a relationship is modeled as a UML association and connects an instance of class elements as follow:

         

An instance of Class1 is designated as playing role1 in AnAssociation and similarly for an instance of Class2. A multiplicity is assigned to each class in AnAssociation. The multiplicity designates how many instances of a class may participate in an instance of AnAssociation. For example, if Class1 is Company Class2 is Person and AnAssociation is Employment, then the role of the Company is employer, and the role of the Person is employee. In our hypothetical domain, a Person can be either unemployed or employed by one company and a Company must have at least one employee up to any number. The Employment association may be represented in UML as follows:

         

The example above is typical of a relationship modeled in the UML. A specific instance of a UML association is called a link and a UML link consists of an ordered set of participants. For example, if Widgets Inc employs Mary, Joe, and Jane, then an Employment association link exists for Widgets Inc. and Mary, for Widgets Inc and Joe, and, for Widgets Inc and Jane. A link does not accommodate participant multiplicity greater than one. In other words, in a link there exists only one participant for each role.

Notice that a MUWS relationship corresponds to an association link in the UML. A MUWS relationship consists of an ordered set of participants for an association link. A UML association corresponds to a MUWS relationship type. Thus, a WS-Resource is similar to the UML classifier, and can participant in any number of MUWS relationships or MUWS relationship types.

A MUWS relationship is similar to a UML association link, since neither accommodates participant cardinality greater than one. Thus, for the above example, a MUWS relationship type, Employment, would represent the association, and a separate MUWS relationship would exist for each of the three Employment association links.

On the other hand, a difference exists in that MUWS does not recognize the distinction UML makes between an association relationship and a dependency relationship. In MUWS, a relationship between resources that might be modeled as an instance of a dependency relationship in UML would still be treated as a MUWS relationship. In this regard, WSDM closely follows the CIM in treating a dependency as an association, via the CIM_Dependency class. See section 3.3, Accessing Relationships as WS-Resources, for additional discussion of   UML Association Classes.

3.1.1 Defining a Relationship Type

As discussed above, the UML association is represented as a MUWS relationship type. In this section we define a MUWS relationship type in which our PDA or similar device can participate. For our example, we define a relationship type for expressing the association our PDA device has with a server and infrastructure necessary for an application communications gateway. We call this association the "Gateway" relationship type. We define the necessary XML element at the end of our LocalDefinitions schema document, as described in section 2.2.1 of this primer, so that we share this relationship type with server resources instead of limiting the use of this relationship type to just MyPdaDevice resources. The XML defining our Gateway relationship type appears as follows:

Note that the xs:annotation/xs:description element is not required by MUWS. However, we consider its use a good way to express the semantics associated with the Gateway relationship type.

In many management models, a relationship type is derived from a more general relationship type. For example, we could derive the Gateway relationship type from a more general relationship type, "ConnectionTypes", as follows:

Notice that the exh:ConnectionTypes element is a relationship type defined in the exh schema document. See Appendix A for a complete definitions of these relationship types.

3.2 The Relationship Capability

The MUWS Relationship capability defines one property, Relationship, and one message exchange, QueryRelationshipsByType. Nevertheless, incorporating relationships into our resource properties document introduces several highly complex structures into our object model and schema. This section shows how to revise our example schema and WSDL documents to handle these structures. A resource that does not support the MUWS Relationships capability does not include the Relationship property in its schema document and does not include the QueryRelationshipsByType message exchange in its WSDL document.

The MUWS Relationship capability is optional. A resource is not required to expose this capability in order to be WSDM compliant. Moreover, a resource exposing information on relationships need not be a participant in any exposed relationship. This behavior may be seen in a resource acting as a registry and exposing relationships among registered resources.

We need to add a reference to the MUWS Relationship property in order to support the Relationship capability. We add this reference to the schema of our resource properties document for MyPdaDevice. Since the WS-ResourceProperties specification says the order of properties in a document schema is not relevant, we simply add our new property at the end of the list of properties already present as follows:

Once support for the Relationship property is implemented, we use existing resource properties access message exchanges to retrieve values for instances of the MUWS Relationship property. In the next section, we discuss what relationship information is contained in these values.

3.2.1 Relationships in the Resource Properties Document

A resource needs to include one Relationship property in its resource properties document for each MUWS relationship in which it participates. Each relationship property is a complex element containing a name, the relationship type and a child element for each participant in the relationship. For example, for our PDA device to report its relationship with a server, the myPdaDeviceServer resource properties document would include a Relationship property instance as follows:

Notice the “exh” namespace refers to the LocalDefinitions schema as described in section 2.2.1 and the Gateway relationship type is a subtype of exh:ConnectionTypes, as defined in the LocalDefinitions schema in Appendix A.

Notice the Type element is required. However, the muws-p2-xs:Name element is optional. The Name is a human-readable designation assigned to a particular MUWS relationship type by a resource. Information about each Participant in a MUWS relationship must be provided. In MUWS, a relationship must have at least two Participant elements. If a resource is a WSDM manageable resource, then the muws-p1-xs:ManageabilityEndpointReference and muws-p1-xs:ResourceId elements must be present within the Participant element. We highly recommend that WSDM manageable resource information, especially the ResourceId element, be exposed for WSDM manageable participants, as illustrated in the above example XML. On the other hand, if a participant in a MUWS relationship is not a WSDM manageable resource, then a wsa:EndPointReference or a URL referencing the resource, should be provided within the Participant element. The Participant element facilitates the use of open content by means of an xs:any element within its schema. For further information about the use of the xs:any element in MUWS, see section 5.2., "How to tell a client where to find schema for elements used in xs:any".

A manageability provider or WS-resource reporting MUWS relationship information must include the Role each participant plays in the MUWS relationship. A role is described by a URI. A manageability consumer uses of the value of a Role element to determine how each participant behaves in the MUWS relationship.

A MUWS relationship contains a muws-p2-xs:Participant child element for each participant in a relationship. In the example above, there are two participants.

3.2.2 Querying Relationships by Type: WSDL Modifications

The MUWS Relationship capability also defines the QueryRelationshipsByType message exchange. This operation is not necessary when a manageability consumer wants to obtain all MUWS relationships for a resource. However, the QueryRelationshipsByType operation is more efficient when a manageability consumer wants to obtain all the relationships of a particular MUWS relationship type and interacts with a resource participating in many relationships of differing types. In fact, MUWS recommends a manageability consumer use the QueryRelationshipsByType operation instead of the GetResourceProperty operation for this reason. The ability for a manageability consumer to request only relationships of a given type facilitates a more efficient processing of the relationships by a manageability consumer and saves the network bandwidth and processor burden incurred when transmitting unwanted relationship information for a resource.

When we add this new operation to the WSDL description of our manageability endpoint we need to use the prefix of an XML namespace in the MUWS part 2 WSDL. Thus, we add the appropriate prefix and import statements. See section 2.2.2, "The WSDL Document" for further detail within this step.

Since the MUWS WSDL already includes a WSDL message element for our operation, we just refer to the existing message from our portType. So, in the next step we add the new operation to our portType as follows:

Finally, we add our new operation to the binding as follows:.

3.2.2.1 An Example using QueryingRelationshipsByType

A manageability consumer constructs a QueryRelationshipsByType request message containing the MUWS relationship type of interest. In our example, we want to obtain all of the relationships in which a resource participates that have a relationship type of "Gateway", as defined in section 3.1.1 above. Our request is as follows:

The response message contains a list of relationships of the specified type. If a resource does not have any relationships of the specified type, then the QueryRelationshipsByTypeResponse element contains no child element. If a resource has many relationships of the specified type, then the QueryRelationshipsByTypeResponse element contains many instances of the Relationship element. For our example, we assume a resource has only a single relationship of the specified type. Our response is as follows:

Notice the content of the response message is familiar and simply exposes the relevant Relationship property of the requested relationship type.

3.2.3 Relationship Events

A MUWS relationship can only be created or destroyed. A MUWS relationship can not be changed or modified. For example, if MyPdaDevice enters into a Gateway relationship with a new server, then our resource destroys the old Gateway relationship and creates a new one. A manageability consumer may subscribe to receive a notification on either the create event or destroy event for a MUWS relationship. For more information on Subscriptions and Notifications, see section 2.10 of this primer.

A manageability consumer subscribes to receive a notification in the event a MUWS relationship is created or deleted by using the TopicExpression/Concrete dialect as described in section 7.2, "ConcreteTopicPath Expressions", in the Web Services Topics [WS-Topics] specification. This dialect is required as these WS-Topics are subtopics of the RelationshipsCapability topic. For example, our subscription message to receive notification of a RelationshipCreated event is as follows:

When a resource issues a notification of a MUWS relationship event, the MUWS ManagementEvent structure is a required part of the Notification message. In addition, a notification of a MUWS relationship event must include the definition of the relationship instance. We simply define a MUWS relationship using the <Relationship> element present in our resource properties document as described by section 3.2.1, "Relationships in the Resource Properties Document".

As an example, we consider a scenario in which a PDA device is assigned to a new server. Let us assume a manageability consumer has a subscription with a PDA manageability endpoint to receive notifications related to any new relationships in which the PDA participates. A notification message can appear as the child of the soap:Body element. Alternatively, a notification message can appear as a child of the wsn:Notify/wsn:NotificationMessage/wsn:Message element. The form and appearance of the notification message depends upon how a manageability consumer subscribed to receive the notification. Our example notification message is as follows:

3.2.4 Relationship Metadata

The metadata for MUWS relationships should appear in the metadata document of any manageability endpoint supporting the MUWS Relationships capability and the MUWS QueryRelationshipByType message. This metadata is as follows:

See Appendix A for the complete metadata document for our example PDA manageability endpoint.

3.2.5 Guidelines for Supporting the Relationships Capability

This section of the MUWS primer offers some guidelines for supporting the MUWS Relationship Capability as discussed above. The MUWS Relationship capability is a powerful manageability tool for resource discovery, for root cause analysis and for determining the set of resources orchestrating a higher level service. The guidelines offered in this section facilitate greater manageability of resources participating in a MUWS relationship.

There is no required ordering of Participant elements contained in a MUWS relationship. A manageability consumer must not assume the first Participant element identifies the resource providing the information. Consider that a resource may report information about a MUWS relationship in which it is not a participant. For example, a distributed processing environment implements a relationship service exposing all of the MUWS relationships within the distributed processing environment. In this case, the resource providing information about MUWS relationship in the extended environment likely is not a participant in the reported relationship. Another reason is that

Some systems implement relationships such that any or all participants return the same relationship information. Also, the order of Participant elements may be identical no matter which participant provided the information on the relationship. The manageability consumer needs to examine the Role element associated with a participant, and possibly needs to examine the ResourceId element or ManageabilityEndpointReference element in determining how a resource behaves in a relationship.

The MUWS specification recommends support for the QueryResourceProperties message exchange by a manageability endpoint supporting the MUWS Relationship capability. Support for the QueryResourceProperties message is not necessary if a resource is a participant in, or knows of only a small number of relationships. However, as a distributed processing environment scales the number of relationships in which a resource participates is likely to increase. The QueryResourceProperties request allows a manageability consumer a fine-grained selection for the relationship information of interest.

Finally, a good idea for a resource participating in a MUWS relationship is to expose its ManageabilityEndpoint and ResourceId information. This helps a manageability consumer determine which participant is the resource providing information on a relationship.

3.3 Accessing Relationships as WS-Resources

As we model resources and relationships, it is often helpful to think of an association as a classifier with its own properties and operations. For example, a marriage of two persons has properties, such as the date and place of the marriage. It is awkward to consider these properties as part of either person. To address this type of situation, the UML provides an association class that represents an association as a classifier. An association class has a special connection to the line representing an association between classes as follows:

         

Now, the properties and operations pertaining to the UML association between Class1 and Class2 are modeled as part of the AnAssocation classifier.

Recall that a MUWS relationship is comparable to a link, an instance of a UML association, or relationship type. MUWS supports the modeling of a MUWS relationship as a WS-Resource. In other words, a WS-Resource may represent a MUWS relationship exposing the properties of a relationship type. For example, a WS-Resource representing the marriage relationship type may expose instance information on the date and place of a marriage ceremony and the two participants, and support operations and events relevant to this MUWS relationship type.

3.3.1 Accessing a MUWS Relationships as a WS-Resource

A manageability consumer must be able to discover the wsa:EndPointReference (EPR) for a WS-Resource representing a MUWS relationship. A manageability consumer may discover the EPR of a MUWS relationship by asking a WS-Resource participating in the MUWS relationship or by asking another resource, such as a registry providing information about MUWS relationships. If a relationship is accessible, then the WS-Resource providing information about the relationship should include an EPR for the relationship itself within the Relationship property. The schema of the MUWS Relationship property includes the <AccessEndpointReference> element for this purpose as follows:

Recall, the WS-Resource representing the relationship is not required to be a WSDM manageable resource. For more information on relationship as WS-Resource, see section 3.3.2, "Treating Relationships as Standalone Resources".

3.3.2 Treating Relationships as Standalone Resources

If a relationship is exposed as a WS-Resource, then the resource is normatively required to support the MUWS RelationshipResource capability. In most cases, this is the only capability exposed by such a resource. The MUWS RelationshipResource capability requires support for three properties in its resource properties document. These properties are Name, Type, and Participants. These properties are the same as the corresponding properties exposed by the Relationship property in the resource properties document of each participant. We see a difference in the relationship as resource since these three properties are not contained within a Relationship element as the resource knows only about the relationship it represents. Likewise, the Participants property is not contained within a Relationship element.

Suppose a management model wants the UML association between PdaDevice and PdaServer represented by an association class. Then, we would represent a MUWS relationship between MyPdaDevice and MyPdaDeviceServer as a WS-Resource. Notice we want to include the AccessEndpointReference element in the Relationship property in the resource properties document of MyPdaDevice and MyPdaDeviceServer in order to reference this MUWS relationship as a WS-Resource.

If a relationship exposed as a resource has only the standard MUWS-defined relationship properties, then the resource does not need to define a schema document since the MUWS part 2 schema contains everything necessary. So, we just define a WSDL document with the appropriate attribute on the portType as follows:

We add the operations we want to use for accessing properties of our relationship resource. At a minimum we want to use the GetResourceProperty operation.

If there are additional properties we want to expose for our relationship resource, then we must construct a resource properties document schema as well as a WSDL document. We define a WS-Resource for our GatewayRelationship example by first creating a resource properties document schema as follows:

Notice we also added two additional optional properties to our relationship resource.

The WSDL for our relationship resource follows the pattern as presented in section 2.2.2, "The WSDL Document", and should expose the GetResourceProperty operation as specified by WS-ResourceProperties. Now, a manageability consumer can request the ‘Type’ property for our relationship resource as follows:

A response from our relationship resource appears as follows::

Notice that all MUWS relationship properties are accessible via GetResourceProperty, including extra optional properties ‘Date’ and ‘Location’, as defined above. Recall that all standard access routines as defined by WS-ResourceProperties may be used by a manageability consumer to access the XML representation of a MUWS relationship as a WS-resource. If a relationship resource allows a manageability consumer to change some property, then the corresponding set operation may also be exposed. If set operations are allowed, then the corresponding relationship properties of the respective participants must be kept in synch with any changes made to the WS-Resource.

We have now built a manageable resource. In this chapter of the MUWS primer we explore how our manageable resource interacts with a manageability consumer. In particular, we will discuss how a manageability consumer:

§         Discovers an EndpointReference (EPR) for a manageable resource

§         Discovers and uses the capabilities of the resource

4.1 Discovering Resources

MUWS does not specify any specific mechanism for the discovery of a resource. However, we can offer some useful hints for a manageability consumer interested in discovering a resource.

One of the more critical and complex aspects of resource management is the discovery of resources to manage. Discovery of a resource is complex because different resources may be discovered in different ways and different management domains may use different methods of discovery. As a result, if a manageability consumer needs to support many different types of resources then it may need to support a broad variety of discovery mechanisms.

Discovery capabilities are briefly described in MUWS part 2, chapter 5, "Discovery". In this section of the MUWS primer we expand on the MUWS description and explore three general methods for the discovery of a resource as follow:

§         Using explicit resource EPRs in the configuration of a manageability consumer

§         Using a registry to expose the existence of a resource

§         Using the MUWS Relationship capability

Notice that other discovery mechanisms may be used in some management domains. However, other discovery mechanisms are not discussed in the MUWS primer.

4.1.1 Explicit Configuration

As mentioned above, one method a manageability consumer can find a resource is through configuration of the manageability consumer. This can be accomplished by providing the discovery information for a resource as an argument at application startup, through a user interface, or through a configuration file or database read at application startup. Using explicit configuration as a method of resource discovery is most useful when a small number of resources and other key components are involved. An example of another key component is a registry of resources or a root resource in a resource hierarchy, from which additional resources are discovered by a manageability consumer. However, a database of current discovery information could easily be maintained for resources with which a manageability consumer interacts.

Using explicit configuration as a resource discovery method is best as an initial bootstrap towards further resource discovery, such as accessing the relationship property of a known resource as described below in section 4.1.3, "MUWS Relationships".

4.1.2 Resource Advertisement and Registries

Advertisement is discussed above in section 2.13, "Advertising a Resource". A manageability consumer may subscribe to the creation messages of a resource factory. If the Advertising capability is supported in a Web services environment that also supports a registry of resources, then the registry can subscribe on ManagebleResourceCreation/Deletion topics to keep itself up to date. Alternatively, a registry could propagate notifications of observed events on these topics to keep other entities up to date.

A registry provides an excellent central location from which other resources may be discovered. As such, the location of a registry as a “known entity” within a system is a good initial bootstrap towards resource discovery. Registries come in many varieties. Often, a registry is designed for a specific environment or a particular management domain. While the MUWS specification does not define a registry structure, MUWS does recommend using a ServiceGroup as defined by WS-ServiceGroup to act as a registry of manageable resources within a Web services environment. The following sections discuss several forms of registry.

4.1.2.1 UDDI

A UDDI compliant registry contains information as usually exposed by a provider to a partner or a client about services offered and how to contact the provider. Information is available from a UDDI registry in a data structure called a tModel. While the tModel exposes the WSDL document and endpoint for a service, it can not expose an Endpoint Reference (EPR) for a resource. Developers using UDDI can use the existing tModel structure to identify top-level services useful towards further resource discovery. Alternatively, developers using UDDI can extend the tModel structure to contain an EPR and identity for a resource.

UDDI can be particularly useful as an initial bootstrap towards resource discovery. A UDDI registry can serve as the one configured resource for a manageability consumer. A UDDI registry can serve as a place where additional discovery mechanisms and manageable resources are exposed. However, in certain use cases a UDDI registry may be an inappropriate discovery mechanism, especially in any use case where resources are created and deleted rapidly or in any use case involving a large number of resources.

4.1.2.2 ServiceGroup

As described in MUWS part 2, section 5.2, "Discovery Using Registries", a ServiceGroup implements a Web service registry. A ServiceGroup is a resource supporting the usual WS-ResourceProperties message exchange patterns. Also, the resource properties document of a member resource may be contained within the ServiceGroup. As a result, a QueryResourceProperties message exchange may be used to find a subset of member resources in a ServiceGroup. Once a subset of members is known, it is possible for a manageability consumer to interact directly with a member as the EPR for each member resource is contained within the ServiceGroup.

4.1.2.3 Relationship Registries

A resource can be discovered by a manageability consumer inspecting the relationship property of a known resource. For more information on resource discovery using MUWS relationships, see the next section of this primer. We can create a simple registry by using a resource that supports the MUWS Relationship capability. See chapter 3, "Building Relationships", for more information about the MUWS Relationship capability. A resource acting as a registry using the MUWS Relationship capability would expose exactly one relationship for each known resource within a distributed processing environment or system. When a resource acts as a registry in this way it should also support the QueryResourceProperties operation.

4.1.3 Using The MUWS Relationship Capability

The MUWS Relationship capability was designed to expose the associations between the various resources in a distributed processing environment or system. Analyzing the information about the resources participating in a MUWS relationship is an excellent way for a manageability consumer to discover new resources. Notice that a manageability consumer using the MUWS Relationship capability in this way still needs a starting point, a first resource. Rather, this approach provides a basis for a recursive resource discovery mechanism and a means to reflect the state of resources and relationships. When using relationships as a discovery mechanism, a manageability consumer must already know an EPR for one or more initial bootstrap resources as discussed in section 4.1.1, "Explicit Configuration".

4.1.3.1 Discovering Resources from Relationships

There are several operations available to a manageability consumer interested in inspecting the MUWS relationships  of a resource. These operations are as follow:

·         GetResourceProperty

·         GetMultipleResourceProperties

·         QueryResourceProperties

·         QueryRelationshipsByType

In order for a resource to provide the manageability consumer with a mechanism for discovering any resources with which it associates, a resource must support at least one of the above operations.

We can describe an algorithm a manageability consumer can use to discover all resources associated with all known resources with pseudo-code as follows:

For each known resource {

     Request the relationship property

     For each returned MUWS relationship {

         Obtain an EPR of the other participant in the relationship

         If the EPR references a resource not already in our list {

              Add this resource to our list of known resources

              Recursively invoke this algorithm for this resource

         }

     }

}

For more information and examples of Message Exchange Patterns useful for traversing relationships, see section 4.2.2.4, "Querying and Traversing Relationships".

MUWS defines the Participant element to allow for open content. In particular, we recommend exposing a ResourceId in the Participant element of a Relationship. We consider it much easier for a manageability consumer to compare ResourceIds than it is for a manageability consumer to send a message to an EPR and then determine whether the referenced resource is a newly discovered resource or the same as a resource previously encountered.

The above discovery algorithm may find large numbers of resources. In fact, this discovery algorithm may discover resources considered outside the management domain of an application. Thus, it may be necessary to add some heuristics to prune or otherwise limit our list of known resources. Some of these heuristics are of a general nature and may apply to any application. For example, a manageability consumer might examine the Participant information to make sure a resource is of interest. Other domain or application specific heuristics may also apply. For example, a manageability consumer might check if a relationship is a certain type or may check if a resource supports a certain property or has a particular value for a certain property.

Since a MUWS relationship can reference a resource that does not implement the MUWS Identity capability, the above discovery algorithm may discover resources that are not MUWS manageable resources.

4.1.3.2 Monitoring Relationships

A manageability consumer interested in the current list of all known resources in an environment may want to subscribe to the RelationshipCreated and RelationshipDeleted Topics for each manageable resource discovered. This subscription will cause a manageability consumer to receive notifications containing either a RelationshipCreatedNotification or a RelationshipDeletedNotification element, as defined in MUWS Part 2, section 4.1.5, "Events". By taking the associated relationship and checking whether the relationship is already known, a manageability consumer can dynamically keep current its list of known resources. A notification message can appear as the child of the soap:Body element or as a child of the wsn:Notify/wsn:NotificationMessage/wsn:Message element, depending upon how a manageability consumer subscribed to receive notifications on an event topic. An example follows:

4.1.4 Summary

A manageability consumer in a scoped or constrained environment may be able to use a single approach towards resource discovery. However, most manageability consumers likely interact with different types of manageable resources within heterogeneous environments and likely use several approaches towards resource discovery.

Typically, an initial bootstrap mechanism configures a manageability consumer to know about one or more top-level resources. Next, by interacting with a top-level resource, the manageability consumer can use the relationship property as a resource discovery mechanism and locate other resources in the environment.

A more sophisticated resource discovery mechanism, like a registry based upon ServiceGroups [WS-ServiceGroup], can be implemented as the need arises.

4.2 Managing and Monitoring

This section of the MUWS primer discusses how a manageability consumer discovers the manageability capabilities of a resource. Also, this section illustrates how a manageability consumer uses manageability capabilities when interacting with a resource.

4.2.1 Discovering Manageability Capabilities

Once a resource is known to a manageability consumer, the next step is determining which manageability capabilities are supported by the resource. MUWS part 1 recommends each supported manageability capability be included as the value of an instance of the ManageabilityCapability property. A manageability consumer obtains these values by sending a GetResourceProperty message to the resource and requesting the values of the ManageabilityCapability property. An example of a SOAP request to retrieve the manageability capabilities of a resource follows:

The response to above request shows the resource supports five manageability capabilities: Identity, ManageabilityCharacteristics, CorrelatableProperties, Description, and Operational Status. Our example response follows:

If a manageability consumer knows the manageability capabilities supported by a resource, then the manageability consumer knows the features available to manage the resource. The capabilities as described in the MUWS, MOWS, and dependent specifications indicate a minimum set of properties, message exchanges, and notifications exposed by a compliant manageable resource.

4.2.2 Using Manageability Capabilities

This section discusses the possible roles played by manageability capabilities in management tasks.

4.2.2.1 Determining Resource Identity

Because manageability capabilities for a resource may be provided in part by different manageability endpoints or discovered through various and overlapping means, it is often necessary for a manageability consumer to determine if different references refer to the same resource or to different resources. In a case where the manageability for a resource is provided by multiple endpoints, simply comparing EPRs to determine if a resource is already discovered can yield an incorrect result.

The simplest approach towards determining the identity of a resource is by comparing the ResourceId of each referenced resource. The ResourceId is specified by MUWS part 1 as a mandatory property. When determining if two values of the MUWS ResourceId property are equal, a manageability consumer compares the URIs on a character by character basis. Equal values of the MUWS ResourceId property indicate the same resource. However, it is not guaranteed that two different manageability endpoints for the same managed resource will return the same ResourceId. This situation may occur if a manageability endpoint is unaware of others and does not obtain a ResourceId from the resource itself.

In a use case where different values of the MUWS ResourceId property may refer to the same resource, each manageability endpoint should also support the MUWS CorrelatableProperties capability. If the MUWS CorrelatableProperties capability is supported, then a manageability consumer should use this capability when determining the identity of a resource if the values of the ResourceId property are not equal. The MUWS CorrelatableProperties capability exposes access to a set of values for a resource that a manageability consumer can use in determining the identity of a resource. If the same resource is referenced, then the values of the correlatable properties should be equal even if the ResourceId properties are not equal. If the CorrelateableProperties capability is not supported, then a manageability consumer should treat different values of the ResourceID property as different resources.

For our example, we assume a manageability consumer determines that the values of the ResourceId property are not equal, and we assume our manageability endpoints support the MUWS CorrelatableProperties capability. Now, a manageability consumer decides to use this capability and determine if the different resource references actually reference the same resource. Next, a manageability consumer obtains the correlatable properties of a resource by sending a message to a manageability endpoint as follows:

In our example, we assume the target resource exposes two correlatable properties, MyID and MyUnitNumber. Further, we assume that the values of both MyID and MyUnityNumber are required to be equal in order to establish the identity of a resource. Also, we assume their conjunction is both necessary and sufficient to guarantee the identity of a resource. The response to our GetResourceProperty request might use the “foo” namespace prefix as defined in the resource properties document of the target resource as follows:

A manageability consumer parses this response to obtain an understanding of how to test the identity of a resource. Notice the Dialect attribute specifies how content in the <muws-p1-xs:CorrelatableProperties> element is formulated. In our case, the Property Boolean Match (pbm) dialect is sufficient, allowing a manageability consumer to perform an equality match on the values of the provided properties. Notice the <MatchAll> element tells a manageability consumer that the value from each resource for both <Match> elements foo:MyKey and foo:MyUnitNumber must compare as equal in order for a successful identity test on a resource. Notice the NegativeAssertionPossible attribute indicates that if a comparison provides a false result, then a manageability consumer is guaranteed that the tested resources are not identical.

Now that a manageability consumer knows how to proceed with a test on the identity of a resource, the next step is to send request messages to the target resources and retrieve the values for the MyKey and MyUnitNumber properties for each resource. Once responses are received, a manageability consumer tests the identity of the target resources by performing the comparison as specified above by the CorrelatableProperties property.

4.2.2.2 Obtaining Description and State Information

Upon discovering a resource, a manageability consumer may wish to obtain a description of the resource and maintain it in a log for future reference. Or, a manageability consumer may wish to display parts of a description of the discovered resource on an application console. Perhaps the application console displays a list of resources comprising a system or produces a topological display of a system and displays the caption property of a resource on its corresponding icon. The description of a resource consists of three elements: a caption, perhaps multiple descriptive statements about the resource, and a version. In our example, we assume that a manageability consumer wants to display the caption and version number on a topological display of a managed system. So, we send a message to the manageability endpoint of the target resource as follows:

We receive a response from the target resource as follows:

Now, a manageability consumer can use the value of the muws-p2-xs:Caption property, adding "Application ABC Version 1.2" with the discovered resource icon to its console display.

Once a resource is discovered, a manageability consumer may wish to obtain additional information about the resource. For on-going, real-time information, a manageability consumer can subscribe to receive notification of events on topics of interest. A manageability consumer can use subscriptions as a basis for a logging or an alerting mechanism. In any case, a manageability consumer may wish to poll for information from a resource. For example, a manageability consumer might poll resources every fifteen minutes with an explicit request for status and current state to update the moment-in-time display of the system.

If the manageability endpoint of a resource supports the MUWS OperationalStatus capability, then a manageability consumer can retrieve the current operational status of a resource. In our example, the status of each resource, its availability in particular, is maintained on a topological display of a system. This way, a console user can quickly see the current availability of a system and which of its resources are currently up or down. We retrieve the MUWS Operational status property via a GetResourceProperty message as follows:

We receive a response showing the target resource is currently Available as follows:

A manageability consumer requests the current state of a resource in a similar way. MUWS part 2 does not predefine a state model for a resource. The definition of a state model for a resource is located in the XML schema of the resource properties document for a resource. In our example, a manageability consumer sends a request for the state of the target resource, one of our PDA devices, as follows:

We receive a response showing the target resource is currently in the ServerConnected state, a sub-state of the Connected state as follows:

4.2.2.3 Configuring the Manageable Resource

A principal concern of a manageability consumer is configuring the resources it manages. MUWS part 2 defines a Configuration capability yet allows a manageable resource to specify which properties are configurable by a manageability consumer. The configurable properties of a resource are specified as modifiable in the schema of its resource properties document.

A mutable configuration property may be set by a manageability consumer via the SetResourceProperties message. In our example, we assume the target resource exposes a configurable property, TriesBeforeFailure. We set this property by sending a request as follows:

4.2.2.4 Querying and Traversing Relationships

An important aspect of managing a resource is querying and traversing the relationships in which it participates. We have already seen one example of traversing relationships for discovering new resources, see section 3.1.3.1. In this section we use as an example a manageability consumer wishing to determine the free space available on the hard-drive of a laptop. If the available space on hard-drive fails below a specified threshold then the laptop user is warned that the hard-drive is dangerously close to running out of free space.

In our example, a relationship between a laptop and its hard-drive is described by the LaptopHardDrive relationship type, a subcategory of the EquipmentConnectedService relationship type. Notice that the EquipmentConnectedService relationship type is a subcategory of the ConnectedTo relationship type.

We request the LaptopHardDrive relationship type from a laptop resource as follows:

The resource properties document for a laptop resource contains the hierarchical structure of the relationship type within the MUWS relationship <Type> child element. We receive a response to the query as follows:

Notice a manageability consumer parses the above response and finds the EndPointReference (EPR) of the resource participating in the connectedTo:service role. A manageability consumer uses this EPR and requests the Capacity and UsedSpace properties from the target resource and then determines if the hard-drive is running out of free-space. If the manageability consumer determines the free-space on the hard-drive has fallen below a threshold then a notification is issued to subscribers.

5.1 Defining a Taxonomy in WSDM

A taxonomy is frequently required for the manageability of a resource. The structure of a taxonomy is defined in the schema of a resource properties document, though parts of a taxonomy may be defined in some other document and imported into the schema.

Section 2.6, "Representation of Categorization Taxonomies in XML", in MUWS Part 2 defines the MUWS schema complex type CategoryType. MUWS extends the CategoryType to derive three general types of taxonomy as follow:

§         SituationCategoryType

§         StateType

§         RelationshipTypeType

Within the schema of MUWS Part 2, each general type of taxonomy extends from of CategoryType using a pattern as follows:

Notice CategoryType is itself a complexType and specifies a sequence of any XML element and "lax" processing. For example, the definition of StateType is as follows:

We can use a predefined category type or we can define our own taxonomy category either as an extension of the MUWS CategoryType or as an extension of a type derived from CategoryType. Our schema may define a further subtype of StateType, for example, a particular State hierarchy such as PrinterStateType, by using this same pattern as follows:

We also need to define an element of the type for taxonomy as follows:

Notice the PrinterState element carries the semantics of the PrinterStateType taxonomy. Also notice, this element may be defined as a Global Element Declaration (GED). If the element is defined as a GED, then an instance of our taxonomy can be retrieved through the GetResourceProperty operation as a query for the QName of this element. In some cases, it is desirable to define an element taking on the semantics of a taxonomy as part of a larger context. For example, the SituationCategoryType taxonomy, with a corresponding element, SituationCategory, may be defined as part of the larger context of SituationType.

When defining elements in a taxonomy we first consider how we want the taxonomy expressed in an instance of a resource properties document. Thus, we want an element defined with the semantics of our taxonomy for the parent element of our taxonomy, exposed as follows:

Notice the highest and most general element of the PrinterState hierarchy appears as the inner most element. In other words, when a manageability consumer parses the PrinterState hierarchy, the most specialized elements are seen first. This structure and organization allows a manageability consumer to stop processing a taxonomy as soon as it sees an element having known semantics.

How do we represent this hierarchy in the XML schema of our resource properties document? Notice that a taxonomy consists of a series of elements. We define each element separately and then connect the elements using the XML restriction of a taxonomy type. So, we begin with the highest level element and its restriction of taxonomy type. Recall, a taxonomy type may either be a MUWS predefined taxonomy type or be our defined taxonomy type. PrinterStateLevel1 is the inner most element of our taxonomy and appears as follows:

Since PrinterStateLevel1 is the most general element of our taxonomy, it has no children. PrinterStateLevel2 is a more specific level and has one child, the PrinterStateLevel1 element. The PrinterStateLevel2 element appears as follows:

A lower level of our taxonomy is defined with an element referencing the next higher level. In our example, the PrinterStateLevel3 element is the most specific and appears as follows:

Given an understanding of this simple pattern we can define a taxonomy of any complexity in our resource properties document.

5.1.1 Steps for Constructing a Taxonomy

A taxonomy is a category for information and we declare a taxonomy as follows:

Step 1: Declare an XML element with a QName identifying the semantics for our category:

Step 2: Declare an XML element with an XML Schema type restriction based upon the MUWS CategoryType:

Step 3: Declare the contents of the XML element. This content is either the one child element corresponding to the most general element of the category or an empty sequence, as in step 2 above. An example of an element declared with one child element appears as follows:

Notice a declared element with an empty sequence is the most general element and is the top level of a taxonomy.

5.2 Alternate Means of Accessing Manageability

The MUWS architecture provides mechanisms for accessing resource properties by exchanging messages with the manageability endpoint of a directly-addressable resource. However, a manageability endpoint may provide access to the properties of more than one resource. Thus, a manageability consumer is able to interact with one manageability endpoint and access the resource properties for a system composed of manageable resources using MUWS defined mechanisms.

One example of this approach is found in the WS-ServiceGroup specification. WS-ServiceGroup describes how to create a collection of resources. If some of the resources in a service group are manageable resources, then the manageability endpoint for the service group can also be used to access the properties of a system composed of several resources. A composed system exposes the properties of its resources, like MUWS identity, and supports the mechanisms defined by the MUWS specification. The exposed properties of a manageable resource that is part of a system may be accessed by directly addressing the resource. However, in some cases properties of a resource can also be accessed via the manageability endpoint of the service group as well.

Similarly, a manageability consumer can subscribe for notifications on a management topic supported by a service group. Subscribing on a topic supported by a service group is equivalent to subscribing on the same topic for each resource of the system as represented by the service group. Thus, MUWS facilitates the management of an individual resource or service as well as an entire system of resources.

A service group is just one of several ways to represent a system composed of individual resources. A system can expose more than the state of its resources and can provide additional metadata and information about the relationships among its resources. A resource information model such as the DMTF Common Information Model (CIM) can be used to define the representation of a system and render it as an XML document, thus making the information model of a system available through mechanisms as defined in the WS-ResourceProperties specification. The W3C Resource Description Framework (RDF) is another example of a mechanism for representing a system.

In a sense, we can think of a manageability endpoint providing access to one manageable resource as a special case of a manageability endpoint providing access to a system of resources. The special case would occur when a system is composed of only one resource.

5.3 FCAPS Discussion

FCAPS is an acronym for Faults, Configuration, Accounting, Performance, Security and is the ISO model for network management. These five categories organize a management model by various management tasks. Wihtin the context of this primer, FCAPS can be used to identify and categorize various aspects of distributed management. Fault management tasks recognize, isolate, correct and log faults occuring within a management domain. Often, a fault will cause a notification to be sent to a manageability consumer. Configuration management tasks include gathering and storing the configuration of resources and services, tracking changes made to a configuration and the configuration or provisioning of circuits. Accounting tasks gather usage statistics on users for the accounting and billing of resource usage and for resource quota enforcement. Performance management tasks collect and analyze performance data used in monitoring the health of management domain and for deriving any trends in resource usage indicating the potential for a capacity or reliability issue before it affects the performance of availability of a service or resource. Security management tasks identify and secure risks associated with the important issues of identification, authentication,  authorization,  message Integrity,  data integrity,  data confidentiality and trust.

These categories are easily mapped onto the WSDM Manageability Capabilities used to achieve the same purpose. The MUWS Metrics Manageability Capabilities can be used to support the five FCAPS management categories. Likewise, the MUWS Relationship capability is essential for gaining an understanding of the relationships among resources. The MUWS Relationship capability ensures that configuration, fault, and performance tasks can be accomplished for resources within the context of a distributed processing environment. The WSDM Event Format (WEF) provides the key mechanism supporting the correlation of events with resources for the purposes of performance, fault, and accounting management. The MUWS Configuration Manageability capability supports configuration management tasks and also supports fault and performance management for the automated correction of faults.

5.4 The Web Services Platform

This section briefly describes the features of the Web services platform required for managing resources using Web services. This section also provides some recommendations on how to support each required feature. Recommendations in this section either reference another specification used to provide the feature, identify the feature as provided by the industry in the future, or identify the feature as defined by an interim specification produced by the WSDM Technical Committee (TC) for use until such feature is available within the Web services platform. Simply, this section provides some insight on the architectural choices and rationale behind the requirements placed onto the Web services platform by the WSDM TC.

5.4.1 Initial Focus

The features discussed in the following subsections must be supported by the Web services platform to support the initial version of the MUWS specification.

5.4.1.1 Properties

A property is information we can describe and retrieve. Sometimes we can set the value of a property. A property may be exposed through a Web services interface. A schema is used to define a property and the message exchanges for retreiving and setting a value for the property.. A property declaration and its description should be introspectable at design time and at runtime. For our purpose of manageability, a property is part of an advertised manageability endpoint for a resource. A property can represent any aspect of a resource, like the configuration values of a resource, or its performance metrics.

Motivation: Many of the manageability capabilities supported by a manageable resource expose information about a resource a manageability consumer is able to retrieve and set. Such information about a resource should be modeled as a set of properties and the associated access methods allow access to its properties in ways that meet the scalability requirements of the management domain.

Recommendation: We recommend using the WS-Resource Properties specification [WS-ResouceProperties] to describe the properties of a manageable resource.

5.4.1.2 Meta Data

Meta-data is generally defined as data about data. In our context of management, meta-data is additional descriptive information about the components comprising a manageability endpoint, including its properties, operations, events, and capabilities. Meta-data can also provide descriptive information about the context, quality and condition, or other characteristics of management data. Meta-data can be introspected at design time and runtime.

Motivation: In IT management, meta-data is important for describing data in greater detail in support of the purpose of a resource providing management data. For example, meta-data may describe the limitations, purpose, context, quality, or characteristics of management data as an associated piece of that data and helps describe how the management data is related to the objectives of an IT environment. Additionally, meta-data facilitates the interoperability of manageability capabilities as provided across different manageability providers.

Recommendation: For WSDM 1.0, we recommend expressing the descriptive information about a manageability endpoint as XML elements bound to a PortType in a resource properties document. This approach satisfies the requirements of runtime and design time introspection but does not form a basis for a well understood and interoperable meta-data format.

Beyond WSDM 1.0, the desired solution involves supporting a standard metadata document format for runtime and design time introspection. We recommend the use of Qualifiers, as defined by the DMTF Common Information Model (CIM), to expose meta-data concerning a class, a property, a method, a notification or a method parameter. Then, a manageability consumer can inspect a qualifier for useful manageability meta-data in a well understood and interoperable format.

5.4.1.3 Addressing

An address or reference is a data structure used as a reference to a unique instance of a resource or service. An address is used to refer to a service acting as a manageability provider or acting as a manageable resource. The data structure for an address must contain sufficient information for a manageability consumer to locate the referenced service and to send messages to the referenced service. If a service acts as a manageability provider for several resources, then there is also a need for an address to uniquely identify a target resource as an endpoint reference (EPR) within its data structure. The data structure of an address must include a means to locate the description of a service. This allows a manageability consumer to identify messages understood by a service. Notice in this context, the terms address and reference as used have synonymous meaning.

Motivation: The management of different types of resources can be simplified by using interoperable addresses for referencing common manageability services and manageable resources in relationships, in notifications and in message exchanges.

Recommendation: We recommend using the WS-Addressing specification [WS-Addressing] as produced by the Web Services Addressing group of the W3C.

5.4.1.4 Notification

A notification provides a means to convey information from a resource to a recipient on a topic of expressed interest. In terms of Web services a notification delivers an XML message from a source to an addressable recipient. An interest in receiving notification messages on a topic must be established by the recipient, or by a third party on behalf of the recipient. When registering an interest on a topic, the address(es) of a recipient must be provided as discussed in section 5.5.1.3, "Addressing".

Motivation: A manageable resource needs to convey its management data to a manageability consumer. In certain cases, it is unreasonable for a manageability consumer to explicitly poll by periodic request for the management data of interest. In such a case, the manageability provider for a resource can convey the management data of interest to a manageability consumer as a notification of an event on a topic of interest A manageability provider needs to know which manageability consumer wants to receive notification of events for a topic and needs to know the deliverable address(es) of a manageability consumer in order to send a notification message as events occur.

Recommendation: We recommend the use of the WS-Notifications specification [WS-Notification].

5.4.1.5 Versioning

A version attribute identifies a set of supported capabilities and exposes a sequence of modifications on a component. There are two kinds of versioning, a resource version and a Web services version. The format of the former is outside the scope of this primer. Version information is useful in determining if a Web Service interface has changed since a manageability consumer last cached meta-data and schema describing the interface.

Motivation: A manageability consumer must be able to retrieve and inspect the versions available for an endpoint and the corresponding change description for each version.  In this way a manageability consumer can determine which interface as offered by a manageability provider is best suited for a particular management application.

Recommendation: WSDM addresses the issue of versioning as part of the Management of Web Services (MOWS) specification. MOWS complies with W3C recommendations on the issue of versioning and supports W3C TAG finding on Versioning. Management Using Web Services (MUWS) provides access to version information as part of the Description Capability.

5.4.1.6 Security

There are many ways to categorize information security. However, the categories in common use today are confidentiality, integrity and authentication. Additional concepts could arguably be categorized as access control, non-repudiation, availability and privacy. The security requirements placed on management data are similar to security requirements placed on any sensitive data. All manageability endpoints and many business endpoints have the same security requirements for confidentiality, integrity, and authentication, as well as access control, availability, and privacy.

Motivation: A resource must be manageable in a secure manner. The mechanisms comprising a security infrastructure should be composed and layered on top of manageability as exposed via Web services. This approach is similar to securing any other capability of a resource as exposed via Web services. For example, access to a manageability operation can be granted only to a manageability consumer presenting suitable credentials in a request message.

Recommendation: We recommend complying with the recommendations made by the OASIS WS-Security TC [WSS]. WSDM 1.0 provides a risk analysis ensuring that WS-Security composes with MUWS and identifies security risks of concern to implementers and deployers.

5.4.1.7 Registration, Discovery and Location

Registration is a method of advertising the existence of an resource. Discovery is a method of finding an existing resource. Discovery can be based on selection criteria or can be based on a name or identity of a resource. Location is a method of obtaining an address of a resource. In the Web services sense, registration, discovery and location can be represented by a set of operations and schema and implemented as a registry.

Motivation: Manageable resources must be discoverable by a manageability consumer. A manageable resource exposed via Web services can be registered, discovered and located via a Registry.

Recommendation:. We recommend using the existing Web services discovery practices as sufficient. This includes use of WS-ResourceFramework ServiceGroups along with the use of the UDDI specification for location of service groups, resource registries, and critical resources.

5.4.2 Future Focus

The section of the MUWS primer discusses what support from the Web services platform may be required in future versions of WSDM.

5.4.2.1 Policy

A Policy is a course of action, guiding principle, or procedure considered expedient, prudent, or advantageous for a given condition or event. It describes a broad range of service requirements, preferences, and capabilities. There are two kinds of policy that govern management of a manageable resource. A policy set can describe how a manageability consumer and a manageable resource interact using the functional interfaces of a resource, for example a policy describing the privacy of functional data. Alternatively, a policy set can describe how a manageability consumer places operational requirements on a manageable resource, for example a service level agreement.

Motivation: There are various policies that can be placed on a manageable resource including authentication, access control, privacy, non-repudiation, service level agreement, quality of service, routing, content inspection, and auditing. MUWS must leverage existing Web services specifications and technologies when applying policies to a manageable resource. MUWS should endorse a list of applicable specifications and technologies, and should specify compatibility and interoperability requirements.

Recommendation: None at this time.

5.4.2.2 Name Resolution

For the purposes of manageability, a name resolution service is required that accepts a name identifier (URI) of a resource and returns an address or reference for a manageability endpoint of the resource. A name resolution service should provide sufficient information for a manageability consumer to interact with a manageability endpoint. Notice that a name resolution service may be used to resolve a name to an endpoint reference in application domains unrelated to management as well, for example in support of Web services discovery.

Motivation: A name resolution service is necessary for management using web services because resources and manageability providers have identifiers as defined with existing instrumentation and technologies. Thus, it is necessary to derive an endpoint reference from a resource identifier so that a manageability consumer can interact with a resource through its manageability interface(s).

Recommendation: None at this time.

5.4.2.3 Transaction

A transaction is a “unit of work”, a serailizable set of actions invoked against a resource. The same unit of work can be applied to multiple resources. As a transaction, a unit of work must be executed once and only once, even if network transmission failures occur and a request is received multiple times. One of three outcomes will result from the execution of a transaction as follow:

·         All actions against all resources succeed

·         One or more actions fail. All actions against all resources are rolled back. If roll back is not possible or not supported, then affected resources should be reconfigured to a known operational, compensatory state

·        One or more actions may fail and the resources are left as affected by the actions.

Motivation: The grouping of actions as a transaction having a consistent behavior when executed against resources is highly valuable for the management of distributed processing environments. A transaction allows a manageability consumer to execute a series of actions or operations as a single “unit of work”, while preserving the integrity of resource(s) affected.

 Recommendation: None at this time.

5.4.2.4 Flow

Flow, more often called workflow or workflow management, is a term used to describe the management of business processes with information technology. By defining, analyzing, and categorizing the  resources and operations or an organization, workflow management systems ensure the right information reaches the right person or computer application at the right time. Business process management (BPM) workflow or execution languages support the composition of services into more complex systems that may in turn be exposed as a Web service. Description of workflow coordination includes constructs for identify business partners, for message correlation, for fault detection and compensating activities, and for parallel and serial execution of services.

Motivation: Web services orchestration languages may be useful tools allowing a manageability consumer to take more complex and meaningful action as a result of observations. A manageability endpoint may need to be defined for a business process engine to monitor and control flows and composite Web services that might expose certain information including the sessions and state of a process and subordinate resources,.

Recommendation: None at this time.

5.4.2.5 Negotiation

Negotiation is the process by which two services dynamically negotiate the terms of a contract. A contract is a document that represents a set of objectives and resources initiating or participating in the contract.

Motivation: Resources in a distributed processing environment interact with each other and interact with management services and manageability consumers. It is important for a resource to understand what it can expect from other resources in such interactions and to understand the various interactions enabling a resource to better describe its own level of performance, as well as how information is exchanged between the components of a distributed service in a federated deployment.

Recommendation: None at this time.

[MUWS Part 1]                   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

 

[MUWS Part 2]                   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/

 

[UML]                                 http://www.omg.org/technology/documents/formal/uml.htm

 

[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-BaseNotification]        Steve Graham, et al., Web Services Base Notification 1.2      (WS-BaseNotification), OASIS Working Draft, June 2004, http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-03.pdf

 

[WS-BrokeredNotification] Dave Chappell, et al., Web Services Brokered Notification 1.2 (WS-BrokeredNotification). OASIS Working Draft, July 2004l http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BrokeredNotification-1.2-draft-01.pdf

 

[WS-Notification]                Steve Graham, et al., Web Services Base Notification 1.2      (WS-BaseNotification), OASIS Working Draft, June 2004, http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-03.pdf

                                          Dave Chappell, et al., Web Services Brokered Notification 1.2 (WS-BrokeredNotification). OASIS Working Draft, July 2004l http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BrokeredNotification-1.2-draft-01.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

 

[WS-RMD]                          Steve Graham, et al., Web Services Resource Metadata 1.0 (WS-ResourceMetadataDescriptor), OASIS Working Draft, October 2004, http://www.oasis-open.org/committees/download.php/9758/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.PDF

 

[WS-ServiceGroup]            Tom Maguire, et al., Web Services Service Group 1.2 (WS-ServiceGroup), OASIS Working Draft, June 2004, http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ServiceGroup-1.2-draft-02.pdf

 

[WS-Topics]                       William Vambenepe, Web Services Topics 1.2 (WS-Topics), OASIS Working Draft, Jully 2004, http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.pdf

 

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

 

[WSS]                                Anthony Nadalin, et al., Web Services Security: SOAP Message Security 1.0 (WS-Security 2004), March 2004, OASIS Standard, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

 

[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

 

XML schema for the MyPdaDevice manageability endpoint exposing all MUWS capabilities.

The special definitions required by the PDA example are defined in the following schema:.

An example of a PDA resource properties document, as developed in this primer, is:

WSDL document for MyPdaDevice manageability endpoint.

The following TopicSpace document is defined:

The following metadata document describes the metadata for the properties and operations of the PDA device:

Finally, the following documents are required to support Relationships as resources:

The following represents the XML Schema of the resource properties document of the relationship between the PDA device and its server (GatewayRelationship is not a WSDM manageable resource, therefore, it does not require the MUWS ResourceID property):

The WSDL for this WS-Resource is as follows:

The following people made contributions to the WSDM MUWS Primer Version 1.0: Vaughn Bullard, Fred Carter, Zulah Eckert, Mark Ellison, Heather Kreger, Frederico Maciel, Bryan Murray, Richard Nikula, Thomas Studwell, Kirk Wilson, Zhili Zhang with special thanks to Bryan Murray, Kirk Wilson, 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.

Rev	Date	By Whom	What
CD	2006-02-24	Kirk Wilson	Title changes
wd-24	2006-01-29	Kirk Wilson, Mark Ellison	Final readability edits Added references in text; completed Reference section Added Acknowledgements section
wd-23	2005-12-21	Kirk Wilson, Mark Ellison	Edit XML in Appendix A Readability edits (section 2)
wd-22	2005-11-28	Kirk Wilson, Mark Elison	Continuation of wd-21. Rewrite Metric examples Example code simplication
wd-21	2005-11-10	Kirk Wilson, Mark Ellison	Editorial corrections; result of F2F Apply Mark Ellision’s edits
wd-20	2005-10-27	Kirk Wilson	Make Relationships a separate major section. Table of contents to show 5 levels
wd-19	2005-10-19	Kirk Wilson	Continue verification of example XML Transfer full RPDoc to Appendix A; show only snippets in text for readability Reorganize sections of Chapter 2
wd-18	2005-09-29	Kirk Wilson, Mark Ellison	Move MOWS chapters to a separate Primer. Add “MUWS” to Primer title Include Mark Ellison’s edits on sections 2.1 through 2.7. Verified consistency of example XML Standardized namespace prefixes, spacing and styles
wd-17	2005-09-08	Bryan Murray	No changes, only accepting all updates
wd-16	2005-09-08	Bryan Murray, Heather Kreger, Kirk Wilson	Added OperableCollections, updates in metadata section, XML example consistency, add more XML in appendix, use consistent prefix for pda and pdaw namespaces
wd-15	2005-09-07	Heather Kreger, Richard Nicula, Bryan Murray	Content for metadata section, updates in Metrics section, XML formatting and consistent examples
wd-14	2005-09-05	Bryan Murray, Richard Nicula, Fred Carter, Kirk Wilson	Moved adding resource-specific properties and operations to before extending a capability, added Metrics section content, updates in sections 4 and 5, updates in section 6.5, work on consistency in section 2, remove some references to spec features newer than WSDM 1.0, format some XML
wd-13	2005-09-02	Kirk Wilson, Heather Kreger, Bryan Murray	Updates to section 2.12, update section 2.6 to extend Description, starting text for Metrics section, add paragraph to Notification section, some XML in Extending Capability section, tweaks throughout based on suggestions from others
wd-12	2005-08-30	Bryan Murray	Incorporate review of section 3, formatting changes throughout
wd-11	2005-08-26	Bryan Murray, Mark Ellison, Kirk Wilson, Heather Kreger	Modified sections as homework to people at the f2f, critical review of section 1, updates to Relationships
wd-10	2005-08-22	Bryan Murray	Changes from f2f
wd-09	2005-08-19	Bryan Murray, Kirk Wilson, Heather Kreger	Added content to many sections
wd-08	2005-07-20	Kirk Wilson	Sections 1, 3, 5
wd-07	2005-07-26	Bryan Murray	Updates from June 2005 f2f. Add Advertisement section.
wd-06	2005-06-29	Bryan Murray, Winston Bumpus, Kirk Wilson, Richard Landau	Formatting, FCAPS, section 4, introduction
wd-05	2005-05-04	Zhili Zhang	Add section 2.4 “Adding Property Access Operations”. Modify WSDL document in Appendix A.
wd-04	2005-04-27	Bryan Murray	Changes discussed during April f2f. Added text to Description section.
wd-03	2005-02-28	Bryan Murray	Outline revised based on Jan 2005 face-to-face, some section 2 content added
wd-02	2005-01-17	Bryan Murray	Revised outline to incrementally add capabilities
wd-01	2004-09-30	Bryan Murray	Initial version

 

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.

Copyright  © OASIS Open 2004-2005. All Rights Reserved.

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.