Making SOA Real: Messaging Standards

Another aspect of the Service Communication part of our services platform are the messaging standards. These include both the envelope standards used for encapsulating messages as well as the message headers we use.

Envelope Standard
This envelope standard defines the XML schema used to represent messages. Rather than create a new standard the CI-SOA will use the Simple Object Access Protocol (SOAP) 1.1 standard envelope defined at http://www.w3.org/TR/2000/NOTE-soap-20000508/. As an example a request message looks as follows:


<soap:Envelope
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
 soap:encodingStyle=
   "http://schemas.xmlsoap.org/soap/encoding/"/>
   <soap:Header>
       <t:Transaction>5</t:Transaction>
   </soap:Header>
   <soap:Body>
       <m:GetLastTradePrice xmlns:m="Some-URI">
           <symbol>DEF</symbol>
       </m:GetLastTradePrice>
   </soap:Body>
</soap:Envelope>

This standard is intended to be used each time a service provider exchanges a message with a service consumer regardless of the binding used to call the service. For example, the same envelope will be used when invoking services over HTTP or MSMQ. As a result, our service agent framework builds SOAP v1.1 envelopes when services are invoked.

Further, developers use document style encoding (as opposed to RPC-style encoding) with XML Schema (XSD) when possible since doing so makes it possible to support arbitrarily complex types in XML messages. The .NET Framework supports document style encoding by default.

The reason the SOAP 1.1 standard is being used rather than SOAP 1.2 is that SOAP 1.1 is supported natively in the .NET Framework v1.1.

Header Standard
This header standard defines the XML schema used to add informational content to the Header element of the envelope. This information is useful for service management, routing, and security.

The standard includes two parts. The first is the WS-Addressing schema found at http://schemas.xmlsoap.org/ws/2004/08/addressing/. Elements in this schema are used for the following purposes.

Element Usage

MessageID (Required)- A GUID that uniquely identifies this message. Useful for logging and duplicate message handling

To (Required) The physical address the message is being sent to. Useful for routing. A URL for HTTP requests or a direct format name for a queue in the form of a URN, e.g. urn:DIRECT=OS:compassion.com\PUBLIC\MyQueue;JOURNAL

From (Required) The service or application that created the message. Typically uses only the Address element formatted as a URN to identify the creator of the message. Useful for logging.

Action (Required) The soapAction for the operation being invoked

ReplyTo (Optional) Contains an address used to send a response to. This can take the form of a URL for HTTP or a direct format queue name in the form of a URN. Optionally, this element may include reference properties if additional information is required for a particular endpoint. If not specified the reply is sent to the URI from which the original was sent. Services may also use this element in order to send delayed responses to a particular location. For example, the immediate response to the message may include an acknowledgement while the eventual complete response is sent to the ReplyTo address

RelatesTo (Optional) Populated in a response message from the request-response message exchange. Contains the MessageID of the original request message

The second schema is the http://schemas.compassion.com/common/headers/2005-04-05 schema that defines elements used within the SOAP Header element as well as the From element of WS-Addressing. The definition of the headers schema is as follows:


<?xml version="1.0" encoding="utf-8" ?>
<xs:schema id="CIHeaders" 
targetNamespace=
 "http://schemas.compassion.org/common/headers/2005-04-05"
 elementFormDefault="qualified"
 xmlns:ch=
 "http://schemas.compassion.com/common/headers/2005-04-05"
 xmlns:xs="http://www.w3.org/2001/XMLSchema">
 <xs:element name="MesssageStreamID" type="xs:anyURI"> 
      </xs:element>
 <xs:element name="CreatorIdentity" 
   type="xs:string"></xs:element>
 <xs:element name="DateTimeStamp" 
   type="xs:dateTime"></xs:element>
 <xs:element name="ProcessID" 
   type="xs:anyURI"></xs:element>
 <xs:element name="Culture" 
   type="xs:string"></xs:element>
</xs:schema>

The usage of the elements is as follows:

Element Usage

MesssageStreamID (Required) A GUID that identifier a unique sequence of messages that flow through the SOA. Used for correlating messages and for logging purposes. If the creator of the message does not have a MessageStreamID in hand from a previous message, it should create one and place it in the Header.

CreatorIdentity (Required) The windows account representing the creator of the message. Useful for logging and to authorize requests using the trusted subsystem model

DateTimeStamp (Required) Identifies in Coordinated Universal Time (UTC) when the message was created by the service consumer or provider. Useful for logging

ProcessID (Optional) A GUID that identifies a process. Typically populated by process services. If a service receives a ProcessID it should include it in subsequent messages

Culture (Optional) The culture setting for the client specifying the formats of date time, currency, and numeric data that follows RFC 1766 derived from ISO 639-1 and ISO 3166, e.g. US English="en-US"

UICulture (Optional) The culture setting for the client specifying the language to use that follows RFC 1766 derived from ISO 639-1 and ISO 3166, e.g. US English="en-US"

In the future we'll likely also add a PartnerCountryCode element that identifies the Compassion partner country from which the request originated. This will allow services to take different actions (for example processing different business rules) when the requests come from different countries.

