3.7.2 ebXML SOAP Extensions

ebXML now adds elements to the SOAP Header and SOAP Body elements. The SOAP Header gets the following elements: MessageHeader, TraceHeaderList, ErrorList, Signature, Acknowledgment and Via. The SOAP Body gets these elements: Manifest, StatusRequest, StatusRespone, DeliveryReceipt. These XML elements are listed here.

In the SOAP Header are:

• MessageHeader
  The MessageHeader element goes into the SOAP Header element and has the following child elements: From, To, CPAId, ConversationId, Service, Action, MessageData, QualityOfServiceInfo, SequenceNumber, Description. The MessageHeader element has a further two attributes: mustUnderstand and Version. This element plays an important role. The child elements of the MessageHeader will be described next.

  The elements often have further child elements. It is worth noting that some of the elements are introduced to realise the functionality of security, error handling, reliable messaging and might be confusing at the moment. It is also worth pointing out, that some elements are related to other elements, e.g. if one element is used another element must be used. A * indicates if the element is mandatory or not.

  • From and To *
    These two elements seem clear. They define the sender of the message and the receiver of the message. This element has the PartyId which can contain an internationally known identifier, like a DUNS number or a simple web site address.
  • CPAId *
    This element is also quite obvious. The element references the CPA of the two trading partners.
  • ConversationId *
    This element represents a unique ID for the current conversation between two trading partners. The initiating MSH creates this ID and from that moment this ID will be used in the proceeding messages.
  • Service *
    The Service element relates back to the Business Process Specification, where authorised roles within a business process are used. The service element names the activity of a party for this message. For example a service could be: ``SupplierOrderProcessing''.
  • Action *
    This element identifies a process within the Service. This could be a ``NewOrder'' or Acknowledgment of reliable messaging purpose.
  • Messagedata
    This element has further child elements: MessageId, Timestamp, RefToMessageId, TimeToLive.
    • MessageId
      It is obvious that each Message has its own identification for further referencing.
    • Timestamp
      It is also obviously the Timestamp when the message was created.
    • RefToMessageId
      If the message is an Acknowledge Message (used for reliable messaging) this element references a previous message by its ID.
    • TimeToLive
      This element is used for the functionality of reliable messaging and sets a time frame for the delivery of the message.
  • QualityOfServiceInfo
    This element deals with reliable messaging. The QualityOfServiceInfo element has three child elements: deliverySemantics, messageOrderSemantics and deliveryReceiptRequested. The deliverSemantics has an example value of OnceAndOnlyOnce which indicates the importance of this element. Chapter 3.7.4 has more details of how reliable messaging is achieved within ebXML.
  • SequenceNumber (* when used with QualityOfServiceInfo)
    This element ensures that the order of messages is recognised.
  • Description
    This is a simple human readable description of the message and is optional.
  Here is a sample Header.

  <eb:MessageHeader id=''...'' eb:version=''1.0'' SOAP-ENV:mustUnderstand=''1''>
          <eb:From>
                  <eb:PartyId>uri:example.com</eb:PartyId>
          </eb:From>
          <eb:To eb:type=''someType''>QRS543</eb:To>
          <eb:CPAid>http://www.ebxml.org/cpa/112345<eb:CPAid>
          <eb:ConversationId>934523405</eb:ConversationId>
          <eb:Service eb:type=''myservicetype''>QuoteToCollect</eb:Service>
          <eb:Action>NewPurchaseOrder</eb:Action>
          <eb:MessageData>
                  <eb:MessageId>mid:UUID-2</eb:MessageId>
                  <eb:Timestamp>2001-12-06ST12:39:05</eb:Timestamp>
                  <eb:RefToMessageId>mid:UUID-1</eb:RefToMessageId>
          </eb:MessageData>
          <eb:QualityOfServiceInfo
                  eb:deliverySemantics=''OnceAndOnlyOnce''
                  eb:deliveryReceptRequested=''Signed''/>
  </eb:MessageHeader>
  

  More elements in the SOAP Header:

• TraceHeaderList
  The TraceHeaderList element consists of one or more TraceHeaders elements. If a message is transfered to a remote ebXML MSH via multiple MSH, each MSH adds a TraceHeader to the TraceHeaderList. It is typically used in a multi-hop scenario.

• ErrorList
  The ErrorList element has one or more Error elements and indicates that the message referenced by RefToMessageId has an error. The ErrorList is used to indicate errors. Check 3.7.5 for more details.

• Signature
  There can be zero or more Signature elements which are digital signatures. See 3.7.6 for more on digital signatures.

• Acknowledgment
  The Acknowledgment element is set when the purpose of the message is to acknowledge of a received message. The ID of the received message is put into the RefToMessageId of the Acknowledgment element.

• Via
  The Via element indicates the way a message goes from point A to point B. The Via element has several child elements or attributes: syncReply, reliableMessagingMethod, ackRequsted, CPAId, Service and Action.

In the SOAP Body element are:

• Manifest
  The Manifest element is a very important element. The Manifest element has one or more Reference elements. As mentioned above an ebXML Message has a Header Container and zero or more Payload Container. Each Reference element references one payload in the Payload Container. The Reference element itself has a Schema element which can link to the schema of the referenced payload. The referencing is done via xlinks (see 2.8.2 for some information on xlink).

• StatusRequest
  The StatusRequest element is used to request status of a message, referenced by the RefToMessageId element of the StatusReqeust element.

• StatusResponse
  The StatusResponse element is the return message to a StatusRequest message. This element has child elements and attributes: RefToMessageId, TimeStamp, version, messageStatus and an id. The MessageStatus can be: UnAuthorized, NotRecognized or Received.

• DeliveryReceipt
  The DeliveryReceipt element is used to indicate, that a previous message (referenced by RefToMessageId) was received.