Skip to content

Mapping ZMF Web Services to XML Services

ChangeMan ZMF Web Services tag names are not identical to ZMF XML Services tag names, but they do map to XML Services tag names in a systematic way.

Service Tag Names

The XML Services <service/>, <scope/>, and <message/> tags are general-purpose tags, each of which includes a name attribute specifying the ZMF functionality desired. The three tags must be used in the correct combination to specify a function, and an eightbyte length restriction on the value of the name attribute leads to error-prone abbreviations such as name="CMPONENT" for certain services.

In contrast, the Web Services API uses a single named service tag, such as <newPackage/> or <checkinComponent/>, to fully identify the functionality desired in a request. Each top-level service name maps to one and only one XML Services service.scope.message triplet.

Within the service tag, request tags are always named <request>. Reply messages, however, can take one of two forms, depending on whether they are standalone host status messages or if they also return data from the host. Reply messages that return only host status information are always called <response>. Reply messages that return data in addition to host status information have a different structure and take names specific to each service.

Within each request or reply tag are a number of parameter tags specific to the service. The names of these parameter tags are identical to their XML Services counterparts. Data types, allowed values, and dependencies are also identical to those in XML Services. Users are referred to the ChangeMan ZMF XML Services User’s Guide for parameter tag names and allowed values. That information is not duplicated in this document.

Request Messages

ZMF Web Services request messages take the general form:

<serviceTag>
   <request>
      <parameterTag1/>
      <parameterTag2/>
             .
             .
             .
      <parameterTagn/>
   </request>
</serviceTag>

where:

serviceTag is a Web Services-specific tag name that maps to a specific XML Services service/scope/method tag triplet and which varies with the ZMF service requested

request is the literal tag name of the request method

parameterTag takes the same name and values as the corresponding XML Services parameter tag

Reply Messages

ZMF Web Services reply messages take one of two general forms, depending on whether or not data is retrieved from the host and returned to the client as part of the reply.

Standard <response> Message

The simplest reply format contains no returned data, but only an acknowledgement of host status as a result of the requested action. The general form of a simple reply is:

<serviceTag>
   <response>
      <statusMessage>Some message</statusMessage>
      <statusReturnCode>nn</statusReturnCode>
      <statusReasonCode>nnnn<statusReasonCode>
   </response>
</serviceTag>

where:

serviceTag is a Web Services-specific tag name that maps to a specific XML Services service/scope/method tag triplet and which varies with the ZMF service requested

response is the literal tag name of the response method

nn and nnnn are numeric values returned by the host

Replies With Host Data

Reply messages that return data include the <response> tag above as the final element of a more complex reply. The general form of a complex reply is:

<serviceTag>
   <serviceTagResults>
      <parameterTag1/>
      <parameterTag2/>
      <parameterTagn/>
         <response>
         <statusMessage>Some message</statusMessage>
         <statusReturnCode>nn</statusReturnCode>
         <statusReasonCode>nnnn<statusReasonCode>
      </response>
   <serviceTagResults>
</serviceTag>

where:

serviceTag maps to a specific XML Services service/scope/method tag triplet and varies with the ZMF service requested

serviceTagResults is the name of the response method, where the literal suffix Results is appended to the serviceTag name

parameterTag takes the same name and values as the corresponding XML Services parameter tag

response is the literal name of the standard complex tag used to return the host status resulting from the request