OASIS ebXML Messaging Services Version 3.0: Part 1, Core Features

Committee Specification 02, 12 July 2007

Document Identifier:

ebms_core-3.0-spec-cs-02

This Version:

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/cs02/ebms_core-3.0-spec-cs-02.pdf

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/cs02/ebms_core-3.0-spec-cs-02.html

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/cs02/ebms_core-3.0-spec-cs-02.odt

Previous Version:

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/cd06/ebms_core-3.0-spec-cd-06.pdf

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/cd06/ebms_core-3.0-spec-cd-06.html

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/cd06/ebms_core-3.0-spec-cd-06.odt

Latest Version:

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms_core-3.0-spec.pdf

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms_core-3.0-spec.html

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms_core-3.0-spec.odt

Technical Committee:

OASIS ebXML Messaging Services TC

Chair:

Ian Jones, British Telecommunications plc <ian.c.jones@bt.com>

Editor:

Pete Wenzel, Sun Microsystems <pete.wenzel@sun.com>

Related Work:

This specification is related to:

• ebXML Message Services 2.0

• SOAP 1.1, 1.2

• Web Services Security: SOAP Message Security 1,0, 1.1

• WS-Reliability 1.1

• WS-ReliableMessaging 1.1

Declared XML Namespace:

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

Abstract:

This specification defines a communications-protocol neutral method for exchanging electronic business messages. It defines specific Web Services-based enveloping constructs supporting reliable, secure delivery of business information. Furthermore, the specification defines a flexible enveloping technique, permitting messages to contain payloads of any format type. This versatility ensures legacy electronic business systems employing traditional syntaxes (i.e. UN/EDIFACT, ASC X12, or HL7) can leverage the advantages of the ebXML infrastructure along with users of emerging technologies.

Status:

This document was last revised or approved by the TC on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.

Technical Committee members should send comments on this specification to the
ebxml-msg@lists.oasis-open.org list. Others should use the comment form at
http://www.oasis-open.org/committees/comments/form.php?wg_abbrev=ebxml-msg.

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 OASIS ebXML Messaging Services TC web page (http://www.oasis-open.org/committees/ebxml-msg/ipr.php).

The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/ebxml-msg/.

Notices

Copyright © OASIS^® 1993–2007. All Rights Reserved. OASIS trademark, IPR and other policies apply.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

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 section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, 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 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

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' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on 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 OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The names "OASIS", "ebMXL", "OASIS ebXML Messaging Services", "ebMS" are trademarks of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.

Table of Contents

Table of Figures

1. Introduction

This specification describes a communication-protocol neutral method for exchanging electronic business messages. It defines specific enveloping constructs supporting reliable, secure delivery of business information. Furthermore, the specification defines a flexible enveloping technique, permitting messages to contain payloads of any format type. This versatility ensures that legacy electronic business systems employing traditional syntaxes (i.e. UN/EDIFACT, ASC X12, or HL7) can leverage the advantages of the ebXML infrastructure along with users of emerging technologies.

1. Background and Objectives

The prime objective of the ebXML Messaging Service (ebMS) is to facilitate the exchange of electronic business messages within an XML framework that leverages common Internet standards, without making any assumption on the integration and consumption model these messages will follow on the back-end. These messages may be consumed in different ways that are out of scope of this specification: they may bind to a legacy application, to a service, be queued, enter a message workflow process, be expected by an already-running business process, be batched for delayed processing, be routed over an Enterprise Service Bus before reaching their consumer application, or be dispatched based on header data or payload data, etc.

It is becoming critical for broad adoption among all partners – large or small - of a supply-chain, to handle differences in message flow capacity, intermittent connectivity, lack of static IP addresses or firewall restrictions. Such new capabilities played an important role in the motivation that led to ebMS 3.0, along with the need to integrate and profile the emerging SOAP-based QoS-supporting standards. The message header profiling that provided, in ebMS 2.0, a standard business-level header, has also been extended to better address the diversity of back-end binding models, as well as the emerging trend in business activity monitoring, the eBusiness side of which a message handler should be able to support.

The ebXML messaging framework is not a restrictive one: business messages, identified as the 'payloads' of ebXML messages, are not limited to XML documents. Traditional EDI formats may also be transported by ebMS. These payloads can take any digital form–XML, ASC X12, HL7, AIAG E5, database tables, binary image files, etc. Multiple payloads, possibly of different MIME types, can be transported in a single ebMS message. An objective of ebXML Messaging protocol is to be capable of being carried over any available transfer protocol. This version of the specification provides bindings to HTTP and SMTP, but other protocols to which SOAP may bind can also be used. The choice of an XML framework rather reflects confidence in a growing XML-based Web infrastructure and development tools infrastructure, the components of which can be leveraged and reused by developers.

2. Scope

The ebXML infrastructure is composed of several independent, but related, components. Some references and bindings to other ebXML specifications in this document should be interpreted as aids to integration, rather than as a requirement to integrate or to use in combination. For example, ebMS may refer to the [ebCPPA] specification, rather than require its use. The ebMS relies on a concept of "Agreement", the concrete representation of which (e.g. CPA or other configuration information) is left for implementers to decide.

The ebMS defines messaging functions, protocol and envelope intended to operate over SOAP (SOAP 1.1 or SOAP 1.2, and SOAP with Attachments). Binding to lower transport layers such as HTTP and SMTP relies on standard SOAP bindings when these exist, and ebMS only specifies some complement to these, as required.

This document, Part 1: Core Features, supports networking topologies in which there are limitations on initiating message transfer, but with only a point-to-point MSH topology, in which no intermediaries are present. A forthcoming Part 2, containing Advanced Features, may take into account topologies that contain intermediaries (e.g. hub, multi-hop), as well as those in which the ultimate MSH acts as a SOAP intermediary.

This version of ebMS leverages established SOAP-based specifications that handle quality of service in the domains of reliability and security. The ebMS specification defines how these are composed in the ebMS context. The design of this composition takes into account the reuse of existing implementations of these standards, not just the reuse of these standards themselves.

The concept for an ebMS implementation is of an ebXML Messaging Service Handler (MSH), that is abstractly defined as implementing the specified messaging functions. Any interface to the MSH is out of scope of this specification. Although it is clearly helpful in many cases to define a standard API, such an interface should not exclude other ways applications may want to interact with an MSH. Such an interface definition should rather belong to an implementation guideline companion document. An implementation of this specification could be delivered as a wholly independent software component or as an embedded component of a larger system.

3. Web Services and Their Role in an eBusiness Messaging Framework

A major design choice in ebMS 3, is the specification of the MSH and its associated processing rules using Web Services standards. The intent is to make use of other relevant Web Services specifications that fulfill certain messaging requirements, and build upon that base by adding what is necessary for a complete and coherent eBusiness messaging service. ebMS 3 brings this all together into a single, coherent framework.

In order to achieve this, message security and reliability requirements are met through the use of other Web Services standards and their implementations. The message SOAP body has been freed for business payload. The ebMS header is just a SOAP extension among others. As a result, ebMS 3 is significantly more compliant than ebMS 2 with the SOAP processing model, and apt at composing Web services standards that are defined as SOAP extensions. Compliance of ebMS 3 implementations with the latest version of WS-I profiles - once approved as final material by the organization - will be addressed in the definition of conformance profiles that are adjunct to this specification (see Appendix G).

Compliance with Web services standards does not remove the rationale behind an Internet-based messaging middleware. Often, document-centric eBusiness and eGovernment exchanges need to clearly dissociate messaging functions from the way these messages are consumed on the back-end. Such consumption may take place according to various models, as mentioned in 1.1. The use of [SOAP] message header elements that represent standard business metadata (user or company ID, business conversation, business service and action, etc.), is a key feature for supporting a decoupled binding with back-end business processes. At the same time, experience has demonstrated that the messaging layer must be more supportive of business transactions: messages are parts of basic choreographies that map to higher-level business exchanges between partners. To this end, ebMS 3 supports a notion of message exchange pattern (MEP) the properties of which (reliability, security, binding to underlying transport, error handling, and other quality of service aspects such as timing, etc.) are controlled in a contract-based manner by the message producer and consumer layers.

4. Caveats and Assumptions

The target audience for this specification is the community of software developers who will implement the ebXML Messaging Service.

It is assumed the reader has an understanding of communications protocols, MIME, XML, SOAP, SOAP Messages with Attachments and security technologies.

All examples are to be considered non-normative. If inconsistencies exist between the specification and the examples, the specification supersedes the examples.

Implementers are strongly advised to read and understand the Collaboration Protocol Profile & Agreement [ebCPPA] specification and its implications prior to implementation.

This specification presents some alternatives regarding underlying specifications (e.g. SOAP 1.1/1.2, WSS1.0/1.1, and Web Services specifications that support the reliability function). This does not imply that a conforming implementation must support them all, nor that it is free to support any option. The definition of conformance profiles - out of scope for this document, and to be described in an adjunct OASIS document - will complement this specification by asserting which option(s) must be supported in order to claim support for a particular conformance profile. Conformance to compatible profiles is a prerequisite to interoperability. See Appendix G for more details on conformance profiles.

5. General Rules for Normative Interpretation

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].

For any given module described in this specification, an implementation MUST satisfy ALL of the following conditions to be considered a conforming implementation of that module:

1. It supports all the mandatory syntax, features and behavior (as identified by the [RFC2119] key words MUST, MUST NOT, REQUIRED, SHALL and SHALL NOT) defined in the section that specifies that module.

2. When the keywords MUST, SHALL, or REQUIRED are used to qualify a feature, support for this feature--either message content or implementation behavior--is mandatory in an implementation with a conformance profile that requires this feature.

3. It complies with the following interpretation of the keywords OPTIONAL and MAY: When these keywords apply to the behavior of the implementation, the implementation is free to support these behaviors or not, as meant in [RFC2119]. When these keywords apply to message contents relevant to a module of features, a conforming implementation of such a module MUST be capable of processing these optional message contents according to the described ebXML semantics.

4. If it has implemented optional syntax, features and/or behavior defined in this specification, it MUST be capable of interoperating with another implementation that has not implemented the optional syntax, features and/or behavior. It MUST be capable of processing the prescribed failure mechanism for those optional features it has chosen to implement.

5. It is capable of interoperating with another implementation that has chosen to implement optional syntax, features and/or behavior, defined in this specification, it has chosen not to implement. Handling of unsupported features SHALL be implemented in accordance with the prescribed failure mechanism defined for the feature.

6. XML Notation

When describing concrete XML schemas and information items, this specification uses a convention in which each XML element or attribute is identified using abbreviated [XPATH] notation (e.g., /x:MyHeader/x:SomeProperty/@attribute).

7. Namespace Prefixes

This table maps various prefixes that appear in XML examples to their intended corresponding namespaces.

8. Example Domains

Hostnames used in the examples are fictitious, and conform to [RFC2606]. The example.org domain is intended to refer generically to a relevant industry standards organization, while the example.com domain represents a participant in a message exchange (whether commercial, government, or other entity).

9. Normative References

[HTTP11] R. Fielding, et al, Hypertext Transfer Protocol -- HTTP/1.1, 1999. <http://www.ietf.org/rfc/rfc2616.txt>

[IANAMEDIA] Various, MIME Media Types, Various. <http://www.iana.org/assignments/media-types/>

[RFC2045] N Freed, et al, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, 1996. <http://www.ietf.org/rfc/rfc2045.txt>