Examples
The following is an example request message that employs the standards discussed in this document:


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:ch=
"http://schemas.compassion.com/common/headers/2005-04-05" 
 xmlns:wsa=
"http://schemas.xmlsoap.org/ws/2004/08/addressing">    
  <soap:Header>
   <ch:MessageStreamID>uuid:bbbb-cccc-dddd-eeee
   </ch:MessageStreamID> 
   <ch:DateTimeStamp>2005-04-05:T18:00:00
   </ch:DateTimeStamp> 
   <ch:CreatorIdentity>ci/dfox</ch:CreatorIdentity> 
   <ch:Culture>en-US</ch:Culture> 
   <ch:UICulture>en-US</ch:UICulture>
   <wsa:MessageID>uuid:aaaa-cccc-dddd-eeee
   </wsa:MessageID> 
   <wsa:To>http://compassion.com/DemoService.asmx
   </wsa:To>
   <wsa:Action>http://compassion.com/DemoServiceURI
   </wsa:Action> 
   <wsa:From>
     <wsa:Address>urn:CompassionWeb</wsa:Address>
   </wsa:From>
  </soap:Header>
  <soap:Body>
    <HelloWorld 
     xmlns="http://compassion.com/DemoServiceURI" />
  </soap:Body>
</soap:Envelope>

Note that the MessageStreamID is created by the service consumer since this is the first message in the stream. The CreatorIdentity is the Windows account of the creator of the message and the culture is the culture setting on the client machine making the request. In this case the message will pass over HTTP and so the To element contains the .asmx address and the Action element the soapAction from the WSDL contract. The From element contains a URN that identifies the application that created the message. Since no ReplyTo element has been provided the reply if any will be sent to the URI from the which the message was received or that defined by the WSDL for the service.

The reply to the above message would look as follows:


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:ch=
 "http://schemas.compassion.com/common/headers/2005-04-05" 
 xmlns:wsa=
 "http://schemas.xmlsoap.org/ws/2004/08/addressing">    
  <soap:Header>
 <ch:MessageStreamID>uuid:bbbb-cccc-dddd-eeee
 </ch:MessageStreamID> 
 <ch:DateTimeStamp>2005-04-05:T18:02:00
 </ch:DateTimeStamp> 
 <ch:CreatorIdentity>ci/serviceAccount
 </ch:CreatorIdentity> 
 <ch:Culture>en-US</ch:Culture>
 <ch:UICulture>en-US</ch:UICulture>
 <wsa:MessageID>uuid:gggg-cccc-dddd-eeee
 </wsa:MessageID> 
 <wsa:To>urn:CompassionWeb</wsa:To>
 <wsa:Action>urn:CompassionWeb/ResponseMessage
 </wsa:Action>  
 <wsa:From>
  <wsa:Address>http://compassion.com/DemoServiceURI
  </wsa:Address>
 </wsa:From>
 <wsa:RelatesTo>uuid:aaaa-cccc-dddd-eeee
 </wsa:RelatesTo>
   </soap:Header>
   <soap:Body>
    <HelloWorldResponse 
      xmlns="http://compassion.com/DemoServiceURI" />
   </soap:Body>
</soap:Envelope>

Here the MessageStreamID is copied from the request message and new DateTimeStamp and MessageID are created. The CreatorIdentity is now the account under which the service is executing. The To element contains the URN of the service consumer from the request message and the Action element includes an identifier that identifies the type of message being returned. The From element contains the URI of the service that returned the result and the RelatesTo element contains the MesssageID of the request message.

In the second example that follows the service consumer includes a ReplyTo element that alerts the service provider as to where the response should be sent. In this case it is an MSMQ queue. The request queue is also specified in the To element. Note that the Action element still identifies the operation being invoked.


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:ch=
 "http://schemas.compassion.com/common/headers/2005-04-05" 
 xmlns:wsa=
 "http://schemas.xmlsoap.org/ws/2004/08/addressing">    
 <soap:Header>
 <ch:MessageStreamID>uuid:bbbb-cccc-dddd-eeee
 </ch:MessageStreamID> 
 <ch:DateTimeStamp>2005-04-05:T18:00:00</ch:DateTimeStamp> 
 <ch:CreatorIdentity>ci/dfox</ch:CreatorIdentity>
 <wsa:MessageID>uuid:aaaa-cccc-dddd-eeee</wsa:MessageID>
 <wsa:To>urn:DIRECT=OS:compassion.com\PUBLIC\RequestQ
 </wsa:To>
 <wsa:Action>http://compassion.com/DemoServiceURI
 </wsa:Action>         
 <wsa:ReplyTo>              
   <wsa:Address>
     urn:DIRECT=OS:compassion.com\PUBLIC\ResponseQ        
  </wsa:Address>
 </wsa:ReplyTo>
 <wsa:From>
  <wsa:Address>urn:CompassionWeb</wsa:Address>
 </wsa:From>
   </soap:Header>
  <soap:Body>
    <HelloWorld 
     xmlns="http://compassion.com/DemoServiceURI" />
  </soap:Body>
</soap:Envelope>

Making SOA Real

Friday, October 07, 2005

Messaging Standards

1 Comments:

About Me