[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, 1997. <http://www.ietf.org/rfc/rfc2119.txt>

[RFC2387] E. Levinson, The MIME Multipart/Related Content-type, 1998. <http://www.ietf.org/rfc/rfc2387.txt>

[RFC2392] E. Levinson, Content-ID and Message-ID Uniform Resource Locators, 1998. <http://www.ietf.org/rfc/rfc2392.txt>

[RFC2396] T. Berners-Lee, et al, Uniform Resource Identifiers (URI): Generic Syntax, 1998. <http://www.ietf.org/rfc/rfc2396.txt>

[RFC2822] P. Resnick, ed., Internet Message Format, 2001. <http://www.ietf.org/rfc/rfc2822.txt>

[SMTP] J. Klensin, ed., Simple Mail Transfer Protocol, 2001. <http://www.ietf.org/rfc/rfc2821.txt>

[SOAP11] D. Box, et al, Simple Object Access Protocol (SOAP) 1.1, 2000. <http://www.w3.org/TR/2000/NOTE-SOAP-20000508/>

[SOAP12] M. Gudgin, et al, SOAP Version 1.2 Part 1: Messaging Framework, 2003. <http://www.w3.org/TR/soap12-part1/>

[SOAPATTACH] J. Barton, et al, SOAP Messages with Attachments, 2000. <http://www.w3.org/TR/SOAP-attachments>

[UTF8] F. Yergeau, UTF-8, a transformation format of ISO 10646, 1998. <http://www.ietf.org/rfc/rfc2279.txt>

[WSIAP10] Chris Ferris, et al, eds, Attachments Profile Version 1.0, 2004. <http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html>

[WSIBSP10] Abbie Barbir, et al, eds, Basic Security Profile Version 1.0, 2005. <http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html>

[WSR11] Kazunori Iwasa, et al, eds, WS-Reliability 1.1, 2004. <http://docs.oasis-open.org/wsrm/ws-reliability/v1.1/wsrm-ws_reliability-1.1-spec-os.pdf>

[WSRM11] D. Davis, et al, eds, Web Services Reliable Messaging (WS-ReliableMessaging) Version 1.1, 2007. <http://docs.oasis-open.org/ws-rx/wsrm/v1.1/wsrm.pdf>

[WSRMP11] D. Davis, et al, eds, Web Services Reliable Messaging Policy (WS-RM Policy) Version 1.1, 2007. <http://docs.oasis-open.org/ws-rx/wsrmp/v1.1/wsrmp.pdf>

[WSS10] Anthony Nadalin, et al, eds., Web Services Security: SOAP Message Security 1.0, 2004. <http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf>

[WSS10-USER] P. Hallam-Baker, et al, eds., Web Services Security UsernameToken Profile 1.0, 2004. <http://docs.oasis-open.org/wss/2004/01/>

[WSS10-X509] P. Hallam-Baker, et al, eds., Web Services Security X.509 Certificate Token Profile, 2004. <http://docs.oasis-open.org/wss/2004/01/>

[WSS11] Anthony Nadalin, et al, eds., Web Services Security: SOAP Message Security 1.1, 2005. <http://docs.oasis-open.org/wss/v1.1/>

[WSS11-USER] A. Nadalin, et al, eds., Web Services Security UsernameToken Profile 1.1, 2006. <http://docs.oasis-open.org/wss/v1.1/>

[WSS11-X509] A. Nadalin, et al, eds., Web Services Security X.509 Certificate Token Profile 1.1, 2006. <http://docs.oasis-open.org/wss/v1.1/>

[XML10] Tim Bray, et al, eds., Extensible Markup Language (XML) 1.0 (Third Edition), 2004. <http://www.w3.org/TR/2004/REC-xml-20040204/>

[XMLDSIG] Donald Eastlake, et al, eds, XML-Signature Syntax and Processing, 2002. <http://www.w3.org/TR/xmldsig-core/>

[XMLENC] D. Eastlake, et al, XML Encryption Syntax and Processing, 2002. <http://www.w3.org/TR/xmlenc-core/>

[XMLNS] Tim Bray, et al, eds, Namespaces in XML, 1999. <http://www.w3.org/TR/REC-xml-names/>

[XMLSCHEMA] Henry S. Thompson, et al, eds., XML Schema Part 1: Structures Second Edition, 2004. <http://www.w3.org/TR/xmlschema-1/>

[XPATH] James Clark, et al, eds., XML Path Language (XPath) Version 1.0, 1999. <http://www.w3.org/TR/xpath>

10. Non-Normative References

[ebBP-SIG] OASIS ebXML Business Process TC, ebXML Business Signals Schema, 2006. <http://docs.oasis-open.org/ebxml-bp/ebbp-signals-2.0>

[ebCPPA] OASIS ebXML Collaboration Protocol Profile and Agreement Technical Committee, Collaboration-Protocol Profile and Agreement Specification Version 2.0, 2002. <http://www.oasis-open.org/committees/download.php/204/ebcpp-2.0.pdf>

[ebCPPA21] OASIS ebXML Collaboration Protocol Profile and Agreement Technical Committee, Collaboration-Protocol Profile and Agreement Specification Version 2.1, 2005. <http://www.oasis-open.org/committees/download.php/12208/ebcpp-2.1-april-5-2005-draft.doc>

[ebRISK] ebXML Security Team, ebXML Technical Architecture Risk Assessment v1.0, 2001. <http://ebxml.org/specs/secRISK.pdf>

[ISO6523] Unknown, Identification of organization identification schemes, 1998. <http://www.iso.org/iso/en/CatalogueDetailPage.CatalogueDetail?CSNUMBER=25773>

[ISO9735] Unknown, EDIFACT, 1988. <http://www.iso.ch/iso/en/CatalogueDetailPage.CatalogueDetail?CSNUMBER=17592>

[QAFW] Karl Dubost, et al, eds, QA Framework: Specification Guidelines, 2005. <http://www.w3.org/TR/qaframe-spec/>

[RFC2246] T. Dierks, et al, The TLS Protocol Version 1.0, 1999. <http://www.ietf.org/rfc/rfc2246.txt>

[RFC2402] S. Kent, et al, IP Authentication Header, 1998. <http://www.ietf.org/rfc/rfc2402.txt>

[RFC2606] D. Eastlake, et al, Reserved Top Level DNS Names, 1999. <http://www.ietf.org/rfc/rfc2606.txt>

[RFC2617] J. Franks, et al, HTTP Authentication: Basic and Digest Access Authentication, 1999. <http://www.ietf.org/rfc/rfc2617.txt>

[RFC3023] M. Murata, et al, XML Media Types, 2001. <http://www.ietf.org/rfc/rfc3023.txt>

[SOAPEMAIL] H. M. Mountain, et al, SOAP Version 1.2 Email Binding, 2002. <http://www.w3.org/TR/soap12-email>

[WSPOLICY] A. Vedamuthu, et al, eds, Web Services Policy 1.5: Framework, 2007. <http://www.w3.org/TR/ws-policy/>

[WSSECPOL] A. Nadalin, et al, eds, WS-SecurityPolicy 1.2, 2007. <http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.2/ws-securitypolicy.pdf>

2. Messaging Model

   1. Terminology and Concepts

This section defines the messaging model and its main concepts, along with the related terminology in use throughout the specification.

1. Components of the Model

The ebMS messaging model assumes the following components:

• ebMS MSH (Messaging Service Handler): An entity that is able to generate or process messages that conform to this specification, and to act in at least one of two ebMS roles defined below in Section 2.1.3: Sending and Receiving. In terms of SOAP processing, an MSH is either a SOAP processor or a chain of SOAP processors. In either case, an MSH must be able to understand the eb:Messaging header (qualified with the ebMS namespace).

• Producer (or Message Producer): An entity that interacts with a Sending MSH (i.e. an MSH in the Sending role) to initiate the sending of a user message. Some examples are: an application, a queuing system, another SOAP processor (though not another MSH).

• Consumer (or Message Consumer): An entity that interacts with a Receiving MSH (i.e. an MSH in the Receiving role) to consume data from a received user message. Some examples are: an application, a queuing system, another SOAP processor.

Figure 1 shows the entities and operations involved in a message exchange.

Notes:

In all figures, the arrows do not represent control flow, i.e. they do not represent a component invoking an operation on another component. They only represent data transfer under the control of an operation which may be implemented in either component.

Producer and Consumer are always MSH endpoints, and Submit and Deliver operations occur at the endpoints only once per message lifetime. Any actions performed by an intermediary will be defined in different terms.

Figure 1: Entities of the Messaging Model and Their Interactions

2. Message Terminology

An ebMS Message is a SOAP message that contains SOAP header(s) qualified with the ebMS namespace, and that conforms to this specification.

An ebMS Message Unit is a logical unit of data that is a subset of an ebMS Message. There are two types of Message Units:

• an ebMS User Message Unit, which is represented by the XML infoset eb:Messaging/eb:UserMessage, together with any referenced payload items. This is the part of the ebMS message that is submitted by a Producer (via Submit operation) and that is subject to delivery to a Consumer.

• an ebMS Signal Message Unit, represented by the XML infoset eb:Messaging/eb:SignalMessage. Its role is to activate a specific function in the Receiving MSH. It is not intended to be delivered to a message Consumer.

An ebMS User Message is an ebMS message that contains a User Message unit (in other words, it contains an eb:UserMessage element as a child of eb:Messaging).

An ebMS Signal Message is an ebMS message that contains a Signal Message unit. A Signal Message that contains an eb:PullRequest element is also called a Pull Signal Message.

An ebMS Message may contain both a User Message Unit and a Signal Message Unit. In that case it is both a Signal Message and a User Message.

3. Messaging Roles

The Messaging Model assumes the following roles for an MSH:

• Sending: When an MSH acts in the Sending role, it performs the functions associated with generating an ebMS user message and sending this message to another MSH. The abstract operations Submit, Send and Notify are supported by this role. (Note that even in a Sending role, an MSH MAY be required to receive and process some types of Signal Messages, depending on the conformance profile in use.)

• Receiving: An MSH acting in the Receiving role performs the functions associated with the receiving and processing of an ebMS user message. The abstract operations Receive, Deliver and Notify are supported by this role. (Note that even in a Receiving role, an MSH MAY be required to generate and send ebMS Signal Messages related to the reception of messages, such as error messages or PullRequest signals.)

The transmission of an ebMS user message requires a pair of Sending and Receiving MSHs. Note that these roles are defined as only relevant to ebMS user messages, as are the abstract operations below.

4. Abstract Messaging Operations

An ebMS MSH supports the following abstract operations, depending on which role it is operating in:

• Submit: This operation transfers enough data from the producer to the Sending MSH to generate an ebMS User Message Unit.

• Deliver: This operation makes data of a previously received (via Receive operation) ebMS User Message Unit available to the Consumer.

• Notify: This operation notifies either a Producer or a Consumer about the status of a previously submitted or received ebMS User Message Unit, or about general MSH status.

• Send: This operation initiates the transfer of an ebMS user message from the Sending MSH to the Receiving MSH, after all headers intended for the Receiving MSH have been added (including security and/or reliability, as required).

• Receive: This operation completes the transfer of an ebMS user message from the Sending MSH to the Receiving MSH. A successful reception means that a contained User Message Unit is now available for further processing by the Receiving MSH.

2. Message Exchange Patterns

This section introduces the notion of an ebMS Message Exchange Pattern (MEP), and how it relates to SOAP MEPs. Such ebMS MEPs represent atomic units of choreography, i.e. different styles of exchange as required by connectivity constraints or application requirements.

1. Rationale

Two communicating partners may agree to conduct business transactions as message sequences that follow well defined patterns, or Message Exchange Patterns (MEP). Enforcing these patterns is usually done above the messaging layer. However it has proved useful to support some aspects of such MEPs in the messaging layer. In particular:

• The correlation between messages, when expressed directly via a referencing mechanism that appears in the message header, allows for efficient monitoring and enforcement of MEPs.

• As an MSH has to bind messages to the transport protocol, these binding requirements may be better expressed and controlled at MEP level. For example, different messages of the same MEP (such as a request and a response) may be required to bind differently to the transport.

An ebMS MEP represents the part of such exchange patterns that is controlled and implemented by an MSH, thus making an abstraction of the business semantics. Although the notion of MEP was not explicitly supported by ebMS 2.0, it can be noted that it provided some informal support for MEPs, such as message referencing (RefToMessageId) and the SyncReply element that controls the use of the back-channel of the underlying protocol. In the following, the acronym "MEP" implicitly means ebMS MEP, unless otherwise qualified.

The goal of this specification is to introduce a model for ebMS MEPs, rather than a formal representation of them. This model is the basis for partners agreeing to which MEPs their exchanges will conform. Such agreements are manifested in Processing Modes, or P-Modes, the representation of which is outside the scope of this specification. The P-Mode also defines which message profile is associated with which MEP, and the role it plays in this MEP. Processing Modes are described in detail in Section 4.

2. General Definition

An ebMS MEP defines a typical choreography of ebMS User Messages which are all related through the use of the referencing feature (RefToMessageId). Each message of an MEP instance refers to a previous message of the same instance, unless it is the first one to occur. Messages are associated with a label (e.g. "request", "reply") that precisely identifies their direction between the parties involved and their role in the choreography.

Note: Because RefToMessageId more accurately defines a referencing between User Message Units than between User Messages (SOAP messages), MEPs are preferably defined here as exchanges of Message Units, rather than of ebMS Messages.

Two MEPs are defined in this specification, not exclusive of others:

• The One-Way MEP which governs the exchange of a single User Message Unit unrelated to other User Messages. Its label is "oneway" and is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/oneWay .

• The Two-Way MEP which governs the exchange of two User Message Units in opposite directions, the first one to occur is labeled "request", the other one "reply". In an actual instance, the "reply" must reference the "request" using eb:RefToMessageId. This MEP is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/twoWay .

The MEP definitions are primarily concerned with the transfer of ebMS User Message Units. Instances of such MEPs may involve or cause the transfer of additional messages or the piggy-backing of additional elements (e.g. ebMS signal messages or units such as errors, receipts, pull requests, and low-level Acknowledgments when using reliability), but these are not taken into account in the MEP definition. Instead, the different ways these additions can be associated with the MEPs defined here, are considered as part of the execution mode of the MEP, which is controlled by some agreement/configuration external to the MEP definition (see P-Modes in Section 4). Some extra messages (Signal messages) may also be mandated by the binding of an ebMS MEP (see channel-binding), but are not relevant to the ebMS MEP definition itself.

MEP definitions in this document are restricted to exchanges between two MSHs.

3. MEP Bindings

The previous definition of ebMS MEP is quite abstract, and ignores any binding consideration to the transport protocol. This is intentional, so that application-level MEPs can be mapped to ebMS MEPs independently from the transport protocol to be used. In addition to agreeing on MEP usage, the following notions of MEP bindings should be subject to agreements between partners:

• An ebMS MEP Transport Channel Binding defines how the MEP maps to the channels allowed by the underlying transport protocol, while making an abstraction of this underlying transport. In case of a two-way transport, the transport channel binding defines whether each message of the MEP maps to the fore-channel (or first leg) or back-channel (second leg). It also tells if an ebMS Signal is needed to initiate the transfer - e.g. by pulling - and which one. Appendix E shows possible options for combining headers supporting reliable messaging as well as error reporting, when binding basic ebMS MEPs to a two-way protocol such as HTTP. The Appendix also shows how these combinations can be controlled with P-Mode parameters.

• An ebMS MEP Transport Protocol Binding defines further how an MEP transport channel binding is implemented over a specific underlying transport protocol such as HTTP or SMTP. For example, an HTTP transport protocol binding will define the usage of HTTP headers and methods for each message. A transport protocol binding usually relies on standard SOAP bindings when these exist.

A transport channel binding is a critical complement to an MEP, to be agreed on in order for partners to interoperate. The rationale in using different transport channel bindings for an ebMS MEP is to accommodate different connectivity constraints (e.g. firewall restrictions, intermittent availability, non-static IP address) by dictating how each message transfer is initiated over the underlying protocol. Because such connectivity constraints usually exist independently from the details of the transport protocol, the transport channel binding is the right level to address them. The transport channel bindings identified in this specification are:

• Push: maps an MEP User message to the 1st leg of an underlying 2-way transport protocol, or of a 1-way protocol. This binding is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/push .

• Pull: maps an MEP User message to the second leg of an underlying two-way transport protocol, as a result of an ebMS Pull Signal sent over the first leg. This binding is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/pull .

• Sync: maps an exchange of two User messages respectively to the first and second legs of a two-way underlying transport protocol. This binding is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/sync .

Notes:

• An underlying transport protocol qualifies as "two-way" if (a) it guarantees a transport channel for transferring the response of every message (request) initiated by an MSH, back to this MSH without need for explicit addressing information in SOAP headers, and regardless of connectivity restrictions such as inability to accept incoming new connections; and (b) it provides to the MSH initiator of the exchange, some means for correlating the response with the request, without relying on the SOAP header. For example, HTTP qualifies as two-way, but SMTP and FTP do not (although FTP has a notion of session, it does not inherently support the coupling of (b)). The channel offered in (a) is also called "back-channel" in this specification.

• "Pull" and "Sync" above cannot be used with a one-way underlying protocol.

• Communicating parties must agree on a transport channel binding: a sending MSH will treat a message submitted for pulling differently from a message submitted for pushing.

An MEP that is associated with a particular transport channel binding is also called a transport-channel-bound MEP. A transport-channel-bound MEP is identified by a pair <MEP name / transport-channel-binding name>. For example, a Two-Way ebMS MEP that executes over a single request-response exchange of the underlying transport (e.g. HTTP), is called a Two-Way/Sync MEP.

A channel-bound MEP has an Initiating MSH, or Initiator, which is the one that triggers the execution of the MEP. The other MSH is called the Responding MSH, or Responder. These MSH roles do not change for the duration of the MEP, regardless of the number of messages exchanged and of their direction. Due to endpoint addressing or availability restrictions, some MSHs may be required to act only as initiator, and never as responder.

On the wire, the only method by which messages from the same MEP instance are associated, is through a referencing link (RefToMessageId). This referencing is decided above the MSH layer (by the Producer entity). A receiving MSH relies on both this referencing and the interpretation of the P-Mode for associating a message with a specific MEP and for validating this association.

4. Relationship to SOAP MEPs

In theory, the transport-channel-bindings previously defined could be expressed in terms of SOAP MEPs instead of channels of the underlying transport protocol. However, the notion of SOAP MEP has only been introduced with SOAP 1.2, and would need to be extended to SOAP 1.1.

Also, only the SOAP Request-Response MEP and Response MEP have been formally defined, as of the time this specification was written. A SOAP One-way MEP could also be defined, but how such an MEP may or may not bind to a two-way underlying protocol is yet to be determined.

Expressing the transport-channel-binding in terms of SOAP MEPs is only helpful if there is a published, non-ambiguous, standard way for these to map to the underlying protocol(s). This is currently only the case for some SOAP MEPs and some transport protocols. Consequently, this specification has chosen to express its transport-channel-bindings directly in terms of how to use the channels of the transport protocol, abstracting such a transport as either "One-Way" or "Two-Way".

5. The One-Way/Push MEP

This transport-channel-bound MEP involves the transfer of a single ebMS User Message unit (label: "oneway").

To conform to this MEP, the ebMS User Message unit that is exchanged MUST NOT relate to any other User Message unit (no eb:RefToMessageId element). Figure 2 illustrates the exchange pattern and MSH operations involved in this MEP.

In case the One-Way/Push MEP is performed over a Two-way underlying transport protocol, the response message MAY carry an ebMS Signal Message, such as an error message, or other SOAP headers. Such an option is controlled by the P-Mode (see Section 4). However, the response message MUST NOT carry an ebMS User Message that refers to the request message. If the P-Mode allows Faults to be reported on the Two-way protocol's back-channel, the MEP can be qualified as a robust MEP, but is still an ebMS One-Way/Push MEP.

6. The One-Way/Pull MEP

   This transport-channel-bound MEP involves the transfer of a single ebMS User Message unit (label: "oneway"). This MEP is initiated by the Receiving MSH, over a two-way underlying transport protocol. The first leg of the protocol exchange carries a Pull Signal message. The second leg returns the pulled User Message unit. To conform to this MEP the pulled User Message unit MUST NOT include an eb:RefToMessageId element. In case no message is available for pulling, an ebMS error signal of severity level "warning" and short description of "EmptyMessagePartitionChannel", as listed in Section 6.7.1, MUST be returned over the response leg. Figure 3 illustrates this MEP.

7. The Two-Way/Sync MEP

This transport-channel-bound MEP transfers two ebMS User Message units over a single Request-Response exchange of the underlying 2-way transport protocol. The Initiator MSH sends the first User Message called the "request" . In the second leg of the MEP, a related User Message unit called the "reply" is sent back. To conform to this MEP, the request MUST NOT relate to any other User Message unit (no eb:RefToMessageId element), and the reply MUST refer to the request via the eb:RefToMessageId header element, as described in Section 5.2.2.1. Figure 4 illustrates this MEP.

8. Other Transport-Channel-Bound MEPs

So far, message exchanges conforming to either one of the three previous transport-channel-bound MEPs were only using one instance of an underlying transport protocol MEP for their binding. The following channel-bound ebMS MEPs are expected to be among the most common ebMS MEPs that use more than one underlying transport protocol MEP instance between the Initiating MSH and the Responding MSH. In this sense, they may be qualified as asynchronous.

• The Two-Way/Push-and-Push MEP composes the choreographies of two One-Way/Push MEPs in opposite directions, the User Message unit of the second referring to the User Message unit of the first via eb:RefToMessageId. This MEP is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/pushAndPush .

• The Two-Way/Push-and-Pull MEP composes the choreography of a One-Way/Push MEP followed by the choreography of a One-Way/Pull MEP, both initiated from the same MSH (Initiator). The User Message unit in the "pulled" message must refer to the previously "pushed" User Message unit. This MEP is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/pushAndPull .

• The Two-Way/Pull-and-Push MEP composes the choreography of a One-Way/Pull MEP followed by the choreography of a One-Way/Push MEP, with both MEPs initiated from the same MSH. The User Message unit in the "pushed" message must refer to the previously "pulled" User Message unit. This MEP is identified by the URI
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/pullAndPush .

In all the above MEPs, the messages labels are respectively "request" and "reply". The two last MEPs support asynchronous exchanges where one party is constrained in terms of addressing or connectivity capability.

3. Message Pulling and Partitioning

   1. Objectives

Business partners may experience differences in their ability to handle message flow, intermittent connectivity, lack of static IP addresses or firewall restrictions. In addition, when a message is transferred and successfully acknowledged, the responsibility for its management shifts sides. For these reasons, a receiver may want (a) to retain control over the transfer procedure of the underlying protocol by initiating transfers, and/or (b) to decide which messages it wants to receive first and when. Two features have been introduced in ebMS 3 that support this:

• Message Pulling

• Message Partition Channels (MPCs)

Message Pulling is defined in an abstract way by the One-Way/Pull ebMS MEP (see Section 2.2.6). This MEP allows an MSH to initiate the transfer of a message as a receiver. When used in combination with the One-Way/Push ebMS MEP, it allows an MSH full control over initiating asynchronous transfers with another MSH in both directions, engaging in a client-server type of interaction with the remote MSH, without any need to open a TCP/IP port to incoming requests. This MEP also supports exchanges with a partner that is intermittently connected: instead of periodically polling for partner presence, a sending MSH will simply wait for the partner MSH to pull its messages.

Example: A mobile, occasionally connected device without static IP address and with limited storage capability can only initiate requests and receive messages as synchronous responses to these requests. The One-Way/Pull MEP allows this device to enable and control the flow of received messages, and to adjust it to its own resources.

Message Partition Channels (see Section 3.4) allow for partitioning the flow of messages from an MSH to another MSH into separate flows, so that each one of these flows can be controlled independently by either MSH, in terms of transfer priorities. A Sending MSH MUST be able to determine whether a submitted message should be pulled or pushed, and to which Message Partition Channel (MPC) it must be assigned. Similarly, the Receiving MSH is aware of which MPC(s) should be pulled from, and which ones will be used for push. This knowledge is based on an agreement shared between parties prior to the exchanges, and modeled in this specification as the P-Mode operation set (see Section 4).

2. Supporting Message Pulling

Using Message pulling requires the ability of an MSH to support the One-Way/Pull MEP. The PullRequest signal that initiates this MEP is described in Section 5.2.3.1. Because there is always at least one MPC open between a Sending MSH and a Receiving MSH–the default MPC–the Pull mode can be supported regardless of the ability to support several MPCs.

When sending a PullRequest signal, the name of the MPC to pull messages from must be specified (in eb:PullRequest/@mpc attribute), unless the default value is to be assumed.

The processing model for a pulled message is as follows, for a typical and successful instance of One-Way/Pull MEP:

On Responding MSH side:

1. Submit: submission of message data to the MSH by the Producer party, intended for the Consumer on the Initiator side. The message is associated with an MPC. If no MPC name is provided by the submitter, or if the MSH implementation has not been provided with a way to determine this association by itself, the default MPC is used. The MEP associated with this message (e.g. as specified by P-Mode.MEP; see Section 4.2) is a One-Way/Pull.

On Initiating MSH side:

2. Sending of a PullRequest signal by the MSH. The PullRequest signal specifies the MPC from which to pull messages.

On Responding MSH side:

3. Reception of the PullRequest signal. For every PullRequest signal received the Responder MSH (acting in Sending role) selects a previously submitted message. It is RECOMMENDED to select messages according to a FIFO policy with respect to the Submit operation. If there is no user message available in the specified MPC for sending, a warning signal with short description: "EmptyMessagePartitionChannel" (see Section 6.7.1) MUST be sent back instead.

4. Send: the selected message is sent over the SOAP Response to the PullRequest.

On Initiating MSH side:

5. Receive: the pulled message is available for processing by the MSH. The header @mpc attribute indicates from which MPC it has been pulled, and is the same as the value of @mpc in the corresponding PullRequest signal.

6. Deliver: after processing of ebMS headers, delivery of the pulled message data to the Consumer of the MSH.

Example: An example of eb:Messaging header for the PullRequest signal:

<S11:Envelope>

<S11:Header>

<eb:Messaging S11:mustUnderstand="1">

<eb:SignalMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-10-01T10:01:00</eb:Timestamp>

<eb:MessageId>UUID-4@receiver.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:PullRequest mpc="http://sender.example.com/mpc123"/>

</eb:SignalMessage>

</eb:Messaging>

</S11:Header>

<S11:Body/>

</S11:Envelope>

Example: An outline of eb:Messaging header for the response to the above PullRequest signal example:

<S11:Envelope>

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" >

<eb:UserMessage mpc="http://sender.example.com/mpc123">

<eb:MessageInfo>

<eb:Timestamp>2006-10-01T10:02:00</eb:Timestamp>

<eb:MessageId>UUID-5@sender.example.com</eb:MessageId>

<eb:RefToMessageId>UUID-4@receiver.example.com</eb:RefToMessageId>

</eb:MessageInfo>

<eb:PartyInfo>

...

</eb:PartyInfo>

<eb:CollaborationInfo>

...

</eb:CollaborationInfo>

<eb:PayloadInfo>

...

</eb:PayloadInfo>

</eb:UserMessage>

</eb:Messaging>

</S11:Header>

<S11:Body>

...

</S11:Body>

</S11:Envelope>

3. Combining Pulling with Security and Reliability

Reliability of a pulled message is usually associated with the reliability of the corresponding PullRequest signal. The reliability of the One-Way/Pull MEP instance is addressed in Section 8.3.

Security for the PullRequest signal is described in details in Section 7.11.

Example: An outline of a secure and reliable eb:Messaging header for the PullRequest signal follows. The reliability header used in the example assumes the use of WS-Reliability, and specifies At-Least-Once delivery, with an acknowledgment to be returned on the MEP response message:

<S11:Envelope>

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" >

<eb:SignalMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-10-01T10:01:00</eb:Timestamp>

<eb:MessageId>UUID-4@receiver.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:PullRequest mpc="http://sender.example.com/mpc123"/>

</eb:SignalMessage>

</eb:Messaging>

<wss:Security>

...

</wss:Security>

<wsr:Request S11:mustUnderstand="1">

...

<ReplyPattern>

<Value>Response</Value>

</ReplyPattern>

<AckRequested/>

...

</wsr:Request>

</S11:Header>

<S11:Body/>

</S11:Envelope>

Example: An outline of secure and reliable eb:Messaging header for the response to the above PullRequest signal:

<S11:Envelope>

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" >

<eb:UserMessage mpc="http://sender.example.com/mpc123">

<eb:MessageInfo>

<eb:Timestamp>2006-10-01T10:02:00</eb:Timestamp>

<eb:MessageId>UUID-5@sender.example.com</eb:MessageId>

<eb:RefToMessageId>UUID-4@receiver.example.com</eb:RefToMessageId>

</eb:MessageInfo>

<eb:PartyInfo>

...

</eb:PartyInfo>

<eb:CollaborationInfo>

...

</eb:CollaborationInfo>

<eb:PayloadInfo>

...

</eb:PayloadInfo>

</eb:UserMessage>

</eb:Messaging>

<wsr:Response S11:mustUnderstand="1">

...

</wsr:Response>

<wss:Security>

...

</wss:Security>

</S11:Header>

<S11:Body>

...

</S11:Body>

</S11:Envelope>

Note:
In the above example, the reliability header, which assumes the use of WS-Reliability, is a Response element. It contains the reliability acknowledgment for the PullRequest signal. In this example there is no wsr:Request reliability header. A wsr:Request header could be present, in addition to wsr:Response, in case some specific reliability requirement is associated with the pulled message (see Section 8.3).

4. Message Partition Channels

   1. Concept and Purpose

Message Partition Channels (MPCs) allow for partitioning the flow of messages from a Sending MSH to a Receiving MSH into several flows that can be controlled separately and consumed differently. They also allow for merging flows from several Sending MSHs, into a unique flow that will be treated as such by a Receiving MSH. In particular, MPCs allow for:

1. setting transfer priorities: some messages may be transferred with higher priority than others regardless in which order they all have been submitted. For example, when using pulling mode, a Receiving MSH may decide from which MPC to pull messages first, based on business needs and readiness to incur responsibility in managing these messages.

2. organizing the inflow of messages on receiving side, so that each flow can be consumed in a distinct way, yet without having to filter messages based on various header elements or payload content. The agreement between two parties on when messages are to be transferred and how they are to be consumed may then be reduced to which MPC will be used.

Notes:

The notion of MPC is abstract from any particular implementation device such as ports or queues: an implementation may choose to implement MPCs using queues and a FIFO policy, though it is not required to.

Although MPCs are most obviously beneficial to message pulling operations, MPCs may be used in association with pushed messages as well. The benefits of doing so, listed above, apply to the push case as well.

Example: A pair of business partners – a large buyer and a small supplier - have decided to create two MPCs for transferring messages sent by the buyer. Urgent messages that require immediate processing (e.g. high priority Purchase Orders, and updates to prior Purchase Orders) are assigned to one MPC; and less urgent messages (payments, catalog requests, confirmations, acknowledgments of receipts, etc.)are assigned to the other MPC. The buyer determines the level of urgency of a posting, which may or may not be manifested inside the message. Per an agreement with the buyer, the supplier will pull and process first all messages from the "urgent" MPC; then, once that is exhausted, only the messages from the less urgent MPC. This way, the low-capacity Receiving MSH (supplier) is able to prioritize the reception of its messages, focusing its resources on the most urgent messages and avoiding the overhead and risk in managing (persistence, recovery, security) less urgent but important messages that it cannot process in the short term.

Any more complex filtering mechanism that requires checking a filter condition on header data, is out of scope of this specification. Such filtering could be implemented in a Sending MSH and/or in a Receiving MSH as a complement to, or instead of, different MPCs. The notion of MPC is a simple and robust solution with low interoperability risk: it allows for partitioning messages based on prior agreement between producer and consumer on which type of message will use which MPC, without a need to communicate and process filter expressions for each message transfer.

Figure 5: One-Way/Pull with Message Partition Channels

Figure 5 illustrates how MPCs and the One-Way/Pull MEP can be used by a Consumer party to control the order of the messages it wants to receive and process. Messages on MPC 1 are "pulled" in priority by the Consumer side.

There is no requirement for ordering messages in an MPC, unless specified otherwise by the reliability requirements to which these messages are subjected. The transfer of messages over an MPC is controlled by:

• The MEPs in which these messages participate. Messages over the same MPC can either be pulled or pushed, based on the different MEPs that govern the transfer of these messages.

• The regular addressing means used for sending messages (e.g. URL of Receiving MSH when pushing messages). MPCs do not have any routing or addressing capability.

Before it is transferred from a Sending MSH to a Receiving MSH, regardless of whether it is pushed or pulled, a message is always assigned to an MPC. If no explicit assignment is requested (e.g. by the message Producer at Submit time or per configuration of the MSH), the default MPC name "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/defaultMPC" is assigned.

2. Some Use Cases

Figure 6 illustrates various cases in using MPCs.

Figure 6: Message Partition Channel Use Cases

In the figure above, each arrow represents the transfer of a user message, which could be either pushed or pulled.

Between MSHs A and B, no MPC has been explicitly defined or assigned. All messages transferred from A to B – whether pushed or pulled – will implicitly use the default MPC.

MSHs C and D have been configured to use MPCs 1 and 2 (in addition to the default MPC). Messages sent may be assigned to either one of these MPCs. In case these messages are pulled, MSH D may choose from which MPC to pull first.

MPC 3 is shared by two Sending MSHs, E and G. The effect of using this MPC is to define on the Receiving MSH F a merged inflow of messages from E and G, which may be presented to the Consumer as a single flow. If messages m3 and m4 are pulled, MSH F has control over which MSH from which to pull first.

MPC 4 is used by MSH G to send either to MSH J or MSH K. When combined with message pulling, this use case allows for various scenarios. For example, the message flow might initially go exclusively from G to J. In case MSH J fails, another MSH (K) may immediately take over the message flow without any change on the sender side (assuming K is authorized) nor any knowledge by K of where the initial flow was intended for. Or, two Receiving MSHs (J and K) that are remote from each other but used by equivalent applications may split the processing of messages submitted to the same Sending MSH G. This may be, for example, two agencies equally qualified to process trouble tickets, indiscriminately pulling messages from the same MPC at the pace allowed by their processing capacity. MPC 4 may also be used by concurrent, pushed message flows. Using the same MPC does not introduce any dependency between the processing of m5 and m6 in J and K, but may be associated with a particular business meaning (i.e. is meaningful to Consumers of J and K).

3. Definition and Usage Requirements

An MPC is a flow of messages from a set of Sending MSHs to a set of Receiving MSHs, in the sense given in flow networks theory. It is identified by a name–a string of characters–that is assigned to every message of the flow. For every message it sends or receives, an MSH must be aware of which MPC this message is assigned to. MPC is a dynamic notion, the elements of which do not need to be fully defined prior to initiating this flow. For example, additional MSHs (either Sending or Receiving) may join the flow at any time, assuming they have knowledge of the MPC name, and assuming there is no other reason preventing them from transferring messages over this MPC (e.g. security).

The association between a user message and an MPC is apparent in the ebMS header of the message (see Section 5.2). Except for the default MPC, the MPC name must appear in the header of a user message transferred over this MPC.

Note:
As defined above, an MPC may involve more than a Sending MSH and a Receiving MSH. In particular, two unrelated pairs of Sending/Receiving MSHs (e.g. in the previous figure, C and D on the one hand, E and F on the other hand) could transfer messages using the same MPC name (e.g. MPC 3 in the figure could also be renamed MPC 2). Formally speaking, all these messages would be transferred over the same MPC. There might be some business significance in deciding whether two pairs of MSHs that have unconnected message flows should use the same MPC to transfer these messages, even though as far as the MSHs are concerned, they will process these two separate sub-flows of messages independently from each other.

Only user messages may be assigned to MPCs, not signal messages.

A PullRequest signal message always indicates in its header (see Section 5.2.3.1) the MPC on which the message must be pulled. If no MPC is explicitly identified, the default MPC MUST be pulled from. The pulled message sent in response MUST have been assigned to the indicated MPC.

The association of a message with an MPC must be done either at Submit time, e.g. requested by the message Producer; or at any time between Submit and Send, e.g. based on configuration or processing mode (see Section 4). This is left to the implementation.

Support for assigning messages to MPCs–e.g. by automatically mapping messages submitted by a Producer to a particular MPC based on some rules, queries or filters–is out of scope of this specification. Similarly, there is no requirement on what criteria (e.g. query expression, FIFO policy) can be used to select messages when pulling messages from an MPC. This specification only describes the properties of MPCs, and how their use affects the message protocol. It does not prescribe a particular way to implement MPCs or to use them.

A message associated with an MPC could fail to be transferred for various reasons (transport issue, security, intermediaries, etc.) and therefore could be removed from the MPC at any time. In other words, there is no additional delivery contract for messages over an MPC, other than that specified by the reliability agreement.

There is no specific quality of service associated with an MPC. Security and reliability remain associated with parties or with MSHs, in a way that is orthogonal to MPCs; although an implementation is free to associate QoS with MPCs as long as this conforms to an agreement between parties.

4. Processing Modes

An MSH is operating–either for sending or receiving messages–with knowledge of some contextual information that controls the way messages are processed. This contextual information that governs the processing of a particular message is called Processing Mode (or P-Mode). Because different messages may be subject to different types of processing, an MSH generally supports several P-Modes.

A P-Mode represents some MSH input data that typically is not provided on a per-message basis, but that is common to a set of messages exchanged between or among parties. To this extent, the P-Mode may be interpreted as configuration data for a deployed MSH. On a Sending MSH, together with the information provided by the application layer for each submitted message, the P-Mode fully determines the content of the message header. For example, the "security" part of the P-Mode will specify certificates and keys, as well as which messages will be subject to these. This in turn will determine the content of the Security header. The set of all P-Modes that are supported by an MSH during operation, is called the P-Mode operation set of the MSH.

The association of a P-Mode with a message may be based on various criteria, usually dependent on header data (e.g. Service/Action, Conversation ID, or other message properties). Which security and/or which reliability protocol and parameters, as well as which MEP is being used when sending a message, is determined by the P-Mode associated with this message.

A data model for P-Modes is described in Appendix D. Although this specification does not require support for any particular representation of a P-Mode, a conformance profile for this specification may require support for a particular representation. An MSH MUST conform the processing of its messages to the values in the P-Mode associated with this message. The details of which P-Mode parameters must be supported by an implementation, is governed by the features associated with the conformance profile claimed by this implementation, i.e. by its profile feature set (see Appendix G on Conformance). An MSH MUST NOT process a message to normal completion if it has no matching P-Mode in its P-Mode operation set: i.e. the MSH MUST NOT deliver such a message when in Receiving role, or MUST NOT send it when in Sending role. When it cannot match a message to a P-Mode, an MSH MUST generate a ProcessingModeMismatch (EBMS:0010) error.

Note:
It is important to distinguish between Conformance Profiles (Appendix G) and P-Modes. A conformance profile qualifies an MSH implementation and does not vary with the usage made of the MSH. A P-Mode qualifies the dynamic exchange and processing of messages, and is generally user defined. It must be within the capabilities allowed by the conformance profile claimed by the MSH on which it is deployed.

1. Messaging Service Processing Model

Although different P-Modes may apply from one message to the other, the overall processing model remains the same for all messages. The P-Modes set may be seen as configuring the execution parameters for the general model.

The ebXML Messaging Service may be conceptually broken down into the following three parts:

1. an abstract Service Interface,

2. functions provided by the MSH and

3. the mapping to underlying transport service(s).

Figure 7 depicts a logical arrangement of the functional modules existing within one possible implementation of the ebXML Messaging Services architecture. These modules are arranged in a manner to indicate their inter-relationships and dependencies.

Following is a description of each module illustrated above. It should be noted that the stack diagram above is abstract, and this specification does not mandate that implementations adopt the architecture suggested by it, although the processing order shown here is RECOMMENDED, especially in regard to Security and Reliability Modules.

• Application or SOAP Processor - This is where the business logic for a message exchange / business process exists.

• Messaging Service Interface - This is the interface through which messages are channelled between the MSH core and the ebXML Application.

• ebMS Packaging - Handling, (de)enveloping and execution of Payload Services are performed by this module.

• Reliable Message Processing - This module fulfills the Quality of Service requirements for a message.

• Web Services Security Processing - Encryption/decryption of any SOAP message content and generation/verification of any digital signatures occurs in this module.

• Transport Protocol Bindings - These are the actual transport protocol bindings. This specification defines bindings for HTTP and SMTP in Appendix C, and supports the addition of other protocols.

2. Processing Mode Features

The P-Mode is partitioned into functional groups called P-Mode features. Each P-Mode feature covers one of the functional areas that is critical to achieving interoperability between two partners: security, reliability, transport, business collaboration, error reporting, Message Exchange Patterns (MEPs) and Message Partition Channels (MPCs).

The main P-Mode features are here identified by names of the form: P-Mode.<featurename>:

• P-Mode.Protocol: includes all transport related information that is necessary to achieve transport-level interoperability. This feature determines the type of transport involved (e.g. HTTP, SMTP, FTP) between two MSHs, and related configuration parameters. This feature usually treats all messages between two MSHs similarly. It also includes information about which SOAP version is to be used (SOAP 1.1 or SOAP 1.2).

• P-Mode.Reliability: includes all reliability contracts, or references to them, that will govern the reliability of messages exchanged. This feature determines the content of the reliability headers.

• P-Mode.Security: includes all security contracts, or references to them, including the security context and related resources (certificates, SAML assertions, etc.) that govern the message exchange. This feature determines the content of the wsse:Security header.

• P-Mode.BusinessInfo: includes all message-relevant data related to a collaboration between two parties. It also indicates which MPCs are to be used by these parties. This feature will complement or validate message data that is expected to be provided by the application on a per-message basis for these header elements:

• eb:UserMessage/eb:PartyInfo

• eb:UserMessage/eb:CollaborationInfo

• eb:UserMessage/eb:MessageProperties

• P-Mode.ErrorHandling: defines how each ebMS Error type is to be reported by this MSH. E.g. if the reporting is done using ebMS signal messages, it defines the address of the destination MSH. It also may include the policy chosen for raising ebMS Errors from the errors generated by functional modules (Reliability, Security). This P-Mode feature must define reporting mode parameters that will allow a Receiving MSH to decide:

• whether an error generated on reception of a message must be returned as response over the same SOAP MEP. (e.g. errorHandling.report.asResponse = true/false).

• whether an error generated on reception of a message must be returned to sender or to a third party over a new SOAP MEP. (e.g. errorHandling.report.ReceiverErrorsTo = <URL>).

• whether the Consumer and/or Producer (e.g. errorHandling.Report.ProcessErrorNotifyConsumer) of a message must be notified of an error generated on reception of the message.

In this specification, a P-Mode feature is abstractly considered to apply to both sending and receiving roles, although implementations may choose to represent only the subset relevant to the role in which they operate. A single P-Mode instance is also intended to govern all messages involved in an ebMS MEP. (The ebMS MEP and its transport channel binding are attributes of a P-Mode.) Because messages involved in an MEP (e.g. request and reply) may use different qualities of service, a single P-Mode may use different vectors of values for its parameters, depending on the message in the MEP. An outline of the data model for P-Modes is given in Appendix D.

Agreeing on a P-Mode operation set is essential for two parties in order for their MSHs to interoperate. P-Modes are the MSH-level expression of a prior agreement between partners. A reference to such an agreement may be present in the message header (see eb:AgreementRef element in Section 5.2.2.7).

3. Default Features for Processing Mode

In order to facilitate interoperability testing, or during the early phase of a deployment, it may be useful to drive message exchanges without relying on user-agreed P-Modes, without interfacing with any application, and (initially) without the added complexity of security and reliability features. To this end, a default semantics of each P-Mode feature is defined as follows:

• Default P-Mode.MEP: http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/oneWay

• Default P-Mode.MEPbinding: http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/push

• Default P-Mode.Protocol: HTTP 1.1 transport is assumed, with default configuration (on standard port), using SOAP 1.2.

• Default P-Mode.Reliability: No reliable messaging assumed (no reliability header will be present).

• Default P-Mode.Security: No secure messaging assumed (no security header will be present.)

• Default P-Mode.BusinessInfo: In the absence of any application input at message level as well as for this P-Mode feature, the following default header element values will be used (shown here for a message sent by an Initiator to a Responder party). Any of these may be overridden by application input.

• eb:UserMessage/eb:PartyInfo: The eb:From element contains a PartyId with value: http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/defaultFrom
  The eb:To element contains a PartyId with value:
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/defaultTo

• eb:UserMessage/eb:CollaborationInfo: Contains no eb:AgreementRef. The eb:Service element has the value:
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service
  The eb:Action element has the value:
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test
  (Section 5.2.2 details the semantics of these values.)
  The eb:ConversationId element has the value: 1.
  The default MPC is in use.

• eb:UserMessage/eb:MessageProperties: This element is absent.

• eb:UserMessage/eb:PayloadInfo: This element is absent.

• Default P-Mode.ErrorHandling: No reporting via ebMS message is required. The MSH may handle error reporting in a way that does not involve the partner MSH, such as notification to local Consumer or Producer.

In the absence of a user-agreed P-Mode feature, it is RECOMMENDED that an MSH operate based on the above default semantics for this feature except in the following cases:

1. The MSH is designed to conform to this specification along profiles (see Appendix G) that are not compatible with the default P-Mode feature. For example, such an incompatibility would occur for the default P-Mode.MEP with a conformance profile that only requires the One-Way/Pull MEP.

2. The MSH has been pre-configured to operate with a non-default P-Mode feature. This would be the case when an MSH is distributed along with a predefined P-Mode feature, e.g. built-in security. This amounts to using a user-defined P-Mode feature.

A Sending MSH and a Receiving MSH may use a mix of default and non-default P-Mode features.

5. Message Packaging

   1. Message Envelope and Message Parts

      1. MIME Structure and SOAP Profile

In the ebMS SOAP header eb:Messaging, the prefix "eb" is an example prefix that corresponds to the ebMS 3.0 namespace, as defined in Section 1.6. The ebMS Message can be packaged as a plain [SOAP11] or [SOAP12] message, or within a MIME multipart to allow payloads or attachments to be included. Because either packaging option can be used, implementations MUST support both multipart and non-multipart messages.

The ebMS Message MAY contain SOAP extension elements other than the eb:Messaging header block. For example, header blocks supporting message reliability and message security MAY be produced and consumed by an MSH in order to fulfill deployment requirements for those features.

An ebMS Message is packaged as a SOAP 1.1 or 1.2 message independent from communications protocols. When represented as a MIME multipart message envelope, this envelope MUST be structured in compliance with the SOAP Messages with Attachments [SOAPATTACH] W3C Note, referred to as a Message Package.

There are two logical sections within the Message Package:

• The first section is the ebMS Header (i.e. The eb:Messaging SOAP header block), itself contained in the SOAP Header.

• The second section is the ebMS Payload, which itself comprises two sections: (a) the SOAP Body element within the SOAP Envelope, and in case of MIME packaging, (b) zero or more additional MIME parts containing additional application-level payloads. The SOAP Body and MIME parts are also referred to as ebMS Payload Containers. The SOAP Body is the only payload container that requires XML-structured content, though non-XML content may be included within an appropriately typed (binary or otherwise) element inside the Body.

The general structure and composition of an ebMS User Message is described in Figure 8, and a Signal Message in Figure 9.

The processing of the SOAP eb:Messaging header block is done according to the SOAP processing semantics: an MSH behaves as a SOAP processor or SOAP node that MUST understand this header block. Other header blocks (except for those relevant to reliability and security of an ebMS Message) are not affected by the ebXML processing. Consequently, it is possible for a Sending MSH implementation to generate an ebMS message from a well-formed input SOAP message simply by adding an eb:Messaging header; likewise, some Receiving MSH implementation could deliver a well-formed SOAP message as output by removing (and processing) the eb:Messaging header.

All MIME headers of the Message Package MUST conform with the SOAP Messages with Attachments [SOAPATTACH] W3C Note. In addition, the Content-Type MIME header of the Message Package MUST contain a type parameter whose value matches the MIME media type of the MIME body part containing the SOAP Envelope document. In accordance with the [SOAP11] specification, the MIME media type of the SOAP 1.1 Message has the value "text/xml". It is STRONGLY RECOMMENDED that the initial headers contain a Content-ID MIME header structured in accordance with MIME [RFC2045], and in addition to the required parameters for the Multipart/Related media type, the start parameter (OPTIONAL in MIME Multipart/Related [RFC2387]) be present. This permits more robust error detection. The following fragment is an example of the MIME headers for the multipart/related Message Package:

Example 1. MIME Header fragment for the multipart/related Message Package

Content-Type: multipart/related; type="text/xml";

boundary="boundaryValue";start="<messagepackage-123@example.com>"

--boundaryValue

Content-ID: messagepackage-123@example.com

Because implementations MUST support non-multipart messages, an ebMS Message with no payload may be sent either as a plain SOAP message or as a [SOAPATTACH] multipart message with only one body part (the SOAP Envelope).

2. MIME and XML Considerations

This section contains further MIME- and XML-specific packaging requirements and guidance.

1. Additional MIME Parameters

Any MIME part described by this specification MAY contain additional MIME headers in conformance with the MIME [RFC2045] specification. Implementations MAY ignore any MIME header not defined in this specification. Implementations MUST ignore any MIME header they do not recognize. For example, an implementation could include Content-Length in a message. However, a recipient of a message with Content-Length could ignore it.

2. Reporting MIME Errors

If a MIME error is detected in the Message Package then it MUST be reported as specified in SOAP with Attachments [SOAPATTACH].

3. XML Prolog

The SOAP Message's XML Prolog, if present, MAY contain an XML declaration. This specification has defined no additional comments or processing instructions appearing in the XML prolog. For example:

Content-Type: text/xml; charset="UTF-8"

<?xml version="1.0" encoding="UTF-8" ?>

4. XML Declaration

The XML declaration MAY be present in a SOAP Message. If present, it MUST contain the version specification required by the XML Recommendation [XML10] and MAY contain an encoding declaration. The semantics described below MUST be implemented by a compliant ebXML Message Service.

5. Encoding Declaration

If both the encoding declaration and the MIME root part charset parameter are present, the XML prolog for the SOAP Message SHALL contain the encoding declaration, and SHALL be equivalent to the charset attribute of the MIME Content-Type of the root part (see Section 5.1.4). If provided, the encoding declaration MUST NOT contain a value conflicting with the encoding used when creating the SOAP Message. It is RECOMMENDED that UTF-8 be used when encoding the SOAP Message. If the character encoding cannot be determined by an XML processor using the rules specified in section 4.3.3 of XML [XML10], the XML declaration and its contained encoding declaration SHALL be provided in the ebXML SOAP Header Document. Note: The encoding declaration is not required in an XML document according to XML v1.0 specification [XML10].

3. ebXML SOAP Envelope Extension

In conformance with the [XML10] specification, all extension element content is namespace qualified. A namespace declaration (xmlns pseudo-attribute) for the ebXML SOAP extension may be included in the SOAP Envelope or Header element, or directly in the ebXML SOAP extension element.

1. namespace Pseudo Attribute

The namespace declaration for the ebXML SOAP Envelope extension (xmlns pseudo attribute) (see [XMLNS]) has a REQUIRED value of:

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

2. xsi:schemaLocation attribute

The SOAP namespace:

http://schemas.xmlsoap.org/soap/envelope/

resolves to a W3C XML Schema specification. It is STRONGLY RECOMMENDED that ebXML MSH implementations include the XMLSchema-instance namespace qualified schemaLocation attribute in the SOAP Envelope element, to indicate to validating parsers a location of the schema document that should be used to validate the document. Failure to include the schemaLocation attribute could prevent XML schema validation of received messages.

For example:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/

http://schemas.xmlsoap.org/soap/envelope/">

<S11:Header/>

<S11:Body/>

</S11:Envelope>

In addition, the ebXML SOAP Header extension element content MAY be similarly qualified, so as to identify the location where validating parsers can find the schema document containing the ebXML namespace-qualified SOAP extension element definition. The ebXML SOAP extension element schema, found in Appendix A, has been defined using the W3C Recommendation version of the XML Schema specification [XMLSCHEMA]. The XMLSchema-instance namespace qualified schemaLocation attribute should include a mapping of the ebXML SOAP Envelope extension namespace to its schema document in the same element that declares the ebXML SOAP Envelope extensions namespace.

The schemaLocation for the namespace described in Section 5.1.3.1 is:

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd

Separate schemaLocation attributes are RECOMMENDED. For example:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/

http://schemas.xmlsoap.org/soap/envelope/">

<S11:Header>

<eb:Messaging xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/"

xsi:schemaLocation=

"http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<eb:UserMessage>

<eb:MessageInfo >...</eb:MessageInfo>

...

<eb:PayloadInfo >...</eb:PayloadInfo>

...

</eb:UserMessage>

</eb:Messaging>

</S11:Header>

<S11:Body>

...

</S11:Body>

</S11:Envelope>

3. SOAP Header Element

The SOAP Header element is the first child element of the SOAP Envelope element. It MUST have a namespace qualifier that matches the SOAP Envelope namespace declaration for the namespace "http://schemas.xmlsoap.org/soap/envelope/".

4. SOAP Body Element

The SOAP Body element is the second child element of the SOAP Envelope element. It MUST have a namespace qualifier that matches the SOAP Envelope namespace declaration for the namespace "http://schemas.xmlsoap.org/soap/envelope/".

Note:
Unlike ebMS v2, ebXML Messaging 3.0 does not define or make use of any elements within the SOAP Body, which is wholly reserved for user-specified payload data.

5. ebXML SOAP Extensions

An ebMS Message extends the SOAP Message with the extension element eb:Messaging, where "eb" is the namespace prefix for ebMS 3.0.

Other headers that support some aspects of ebMS messaging, such as the security header (wsse:Security) and reliability headers, may be present. These are not qualified under the ebMS namespace.

4. ebMS Header

In case of MIME packaging, the root body part of the Message Package is the SOAP message, as defined in the SOAP Messages with Attachments [SOAPATTACH] W3C Note. This root part always contains the ebMS header.

The MIME Content-Type header for the root part MUST have the value "text/xml" to match the MIME media type of the MIME body part containing the [SOAP11] Message document, or "application/soap+xml" in the case of a [SOAP12] body. The Content-Type header MAY contain a "charset" parameter. For example:

Content-Type: text/xml; charset="UTF-8"

The MIME charset parameter identifies the character set used to create the SOAP Message. The semantics of this attribute are described in the "charset parameter / encoding considerations" of text/xml as specified in [RFC3023]. The list of valid values can be found at [IANAMEDIA].

If both are present, the value of the MIME charset parameter SHALL be equivalent to the encoding declaration of the SOAP Message. If provided, the MIME charset parameter MUST NOT contain a value conflicting with the encoding used when creating the SOAP Message.

For maximum interoperability it is RECOMMENDED UTF-8 [UTF8] be used when encoding this document. Due to the processing rules defined for media types derived from text/xml [RFC3023], this MIME attribute has no default.

The following fragment represents an example of a root part, for a MIME packaging of ebMS:

Content-ID: <messagepackage-123@example.com>

Content-Type: text/xml; charset="UTF-8"

<S11:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">

<S11:Header>

<eb:Messaging>

…

</eb:Messaging>

</S11:Header>

<S11:Body>

…

</S11:Body>

</S11:Envelope>

5. Payload Containers

In addition to the SOAP Body, other Payload Containers MAY be present within a Message Package in conformance with the SOAP Messages with Attachments [SOAPATTACH] specification.

If there is no application payload within the Message Package, then the SOAP Body MUST be empty, and there MUST NOT be additional Payload Containers.

There SHOULD also be no additional MIME attachments that are not Payload Containers (i.e., that are not referenced by an eb:PayloadInfo element, as described in Section 5.2.2.12); but if any such attachments are present, they are outside the scope of MSH processing. An MSH MUST NOT process application data that is not referenced by eb:PayloadInfo.

The contents of each Payload Container (including the SOAP Body) MUST be identified in the /eb:Messaging/eb:UserMessage/eb:PayloadInfo element.

The ebXML Messaging Service Specification makes no provision, nor limits in any way, the structure or content of application payloads. Payloads MAY be simple, plain-text objects or complex, nested, multipart objects. The specification of the structure and composition of payload objects is the prerogative of the organization defining the business process or information exchange using the ebXML Messaging Service.

Example of SOAP Message containing an ebMS header:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/

http://schemas.xmlsoap.org/soap/envelope/">

<S11:Header

xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<eb:Messaging S11:mustUnderstand="1">

<eb:UserMessage>

...

<eb:PayloadInfo>

...

</eb:PayloadInfo>

...

</eb:UserMessage>

</eb:Messaging>

</S11:Header>

<S11:Body>

...

</S11:Body>

</S11:Envelope>

2. The eb:Messaging Container Element

The REQUIRED eb:Messaging element is a child of the SOAP Header. It is a container for either a User message or a Signal message.

In the case of a User message, the ebXML header block contains an eb:UserMessage child element:

<eb:Messaging>

<eb:UserMessage>

<eb:MessageInfo>

<!-- some headers here like Timestamp and MessageId -->

</eb:MessageInfo>

<!-- header elements of the ebMS user message -->

</eb:UserMessage>

</eb:Messaging>

In the case of a Signal message, the ebXML header block (eb:Messaging) contains at least one eb:SignalMessage child element:

<eb:Messaging>

<eb:SignalMessage>

<eb:MessageInfo>

<!-- some headers here like Timestamp and MessageId -->

</eb:MessageInfo>

<eb:signalname>

<!-- header elements of this ebMS signal message -->

</eb:signalname>

</eb:SignalMessage>

</eb:Messaging>

For example, signalname can be "PullRequest".

1. eb:Messaging Element Specification

The eb:Messaging element has the following attributes:

• eb:Messaging/@S11:mustUnderstand: indicates whether the contents of the element MUST be understood by the MSH. This attribute is REQUIRED, with namespace qualified to the SOAP namespace (http://schemas.xmlsoap.org/soap/envelope/). It MUST have value of '1' (true) indicating the element MUST be understood or rejected.

The eb:Messaging element has the following children elements:

• eb:Messaging/eb:UserMessage: The OPTIONAL UserMessage element contains all header information for a User message. If this element is not present, an element describing a Signal message MUST be present.

• eb:Messaging/eb:SignalMessage/eb:[signalname]: The OPTIONAL element is named after a type of Signal message. It contains all header information for the Signal message. If this element is not present, an element describing a User message MUST be present. Three types of Signal messages are specified in this document: Pull signal (eb:PullRequest), Error signal (eb:Error) and Receipt signal (eb:Receipt).

Both eb:UserMessage element and eb:SignalMessage element MAY be present within the eb:Messaging element.

Example ebMS Message Header:

<!-- (contained within S11:Header) -->

<eb:Messaging S11:mustUnderstand="1" >

<eb:UserMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-2@example.com</eb:MessageId>

<eb:RefToMessageId>UUID-1@example.com</eb:RefToMessageId>

</eb:MessageInfo>

<eb:PartyInfo>

<eb:From>

<eb:PartyId>uri:example.com</eb:PartyId>

<eb:Role>http://example.org/roles/Buyer</eb:Role>

</eb:From>

<eb:To>

<eb:PartyId type="someType">QRS543</eb:PartyId>

<eb:Role>http://example.org/roles/Seller</eb:Role>

</eb:To>

</eb:PartyInfo>

<eb:CollaborationInfo>

<eb:AgreementRef>http://registry.example.com/cpa/123456

</eb:AgreementRef>

<eb:Service type="MyServiceTypes">QuoteToCollect</eb:Service>

<eb:Action>NewPurchaseOrder</eb:Action>

<eb:ConversationId>4321</eb:ConversationId>

</eb:CollaborationInfo >

<eb:MessageProperties>

<eb:Property name="ProcessInst">PurchaseOrder:123456

</eb:Property>

<eb:Property name="ContextID"> 987654321

</eb:Property>

</eb:MessageProperties >

<eb:PayloadInfo>

<eb:PartInfo href="cid:foo@example.com">

<eb:Schema location="http://example.org/bar.xsd" version="2.0"/>

<eb:Description xml:lang="en-US">Purchase Order for 100,000 foo widgets</eb:Description>

</eb:PartInfo>

<eb:PartInfo href="#idref">

</eb:PartInfo>

</eb:PayloadInfo>

</eb:UserMessage>

</eb:Messaging>

2. eb:Messaging/eb:UserMessage

This element has the following attributes:

• eb:Messaging/eb:UserMessage/@mpc: This OPTIONAL attribute contains a URI that identifies the Message Partition Channel to which the message is assigned. The absence of this element indicates the use of the default MPC. When the message is pulled, the value of this attribute MUST indicate the MPC requested in the PullRequest message.

This element has the following children elements:

• eb:Messaging/eb:UserMessage/eb:MessageInfo: This REQUIRED element occurs once, and contains data that identifies the message, and relates to other messages' identifiers.

• eb:Messaging/eb:UserMessage/eb:PartyInfo: This REQUIRED element occurs once, and contains data about originating party and destination party.

• eb:Messaging/eb:UserMessage/eb:CollaborationInfo: This REQUIRED element occurs once, and contains elements that facilitate collaboration between parties.

• eb:Messaging/eb:UserMessage/eb:MessageProperties: This OPTIONAL element occurs at most once, and contains message properties that are user-specific. As parts of the header such properties allow for more efficient monitoring, correlating, dispatching and validating functions (even if these are out of scope of ebMS specification) which would otherwise require payload access.

• eb:Messaging/eb:UserMessage/eb:PayloadInfo: This OPTIONAL element occurs at most once, and identifies payload data associated with the message, whether included as part of the message as payload document(s) contained in a Payload Container, or remote resources accessible via a URL. The purpose of the PayloadInfo is (a) to make it easier to directly extract a particular payload associated with this User message, (b) to allow an application to determine whether it can process the payload without having to parse it.

1. eb:Messaging/eb:UserMessage/eb:MessageInfo

This element has the following children elements:

• eb:Messaging/eb:UserMessage/eb:MessageInfo/eb:Timestamp: The REQUIRED Timestamp element has a value representing the date at which the message header was created, and is conforming to a dateTime (see [XMLSCHEMA]). It MUST be expressed as UTC. Indicating UTC in the Timestamp element by including the 'Z' identifier is optional.

• eb:Messaging/eb:UserMessage/eb:MessageInfo/eb:MessageId: This REQUIRED element has a value representing – for each message - a globally unique identifier conforming to MessageId [RFC2822]. Note: In the Message-Id and Content-Id MIME headers, values are always surrounded by angle brackets. However references in mid: or cid: scheme URI's and the MessageId and RefToMessageId elements MUST NOT include these delimiters.

• eb:Messaging/eb:UserMessage/eb:MessageInfo/eb:RefToMessageId: This OPTIONAL element occurs at most once. When present, it MUST contain the MessageId value of an ebMS Message to which this message relates, in a way that conforms to the MEP in use (see Section C.3).

2. eb:Messaging/eb:UserMessage/eb:PartyInfo

This element has the following children elements:

• eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From: The REQUIRED element occurs once, and contains information describing the originating party.

• eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:To: The REQUIRED element occurs once, and contains information describing the destination party.

3. eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From

This element has the following children elements:

• eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId: The REQUIRED PartyId element occurs one or more times. If it occurs multiple times, each instance MUST identify the same organization.

• eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:Role: The REQUIRED eb:Role element occurs once, and identifies the authorized role (fromAuthorizedRole or toAuthorizedRole) of the Party sending (when present as a child of the From element) or receiving (when present as a child of the To element) the message. The value of the Role element is a non-empty string, with a default value of
  http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/defaultRole .
  Other possible values are subject to partner agreement.

Example: The following fragment demonstrates usage of the From element.

<eb:From>

<eb:PartyId type="urn:oasis:names:tc:ebxml-cppa:partyid-type:duns"> 123456789</eb:PartyId>

<eb:PartyId type="SCAC">RDWY</eb:PartyId>

<eb:Role>http://example.org/roles/Buyer</eb:Role>

</eb:From>

4. eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId

This element has a string value content that identifies a party, or that is one of the identifiers of this party.

It has a single attribute, @type. The type attribute indicates the domain of names to which the string in the content of the PartyId element belongs. It is RECOMMENDED that the value of the type attribute be a URI. It is further RECOMMENDED that these values be taken from the EDIRA , EDIFACT or ANSI ASC X12 registries. Technical specifications for the first two registries can be found at and [ISO6523] and [ISO9735], respectively. Further discussion of PartyId types and methods of construction can be found in an appendix of [ebCPPA21]. The value of any given @type attribute MUST be unique within a list of PartyId elements.

An example of PartyId element is:

<eb:PartyId type="urn:oasis:names:tc:ebxml-cppa:partyid-type:duns"> 123456789</eb:PartyId>

If the eb:PartyId/@type attribute is not present, the content of the PartyId element MUST be a URI [RFC2396], otherwise the Receiving MSH SHOULD report a "ValueInconsistent" error with severity "error". It is strongly RECOMMENDED that the content of the eb:PartyId element be a URI.

5. eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:To

This element has the same children elements as eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From, above in Section 5.2.2.3.

Example: The following fragment demonstrates usage of the To element.

<eb:To>

<eb:PartyId>mailto:joe@example.com</eb:PartyId>

<eb:Role>http://example.org/roles/Seller</eb:Role>

</eb:To>

6. eb:Messaging/eb:UserMessage/eb:CollaborationInfo

This element has the following children elements:

• eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:AgreementRef: This OPTIONAL element occurs zero or once. The AgreementRef element is a string that identifies the entity or artifact governing the exchange of messages between the parties.

• eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:Service: This REQUIRED element occurs once. It is a string identifying the service that acts on the message and it is specified by the designer of the service.

• eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:Action: This REQUIRED element occurs once. The element is a string identifying an operation or an activity within a Service that may support several of these.

• eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:ConversationId: This REQUIRED element occurs once. The element is a string identifying the set of related messages that make up a conversation between Parties.

7. eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:AgreementRef

AgreementRef is a string value that identifies the agreement that governs the exchange. The P-Mode under which the MSH operates for this message should be aligned with this agreement.

The value of an AgreementRef element MUST be unique within a namespace mutually agreed by the two parties. This could be a concatenation of the From and To PartyId values, a URI containing the Internet domain name of one of the parties, or a namespace offered and managed by some other naming or registry service. It is RECOMMENDED that the AgreementRef be a URI. The AgreementRef MAY reference an instance of a CPA as defined in [ebCPPA].

An example of the AgreementRef element follows:

<eb:AgreementRef>http://registry.example.com/cpas/our_cpa.xml</eb:AgreementRef>

If a CPA is referred to and a Receiving MSH detects an inconsistency, then it MUST report it with an "ValueInconsistent" error of severity "error". If the AgreementRef is not recognized, then the Receiving MSH MUST report it as a "ValueNotRecognized" error of severity "error".

The AgreementRef element may have two attributes:

• @type: This OPTIONAL attribute indicates how the parties sending and receiving the message will interpret the value of the reference (e.g. the value could be "ebcppa2.1" for parties using a CPA-based agreement representation). There is no restriction on the value of the type attribute; this choice is left to profiles of this specification. If the type attribute is not present, the content of the eb:AgreementRef element MUST be a URI. If it is not a URI, then the MSH MUST report a "ValueInconsistent" error of severity "error".

• @pmode: This OPTIONAL attribute allows for explicit association of a message with a P-Mode. When used, its value contains the PMode.ID parameter.

8. eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:Service

This element identifies the service that acts on the message. Its actual semantics is beyond the scope of this specification. The designer of the service may be a standards organization, or an individual or enterprise.

Examples of the Service element include:

<eb:Service>urn:example.org:services:SupplierOrderProcessing</eb:Service>

<eb:Service type="MyServiceTypes">QuoteToCollect</eb:Service>

The Service element MAY contain a single @type attribute, that indicates how the parties sending and receiving the message will interpret the value of the element. There is no restriction on the value of the type attribute. If the type attribute is not present, the content of the Service element MUST be a URI (see [RFC2396]). If it is not a URI then the MSH MUST report a "ValueInconsistent" error of severity "error".

When the value of the element is http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service, then the receiving MSH MUST NOT deliver this message to the Consumer. With the exception of this delivery behavior, and unless indicated otherwise by the eb:Action element, the processing of the message is not different from any other user message.

9. eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:Action

This element is a string identifying an operation or an activity within a Service. Its actual semantics is beyond the scope of this specification. Action SHALL be unique within the Service in which it is defined. The value of the Action element is specified by the designer of the service.

An example of the Action element follows:

<eb:Action>NewOrder</eb:Action>

If the value of either the Service or Action element is unrecognized by the Receiving MSH, then it MUST report a "ValueNotRecognized" error of severity "error".

When the value of this element is http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test, then the eb:Service element MUST have the value http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service. Such a value for the eb:Action element only indicates that the user message is sent for testing purposes and does not require any specific handling by the MSH.

10. eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:ConversationId

This element is a string identifying the set of related messages that make up a conversation between Parties.

If a CPA is referred to by eb:AgreementRef, the number of conversations related to this CPA MUST comply with CPA requirements. The value of eb:ConversationId MUST uniquely identify a conversation within the context of this CPA.

An example of the ConversationId element follows:

<eb:ConversationId>20001209-133003-28572</eb:ConversationId>

The Party initiating a conversation determines the value of the ConversationId element that SHALL be reflected in all messages pertaining to that conversation. The actual semantics of this value is beyond the scope of this specification. Implementations SHOULD provide a facility for mapping between their identification scheme and a ConversationId generated by another implementation.

11. eb:Messaging/eb:UserMessage/eb:MessageProperties

This element has zero or more eb:Property child elements.

An eb:Property element is of xs:anySimpleType (e.g. string, URI) and has two attributes:

• @name: The value of this REQUIRED attribute must be agreed upon between partners.

• @type: This OPTIONAL attribute allows for resolution of conflicts between properties with the same name, and may also help with Property grouping, e.g. various elements of an address.

Its actual semantics is beyond the scope of this specification. The element is intended to be consumed outside the ebMS-specified functions. It may contain some information that qualifies or abstracts message data, or that allows for binding the message to some business process. A representation in the header of such properties allows for more efficient monitoring, correlating, dispatching and validating functions (even if these are out of scope of ebMS specification) that do not require payload access.

Example:

<eb:MessageProperties>

<eb:Property name="ContextId">C1234</eb:Property>

<eb:Property name="processinstanceID">3A4-1234</eb:Property>

<eb:Property name="transactionID">45764321</eb:Property>

</eb:MessageProperties>

12. eb:Messaging/eb:UserMessage/eb:PayloadInfo

Each PayloadInfo element identifies payload data associated with the message. The purpose of the PayloadInfo is:

• to make it easier to extract particular payload parts associated with this ebMS Message,

• and to allow an application to determine whether it can process these payload parts, without having to parse them.

The PayloadInfo element has the following child element:

• eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo
  This element occurs zero or more times. The PartInfo element is used to reference a MIME attachment, an XML element within the SOAP Body, or another resource which may be obtained by resolving a URL, according to the value of the href attribute, described below.

13. eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo

This element has the following attribute:

• eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo/@href
  This OPTIONAL attribute has a value that is the [RFC2392] Content-ID URI of the payload object referenced, an xml:id fragment identifier, or the URL of an externally referenced resource; for example, "cid:foo@example.com" or "#idref". The absence of the attribute href in the element eb:PartInfo indicates that the payload part being referenced is the SOAP Body element itself. For example, a declaration of the following form simply indicates that the entire SOAP Body is to be considered a payload part in this ebMS message:

<eb:PayloadInfo>

<eb:PartInfo/>

</eb:PayloadInfo>

Any other namespace-qualified attribute MAY be present. A Receiving MSH MAY choose to ignore any foreign namespace attributes other than those defined above.

The designer of the business process or information exchange using ebXML Messaging decides what payload data is referenced by the Manifest and the values to be used for xlink:role.

This element has the following child elements:

• eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo/eb:Schema
  This element occurs zero or more times. It refers to schema(s) that define the instance document identified in the parent PartInfo element. If the item being referenced has schema(s) of some kind that describe it (e.g. an XML Schema, DTD and/or a database schema), then the Schema element SHOULD be present as a child of the PartInfo element. It provides a means of identifying the schema and its version defining the payload object identified by the parent PartInfo element. This metadata MAY be used to validate the Payload Part to which it refers, but the MSH is NOT REQUIRED to do so. The Schema element contains the following attributes:

• (a) namespace - the OPTIONAL target namespace of the schema

• (b) location – the REQUIRED URI of the schema

• (c) version – an OPTIONAL version identifier of the schema.

• eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo/eb:PartProperties
  This element has zero or more eb:Property child elements. An eb:Property element is of xs:anySimpleType (e.g. string, URI) and has a REQUIRED @name attribute, the value of which must be agreed between partners. Its actual semantics is beyond the scope of this specification. The element is intended to be consumed outside the ebMS specified functions. It may contain meta-data that qualifies or abstracts the payload data. A representation in the header of such properties allows for more efficient monitoring, correlating, dispatching and validating functions (even if these are out of scope of ebMS specification) that do not require payload access.

Example:

<eb:PartProperties>

<eb:Property name="Description">Purchase Order for 11 widgets</eb:Property>

<eb:Property name="MimeType">application/xml</eb:Property>

</eb:PartProperties>

Full PayloadInfo Example:

<eb:PayloadInfo>

<eb:PartInfo href="cid:foo@example.com">

<eb:Schema location="http://example.org/bar.xsd" version="2.0"/>

<eb:PartProperties>

<eb:Property name="Description">Purchase Order for 11 widgets</eb:Property>

<eb:Property name="MimeType">application/xml</eb:Property>

</eb:PartProperties>

</eb:PartInfo>

<eb:PartInfo href="#goo_payload_id">

<eb:Schema location="http://example.org/bar.xsd" version="2.0"/>

<eb:PartProperties>

<eb:Property name="Description">Purchase Order for 100 widgets</eb:Property>

<eb:Property name="MimeType">application/xml</eb:Property>

</eb:PartProperties>

</eb:PartInfo>

</eb:PayloadInfo>

3. eb:Messaging/eb:SignalMessage

This element is an alternative to the eb:UserMessage element. It has two child elements:

• eb:Messaging/eb:SignalMessage/eb:MessageInfo
  This REQUIRED element is similar to eb:MessageInfo as defined for user messages.

• eb:Messaging/eb:SignalMessage/eb:[SignalName]
  This REQUIRED element defines the nature of the ebMS signal. There is only one eb:[SignalName] child element when [SignalName]=PullRequest or [SignalName]=Receipt. There may be several children elements when SignalName=Error.

An ebMS signal does not require any SOAP Body: if the SOAP Body is not empty, it MUST be ignored by the MSH, as far as interpretation of the signal is concerned.

1. eb:Messaging/eb:SignalMessage/eb:PullRequest

This element has the following attribute:

• eb:Messaging/eb:SignalMessage/eb:PullRequest/@mpc
  This OPTIONAL attribute identifies the Message Partition Channel from which the message is to be pulled. The absence of this attribute indicates the default MPC.

2. eb:Messaging/eb:SignalMessage/eb:Error

The eb:Error element MAY occur zero or more times. For its complete specification, refer to Section 6.

3. eb:Messaging/eb:SignalMessage/eb:Receipt

The eb:Receipt element MAY occur zero or one times; and, if present, SHOULD contain a single ebbpsig:NonRepudiationInformation child element, as defined in the ebBP Signal Schema [ebBP-SIG]. The value of eb:MessageInfo/eb:RefToMessageId MUST refer to the message for which this signal is a receipt.

4. Message Unit Bundling

When the eb:Messaging element contains multiple children elements, i.e. multiple Message Units (either User Message Units or Signal Message Units), this is called Message Unit bundling. The following general rules govern Message Unit bundling:

Note:
Other use cases for bundling may be considered in a forthcoming Part 2 of this specification, resulting in changes to these rules, potentially allowing for multiple User Message Units or multiple Signal Message Units of the same type.

• The eb:Messaging element MUST NOT contain more than one eb:UserMessage element.

• The eb:Messaging element MAY contain multiple eb:SignalMessage elements, in addition to an optional eb:UserMessage element, but MUST NOT contain more than one Signal Message Unit of the same type.

The following is a non-exhaustive list of valid bundling cases:

1. eb:Messaging element with the following children:

• an eb:UserMessage element

• an eb:SignalMessage element with an eb:PullRequest child

2. eb:Messaging element with the following children:

• an eb:UserMessage element

• an eb:SignalMessage element with one or more eb:Error children

3. eb:Messaging element with the following children:

• an eb:UserMessage element

• an eb:SignalMessage element with an eb:PullRequest child

• an eb:SignalMessage element (distinct from the previous one) with one or more eb:Error children

4. eb:Messaging element with the following children:

• an eb:SignalMessage element with an eb:PullRequest child

• an eb:SignalMessage element (distinct from the previous one) with an eb:Receipt child

With regard to MEP transport channel bindings, the following restrictions must be observed:

• An ebMS Message containing an eb:SignalMessage/eb:PullRequest element cannot bind to the back-channel of the underlying transport protocol, regardless of its bundling context (bundling cases (a) , (c) or (d)) i.e. even if it is also a User Message. For example, such a message can neither appear as "reply" in the Sync transport channel binding, nor as a "oneway" in the Pull transport channel binding.

• An ebMS Message containing an eb:SignalMessage/eb:PullRequest element and a User Message unit (case (a) or case (c)) cannot act as a "request" in the Sync transport channel binding, as the semantics of this combination would require sending back two User Messages units over the back-channel, which is a bundling case not supported in this release.

3. Examples of ebMS Messages

The following listings provide examples of various types of ebMS messages: UserMessage, PullRequest Signal, Error Signal, Receipt Signal and a "bundled" message.

Note:
The examples are depicted using the SOAP 1.1 envelope; however, SOAP 1.2 could have been used instead, with the appropriate namespace adjustment. In that case, the contents of the eb:Messaging header would be the same, with the exception of the attribute eb:Messaging/@S11:mustUnderstand, which becomes eb:Messaging/@S12:mustUnderstand, having a boolean value of "true" instead of the integer value "1".

1. UserMessage Example

The following is an example of an ebMS Request User Message packaged in a SOAP 1.1 envelope:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<eb:UserMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-1@requester.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:PartyInfo>

<eb:From>

<eb:PartyId>uri:requester.example.com</eb:PartyId>

<eb:Role>http://example.org/roles/Buyer</eb:Role>

</eb:From>

<eb:To>

<eb:PartyId type="someType">QRS543</eb:PartyId>

<eb:Role>http://example.org/roles/Seller</eb:Role>

</eb:To>

</eb:PartyInfo>

<eb:CollaborationInfo>

<eb:AgreementRef>http://registry.example.com/cpa/123456</eb:AgreementRef>

<eb:Service type="MyServiceTypes">QuoteToCollect</eb:Service>

<eb:Action>NewPurchaseOrder</eb:Action>

<eb:ConversationId>4321</eb:ConversationId>

</eb:CollaborationInfo>

<eb:MessageProperties>

<eb:Property name="ProcessInst">PurchaseOrder:123456</eb:Property>

<eb:Property name="ContextID"> 987654321</eb:Property>

</eb:MessageProperties>

<eb:PayloadInfo>

<eb:PartInfo href="cid:part@example.com">

<eb:Schema location="http://registry.example.org/po.xsd" version="2.0"/>

<eb:PartProperties>

<eb:Property name="Description">Purchase Order for 11 Widgets</eb:Property>

<eb:Property name="MimeType">application/xml</eb:Property>

</eb:PartProperties>

</eb:PartInfo>

</eb:PayloadInfo>

</eb:UserMessage>

</eb:Messaging>

</S11:Header>

<S11:Body>

</S11:Body>

</S11:Envelope>

The following is an example of a possible Response to the above User Message:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<eb:UserMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-2@responder.example.com</eb:MessageId>

<eb:RefToMessageId>UUID-1@requester.example.com</eb:RefToMessageId>

</eb:MessageInfo>

<eb:PartyInfo>

<eb:From>

<eb:PartyId type="someType">QRS543</eb:PartyId>

<eb:Role>http://example.org/roles/Seller</eb:Role>

</eb:From>

<eb:To>

<eb:PartyId>uri:requester.example.com</eb:PartyId>

<eb:Role>http://example.org/roles/Buyer</eb:Role>

</eb:To>

</eb:PartyInfo>

<eb:CollaborationInfo>

<eb:AgreementRef>http://registry.example.com/cpa/123456</eb:AgreementRef>

<eb:Service type="MyServiceTypes">QuoteToCollect</eb:Service>

<eb:Action>PurchaseOrderResponse</eb:Action>

<eb:ConversationId>4321</eb:ConversationId>

</eb:CollaborationInfo>

<eb:PayloadInfo>

<eb:PartInfo href="cid:part@example.com">

<eb:Schema location="http://registry.example.org/poc.xsd" version="2.0"/>

<eb:PartProperties>

<eb:Property name="Description">Purchase Order Confirmation</eb:Property>

<eb:Property name="MimeType">application/xml</eb:Property>

</eb:PartProperties>

</eb:PartInfo>

</eb:PayloadInfo>

</eb:UserMessage>

</eb:Messaging>

</S11:Header>

<S11:Body>

</S11:Body>

</S11:Envelope>

2. PullRequest Message Example

The following is an example of a PullRequest Signal Message:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<eb:SignalMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-2@initiator.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:PullRequest mpc="http://msh.example.com/mpc123" />

</eb:SignalMessage>

</eb:Messaging>

</S11:Header>

<S11:Body/>

</S11:Envelope>

3. Error Message Example

The following is an example of an Error Signal Message:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<eb:SignalMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-2@receiver.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:Error origin="ebMS" category="Content"

errorCode="EBMS:0001" severity="failure"

refToMessageInError="UUID-1@sender.example.com">

<eb:Description xml:lang="en">Value not recognized</eb:Description>

</eb:Error>

<eb:Error origin="Security" category="Processing" errorCode="0101"

severity="failure" refToMessageInError="UUID-23@esender.fxample.com">

<eb:Description xml:lang="en">Failed Authentication</eb:Description>

</eb:Error>

</eb:SignalMessage>

</eb:Messaging>

</S11:Header>

<S11:Body/>

</S11:Envelope>

4. Receipt Message Example

The following is an example a Receipt Signal Message, as described in Section 5.2.3.3:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">

<S11:Header>

<eb:Messaging xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd"

xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

xmlns:ebbpsig="http://docs.oasis-open.org/ebxml-bp/ebbp-signals-2.0">

<eb:SignalMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-01T13:42:37.429Z</eb:Timestamp>

<eb:MessageId>uiwtoruiopwr2543890@b.example.com</eb:MessageId>

<eb:RefToMessageId>uiopfdsmnf4898965563434@a.example.com</eb:RefToMessageId>

</eb:MessageInfo>

<eb:Receipt>

<ebbpsig:NonRepudiationInformation>

<ebbpsig:MessagePartNRInformation>

<ebbpsig:MessagePartIdentifier></ebbpsig:MessagePartIdentifier>

<ds:Reference URI="http://b.example.com/doc45/#b">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>fX/iNylcUHNLV4lCE0eC7aEGP28=</ds:DigestValue>

</ds:Reference>

</ebbpsig:MessagePartNRInformation>

<ebbpsig:MessagePartNRInformation>

<ebbpsig:MessagePartIdentifier></ebbpsig:MessagePartIdentifier>

<ds:Reference URI="http:/a.example.com/doc23/#a">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>fX/iNylcUHNLV4lCE0eC7aEGP28=</ds:DigestValue>

</ds:Reference>

</ebbpsig:MessagePartNRInformation>

</ebbpsig:NonRepudiationInformation>

</eb:Receipt>

</eb:SignalMessage>

</eb:Messaging>

</S11:Header>

<S11:Body/>

</S11:Envelope>

5. "Bundled" Message Example

The following is an example a User Message unit bundled with both PullRequest and Error Signal Message units, as described in Section 5.2.4:

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">

<S11:Header>

<eb:Messaging S11:mustUnderstand="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<eb:SignalMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-2@receiver.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:Error origin="ebMS" category="Content"

errorCode="EBMS:0001" severity="failure"

refToMessageInError="UUID-1@sender.example.com">

<eb:Description xml:lang="en">Value not recognized</eb:Description>

</eb:Error>

<eb:Error origin="Security" category="Processing" errorCode="0101"

severity="failure" refToMessageInError="UUID-23@esender.fxample.com">

<eb:Description xml:lang="en">Failed Authentication</eb:Description>

</eb:Error>

</eb:SignalMessage>

<eb:SignalMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-2@initiator.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:PullRequest mpc="http://msh.example.com/mpc123" />

</eb:SignalMessage>

<eb:UserMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-07-25T12:19:05</eb:Timestamp>

<eb:MessageId>UUID-1@requester.example.com</eb:MessageId>

</eb:MessageInfo>

<eb:PartyInfo>

<eb:From>

<eb:PartyId>uri:requester.example.com</eb:PartyId>

<eb:Role>http://example.org/roles/Buyer</eb:Role>

</eb:From>

<eb:To>

<eb:PartyId type="someType">QRS543</eb:PartyId>

<eb:Role>http://example.org/roles/Seller</eb:Role>

</eb:To>

</eb:PartyInfo>

<eb:CollaborationInfo>

<eb:AgreementRef>http://registry.example.com/cpa/123456</eb:AgreementRef>

<eb:Service type="MyServiceTypes">QuoteToCollect</eb:Service>

<eb:Action>NewPurchaseOrder</eb:Action>

<eb:ConversationId>4321</eb:ConversationId>

</eb:CollaborationInfo>

<eb:MessageProperties>

<eb:Property name="ProcessInst">PurchaseOrder:123456</eb:Property>

<eb:Property name="ContextID"> 987654321</eb:Property>

</eb:MessageProperties>

<eb:PayloadInfo>

<eb:PartInfo href="cid:foo@example.com">

<eb:Schema location="http://registry.example.org/bar.xsd" version="2.0"/>

<eb:PartProperties>

<eb:Property name="Description">Purchase Order for 11 widgets</eb:Property>

<eb:Property name="MimeType">application/xml</eb:Property>

</eb:PartProperties>

</eb:PartInfo>

</eb:PayloadInfo>

</eb:UserMessage>

</eb:Messaging>

</S11:Header>

<S11:Body/>

</S11:Envelope>

6. Error Handling

Error handling must take into account the composed nature of an MSH, which includes relatively independent (SOAP) modules such as those handling reliability and security. Error reporting is also subject to the same connectivity constraints as the exchange of regular messages. This calls for a more comprehensive error model. With regard to different ways to report errors, this model must allow for a clear distinction between what is relevant to an agreement, and what is relevant to immutable interoperability requirements.

Error generation and error reporting are treated here as orthogonal concepts. While the generation of errors is a matter of conformance, the reporting of errors may be subject to an agreement. Consequently, the way errors are to be reported is specified in the P-Mode (P-Mode.ErrorHandling feature) that results from such an agreement.

1. Terminology

• Fault: A Fault always means a SOAP Fault. It must be generated and processed according to the [SOAP11] or [SOAP12] specification.

• Error: An error that is not a SOAP Fault, and occurs in one of the defined modules (ebMS Module, Reliability Module, Security Module).

• ebMS Error: This is a particular case of Error, which is generated by the ebMS Module in conformity with this specification.

• Reliability Error: This is a particular case of Error, generated by the Reliability Module.

• Security Error: This is a particular case of Error, generated by the Security Module.

• Escalated ebMS Error: This is an ebMS Error that originates in a module other than the ebMS Module (i.e. Security module, or Reliability module).

• ebMS Error Generation: The operation of creating an ebMS Error object based on some failure or warning condition.

• ebMS Error Reporting: The operation of communicating an ebMS Error object to some other entity.

• Message-in-error: A flawed message causing an error of some kind.

2. Packaging of ebMS Errors

   1. eb:Error Element

An ebMS Error is represented by an eb:Error XML infoset, regardless of the way it is reported. Each error raised by an MSH has the following properties:

• origin (optional attribute)

• category (optional attribute)

• errorCode (required attribute)

• severity (required attribute)

• refToMessageInError (optional attribute)

• shortDescription (optional attribute)

• Description (optional element)

• ErrorDetail (optional element)

Example:

<eb:Error origin="ebMS" category="Unpackaging"

shortDescription="InvalidHeader"

errorCode="EBMS:0009" severity="fatal">

<eb:Description xml:lang="en"> … </eb:Description>

</eb:Error>

2. eb:Error/@origin

This OPTIONAL attribute identifies the functional module within which the error occurred. This module could be the the ebMS Module, the Reliability Module, or the Security Module. Possible values for this attribute include "ebMS", "reliability", and "security". The use of other modules, and thus their corresponding @origin values, may be specified elsewhere, such as in a forthcoming Part 2 of this specification.

3. eb:Error/@category

This OPTIONAL attribute identifies the type of error related to a particular origin. For example: Content, Packaging, UnPackaging, Communication, InternalProcess.

4. eb:Error/@errorCode

This REQUIRED attribute is a unique identifier for the type of error.

5. eb:Error/@severity

This REQUIRED attribute indicates the severity of the error. Valid values are: warning, failure.

The warning value indicates that a potentially disabling condition has been detected, but no message processing and/or exchange has failed so far. In particular, if the message was supposed to be delivered to a consumer, it would be delivered even though a warning was issued. Other related messages in the conversation or MEP can be generated and exchanged in spite of this problem.

The failure value indicates that the processing of a message did not proceed as expected, and cannot be considered successful. If, in spite of this, the message payload is in a state of being delivered, the default behavior is not to deliver it, unless an agreement states otherwise (see OpCtx-ErrorHandling). This error does not presume the ability of the MSH to process other messages, although the conversation or the MEP instance this message was involved in is at risk of being invalid.

6. eb:Error/@refToMessageInError

This OPTIONAL attribute indicates the MessageId of the message in error, for which this error is raised.

7. eb:Error/@shortDescription

This OPTIONAL attribute provides a short description of the error that can be reported in a log, in order to facilitate readability.

8. eb:Error/Description

This OPTIONAL element provides a narrative description of the error in the language defined by the xml:lang attribute. The content of this element is left to implementation-specific decisions.

9. eb:Error/ErrorDetail

This OPTIONAL element provides additional details about the context in which the error occurred. For example, it may be an exception trace.

3. ebMS Error Message

When reported as messages, ebMS Errors are packaged as ebMS Signal Messages. Several eb:Error elements MAY be present under eb:SignalMessage. If this is the case, and if eb:RefToMessageId is present as a child of eb:SignalMessage/eb:MessageInfo, then every eb:Error element MUST be related to the ebMS message (message-in-error) identified by eb:RefToMessageId.

If the element eb:SignalMessage/eb:MessageInfo does not contain eb:RefToMessageId, then the eb:Error element(s) MUST NOT be related to a particular ebMS message.

For an example of an ebXML Error Message, see Section 5.3.3.

4. Extensibility of the Error Element

   1. Adding new ebMS Errors

The errorCode attribute (eb:Messaging/eb:SignalMessage/eb:Error/@errorCode) must be an identifier that is unique within the scope of an MSH. ebMS Errors in addition to those specified here may be added by creating new errorCode values. The value of the errorCode attribute must begin with the five characters "EBMS:".

5. Generating ebMS Errors

This specification identifies key ebMS Errors, as well as the conditions under which they must be generated. Some of these error-raising conditions include the escalation as ebMS Errors of either Faults or Errors generated by Reliability and Security modules. These modules could be those contained in the MSH raising the Error, or those contained in a remote MSH communicating with the MSH raising the Error. Except for some cases defined in this specification, Error escalation policies are left to an agreement between users, represented in the processing mode of an MSH (P-Mode.ErrorHandling).

6. Error Reporting

There are three primary means of Error Reporting:

• Reporting with Fault Sending: An MSH may generate a SOAP Fault for reporting ebMS processing errors of severity "failure", which prevent further message processing. This Fault must comply with SOAP Fault processing, i.e. be sent back as an HTTP response in case the message in error was over an HTTP request. In case of ebMS processing errors (see Section 6.7.1), the Fault message MUST also include the eb:SignalMessage/eb:Error element in the eb:Messaging header.

• Reporting with Notification: An out-of-band transfer of error information from MSH to some entity (message producer, consumer, or any other entity, be it local or remote). In case of notification to the message Producer or Consumer, such reporting action is abstracted by the "Notify" operation in the messaging model.

• Error message: an ebMS signal message sent from one MSH to another, which contains at least one eb:Error element. Such a reporting action is modeled by Send and Receive abstract operations over such a message. The reporting message must always be combined with a SOAP Fault unless the severity is "warning".

Example of different options in reporting errors raised on a Sending MSH: Some error detected on a submitted message and before it is even packaged, would normally be locally notified to the message Producer, and not even reported to the destination MSH. However, in case this message was part of a larger exchange that is holding its state waiting for completion on the receiving side, the preferred policy could state that the message-in-error be also reported (using an error message) to the Receiving MSH. If the Receiving MSH is getting its messages as responses to PullRequest signals, such ebMS errors can be transmitted as responses to these signals. If user messages are pushed sender to receiver, it could be decided that errors generated on the sender side will be pushed like any regular message.

Example of different options in reporting errors raised on a Receiving MSH: If a Receiving MSH detects an error in a received message, the reporting policy may vary depending on the context and the ability of parties to process such errors. For example, the error-raising Receiving MSH may just notify its own Consumer party, or send back an error message to the Sending MSH, or both. The usual common requirement in all these cases, is that the error be reported somehow, and complies with the eb:Error element structure.

Appendix E shows possible options for combining error reporting with ebMS MEPs, when binding to a two-way protocol such as HTTP. It also shows how these combinations can be controlled with P-Mode parameters.

7. Standard ebMS Errors

This section defines the standard error codes expected to be generated and processed by a conformant MSH. They are segmented according to the stage of processing they are likely to occur: during reliable message processing, security processing, and general ebMS processing.

1. ebMS Processing Errors

The table below describes the Errors that may occur within the ebMS Module itself (ebMS Errors that are not Escalated Errors), i.e. with @origin="ebms". These errors MUST be supported by an MSH, meaning generated appropriately, or understood by an MSH when reported to it.

2. Security Processing Errors

The table below describes the Errors that originate within the Security Module, i.e. with @origin="security". These errors MUST be escalated by an MSH, meaning generated appropriately, or understood by an MSH when reported to it.

3. Reliable Messaging Errors

The table below describes the Errors that originate within the Reliable Messaging Module, i.e. with @origin="reliability". These errors MUST be escalated by an MSH, meaning generated appropriately, or understood by an MSH when reported to it.

7. Security Module

The ebXML Messaging Service, by its very nature, presents certain security risks. A Messaging Service may be at risk by means of:

• Unauthorized access

• Data integrity and/or confidentiality attacks (e.g. through man-in-the-middle attacks)

• Denial-of-Service and spoofing

Each security risk is described in detail in the ebXML Technical Architecture Risk Assessment Technical Report [ebRISK].

Each of these security risks may be addressed in whole, or in part, by the application of one, or a combination, of the countermeasures described in this section. This specification describes a set of profiles, or combinations of selected countermeasures, selected to address key risks based upon commonly available technologies. Each of the specified profiles includes a description of the risks that are not addressed.

Application of countermeasures SHOULD be balanced against an assessment of the inherent risks and the value of the asset(s) that might be placed at risk.

1. Security Element

Web Services Security 1.0 [WSS10] or 1.1 [WSS11] can be utilized to secure an ebMS message. Web Services Security provides three mechanisms to secure messages: ability to send security tokens as part of a message, message integrity and message confidentiality.

Zero or one Security elements per target, belonging to the Web Services Security-defined namespace, MAY be present as a child of the SOAP Header. The Security element MUST be namespace qualified in accordance with Web Services Security. The structure and content of the Security element MUST conform to the Web Services Security specification and the Web Services Security SOAP Messages with Attachments Profile [SOAPATTACH].

To promote interoperability the security element MUST conform to the WS-I Basic Security Profile Version 1.0 [WSIBSP10], and WS-I Attachments Profile Version 1.0 [WSIAP10].

Note
An MSH implementation may elect to leverage WSS 1.0 and/or or WSS 1.1. Note that the security of attachment defined in WSS 1.1 is not only applicable to SOAP 1.1; security of attachment is orthogonal to the SOAP version, even though all examples in the WSS 1.1 specification depict only the SOAP 1.1 variant when securing attachments. In other words, an MSH may secure a SOAP 1.2 with Attachments message in the same way a SOAP 1.1 with Attachment can be secured in WSS 1.1. Refer to Section C for complete details of the ebMS SOAP binding.

This specification outlines the use of Web Services Security x.509 Certificate Token Profile [WSS10-X509] or [WSS11-X509] and the Web Services Security Username Token Profile [WSS10-USER] or [WSS11-USER]. An MSH implementation MAY choose to support other Web Services Security Profiles.

2. Signing Messages

Signing of ebMS Messages is defined in Web Services Security [WSS10] and [WSS11]. Support for WSS X.509 Certificate Token Profile is REQUIRED to sign a message.

It is REQUIRED that compliant MSH implementations support Detached Signatures as defined by the XML Signature Specification [XMLDSIG].

An MSH implementation MAY support Enveloped Signatures as defined by the XML Signature Specification. Enveloped Signatures add an additional level of security in detecting the addition of XML elements to the SOAP Header. The use of Enveloped Signatures may limit the ability of intermediaries to process messages.

To ensure the integrity of the user-specified payload data and ebMS message headers it is RECOMMENDED that the entire eb:Messaging Container Element and the SOAP Body be included in the signature.

3. Signing SOAP with Attachments Messages

Application payloads that are are built in conformance with the [SOAPATTACH] specification may be signed. To sign a SOAP with Attachment message the Security element must be built in accordance with WSS 1.1.

It is REQUIRED that compliant MSH implementations support the Attachment-Content-Only transform. It is RECOMMENDED that compliant MSH implementations support the Attachment-Complete transform.

To ensure the integrity of the user-specified payload data and ebMS headers it is RECOMMENDED that the entire eb:Messaging Container Element, and all MIME Body parts of included payloads are included in the signature.

4. Encrypting Messages

Encryption of ebMS Messages is defined in Web Services Security [WSS10] and [WSS11]. Support for Web Services Security X.509 Certificate Token Profile is REQUIRED to encrypt message.

An MSH Implementation may encrypt the eb:Messaging Container Element. It may also encrypt select child elements of the eb:Messaging header, leaving other elements unencrypted. For example, the eb:PartyInfo section may be used to aid in message routing before decryption of other elements has occurred. Therefore, when third-party routing of a message is expected, it is RECOMMENDED that the eb:PartyInfo section not be encrypted. To ensure the confidentiality of the user-specified payload data, it is RECOMMENDED that the SOAP Body be encrypted.

5. Encrypting SOAP with Attachments Messages

Application payloads that are are built in conformance with the [SOAPATTACH] specification may be encrypted. To encrypt a SOAP with Attachment message the Security element must be built in accordance to WSS 1.1. To ensure the confidentiality of the user-specified payload data it is RECOMMENDED that the MIME Body parts of included payloads be encrypted.

6. Signing and Encrypting Messages

When both signature and encryption are required of the MSH, the message MUST be signed prior to being encrypted.

7. Security Token Authentication

In constrained environments where management of XML digital signatures is not possible, an authentication alternative that is based on Web Services Security Username Token Profile is RECOMMENDED to be supported, and MAY include support for wsse:PasswordText-type passwords. The value of the wsse:UserName element is an implementation issue. The "user" may represent the MSH itself, or may represent a party using the MSH. In the latter case, there is no requirement that this user name be identical to some eb:From/PartyId value.

An MSH MAY support other types of Security Tokens, as allowed by the WS-Security family of standards.

8. Security Policy Errors

A responding MSH MAY respond with an error if a received ebMS message does not meet the security policy of the responding MSH. For example, a security policy might indicate that messages with unsigned parts of the SOAP Body or eb:Messaging Container element are unauthorized for further processing. If a responding MSH receives a message with unsigned data within the SOAP Body and error MAY be returned to the initiating MSH.

9. Secured Message Examples

   1. Digitally Signed and Encrypted ebXML Message

Mime-Version: 1.0

Content-Type: text/xml

Content-Transfer-Encoding: binary

SOAPAction: ""

Content-Length: 7205

<?xml version="1.0" encoding="UTF-8"?>

<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsd="http://www.w3c.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/

http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms-header-3_0-200704.xsd">

<S11:Header xmlns:eb="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/">

<eb:Messaging id="ebMessage" S11:mustUnderstand="1">

<eb:UserMessage>

<eb:MessageInfo>

<eb:Timestamp>2006-10-31T17:36:20.656Z</eb:Timestamp>

<eb:MessageId>UUID-2@msh-server.example.com</eb:MessageId>

<eb:RefToMessageId>UUID-1@msh-server.example.com</eb:RefToMessageId>

</eb:MessageInfo>

<eb:PartyInfo>

<eb:From>

<eb:PartyId>uri:msh-server.example.com</eb:PartyId>

<eb:Role>http://example.org/roles/Buyer</eb:Role>

</eb:From>

<eb:To>

<eb:PartyId type="someType">QRS543</eb:PartyId>

<eb:Role>http://example.org/roles/Seller</eb:Role>

</eb:To>

</eb:PartyInfo>

<eb:CollaborationInfo>

<eb:AgreementRef>http://msh-server.example.com/cpa/123456</eb:AgreementRef>

<eb:Service type="someType">QuoteToCollect</eb:Service>

<eb:Action>NewPurchaseOrder</eb:Action>

<eb:ConversationId>2a81ffbd-0d3d-4cbd-8601-d916e0ed2fe2</eb:ConversationId>

</eb:CollaborationInfo>

<eb:MessageProperties>

<eb:Property name="ProcessInst">PurchaseOrder:123456</eb:Property>

<eb:Property name="ContextID">987654321</eb:Property>

</eb:MessageProperties>

<eb:PayloadInfo>

<eb:PartInfo href="#enc">

<eb:Description xml:lang="en-US">PO Image</eb:Description>

</eb:PartInfo>

</eb:PayloadInfo>

</eb:UserMessage>

</eb:Messaging>

<wsse:Security S11:mustUnderstand="1"

xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"

xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<wsse:BinarySecurityToken

EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"

ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"

wsu:Id="signingCert">...</wsse:BinarySecurityToken>

<wsse:BinarySecurityToken

EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"

ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"

wsu:Id="encryptionCert">...</wsse:BinarySecurityToken>

<enc:EncryptedKey xmlns:enc="http://www.w3.org/2001/04/xmlenc#">

<enc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"

xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"/>

<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">

<wsse:SecurityTokenReference>

<wsse:Reference URI="#encryptionCert"/>

</wsse:SecurityTokenReference>

</KeyInfo>

<CipherData xmlns="http://www.w3.org/2001/04/xmlenc#">

<CipherValue>F3HmZ2Ldyn0umLCx/8Q9B9e8OoslJx9i9hOWQjh6JJwYqDLbdg0QVFiVT1LVjazlThS9m9rkRtpkhCUIY1xjFKtDsuIIAW8cLZv7IHkVoDtQ7ihJc8hYIlEESX9qZN65JgyAa3BYgW9ipjGHtNgZ9RzUdzKdeY74DFm27R6m8b0=</CipherValue>

</CipherData>

<ReferenceList xmlns="http://www.w3.org/2001/04/xmlenc#">

<DataReference URI="#enc"/>

</ReferenceList>

</enc:EncryptedKey>

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

<ds:SignedInfo>