ebMS Implementation Guidelines

See section 1.6.2 for the naming conventions for the CPA ID element.

The naming conventions for the PartyId element are still under development by STAR.

The CollaborationRole elements are the heart of the CPA. They are used to define the trading characteristics for each transaction.   In the sample CPA shown in Appendix A, each Collaboration Role element is associated with a STAR BOD using the ProcessSpecification element. The structure of the CollaborationRole element is shown in Figure 2.2, “Collaboration Role Structure”.

Figure 2.2. Collaboration Role Structure

The ProcessSpecification element defines the BOD type. The value of the name attribute should match the name attribute in the BPSS document for that BOD.

<tns:ProcessSpecification tns:name="PartsOrder" tns:uuid="urn:icann:star.org:bpid:3A4$2.0" tns:version="2.0" xlink:href="http://www.vwoa.com/po_processing/" xlink:type="simple"/>

The role names are defined using the Role element. Again, the Role names should match those in the BPSS document for the BOD. Currently STAR has defined the role names “Initiator” and “Responder” for all BOD types.

<<tns:Role tns:name="Initiator" xlink:href="http://www.starstandard.org/processes/3A4.xml#Initiator" xlink:type="simple"/>

The CPA was designed with two CollaborationRole elements per BOD to allow different messaging and transport parameters to be defined depending on whether the party is acting as the Initiator or the Responder for a transaction.

The ServiceBinding element defines the Service and Action elements that appear in the ebMS message header

The Service Element is defined using the BOD Noun value. For example, the ServiceElement for a PartsOrder collaboration role would be “PartsOrder”.

<tns:ServiceBinding>

        <tns:Service tns:type="string">PartsOrder</tns:Service>

The CanSend and CanReceive elements define the ebXML actions associated with each collaboration. The ebXML action element corresponds to the STAR BOD verb that will be supported by each party. The ThisPartyActionBinding element within the CanSend or CanReceive element is used to indicate the supported action. The OtherPartyActionBinding element is a reference to the ID of the other party’s corresponding CanReceive element.

For example, if Party A is an OEM acting as the “Responder” and we are defining the collaboration for the PartsOrder BOD, the OEM would be capable of sending an “Acknowledge” verb and receiving a “Process” verb. The CanSend element would contain “Acknowledge” in the ThisPartyActionBinding element and the ID of Party 2’s corresponding CanReceive element in the OtherPartyActionBinding element. The CanReceive element would contain “Process” in the ThisPartyActionBinding element and the ID of Party 2’s corresponding CanSend element.

CanSend element for Responder collaboration role

<tns:CanSend>

        <tns:ThisPartyActionBinding tns:action="Acknowledge" tns:id="SendPOAck" tns:packageId="DefaultComposite">







        <tns:OtherPartyActionBinding>Party2_ReceiveAckPO</tns:OtherPartyActionBinding>

CanReceive element for Responder collaboration role

<tns:CanReceive>

        <tns:ThisPartyActionBinding tns:action="Process" tns:id="ReceivePO" tns:packageId="DefaultPackage">







        <tns:OtherPartyActionBinding>Dealer_SendPO</tns:OtherPartyActionBinding>

The attributes contained in the BusinessTransactionCharacteristics element will be negotiated and defined by each party according to their individual requirements.

The ChannelId element contains the identifier for the delivery channel that will be used to send or receive the BOD defined for a particular collaboration. The STAR CPA contains 14 delivery channel definitions. Each definition defines a different set of transport and message delivery parameters. Each party will determine the appropriate delivery channel types for each of the BODs that they support and assign the required delivery channel using the ChannelId element.

The certificate section of the STAR CPA is defined using the standard constructs as defined in the ebCPPA 2.0 specifications document.

As stated above, the STAR CPA contains 14 pre-defined channel types that can be used to define the delivery parameters for any collaboration activity by inserting the appropriate ID into the ChannelID element.

The STAR CPA contains 3 pre-defined DocExchange elements, each of which defines a different set of encryption and non-repudiation settings. A DocExchange ID is associated with Delivery Channel type definition.

The STAR CPA contains a single transport definition for a standard HTTP connection. Additional transport definitions may defined to support SSL or SMTP transports as needed.

To enable Best-Effort an ebMS message is sent without using any of the ebMS reliable messaging features, in other words, for the sender:

To enable At-Least-Once an ebMS message sender:

To enable At-Most-Once an ebMS message sender:

Implementers MUST provide and use the following features:

Message Routing in ebMS can be accomplished through a combination of the underlying Transfer protocol, data elements in the messages themselves and out-of-band agreements as determined by ebXML CPPA.

Routing at the Transfer level is defined by HTTP URLs. At the message level, parties can key off the ToParty, FromParty, Service, Action and CPAID elements. At the CPPA level, “return addresses” can be defined. Parties may use a combination of these attributes to route messages in a way that makes sense for differing business scenarios or system architectures.

Receipt of an acknowledgment indicates that the original message reached its destination. In other words, an Acknowledgment signifies only that a message has been received securely and intact, it is not a business level Acknowledgment.

ebMS clearly defines the format and content of Acknowledgment messages.

Although ebMS Acknowledgment messages are typically stand-alone messages, this is not required; an Acknowledgment to a message could be returned as part of a synchronous reply, as a stand-alone asynchronous message or as a part of a separate business message exchange.

An ebMS Acknowledgment contains a RefToMessageID, which is the exact MessageID of the original message, i.e. the message that is being acknowledged. This allows the sender of the original message to cross-reference the original message and confirm delivery.

As an option an ebMS Acknowledgment can be signed, which allows the sender to validate that the specific intended party received the message. Optionally, a signed message can contain a digest of the original message, allowing for full Non-repudiation of receipt. In other words, the sender knows who received the message and the sender can prove that the message was received exactly as sent.

Content Integrity is provided in ebMS through the use of XML Digital Signature. An original message can be signed, allowing the receiver to validate that the contents of the message have not been altered. In addition, as mentioned above, ebMS Acknowledgements may be signed and may include a digest of the original message, allowing for Non-repudiation of receipt, in other words the sender can prove that the message was received by the intended receiver exactly as sent.

The ebMS TimeToLive element is a UTC (Universal Time Code). TimeToLive is a required message element for Once-And-Only-Once / Exactly-Once message delivery. If a receiver determines that the TimeToLive has expired, it must return an error and not process the message.

ebMS supports the ability to order multiple messages, guaranteeing that the messages are processed in order.

Message Ordering is set using the SequenceNumber element which is a positive integer that must be unique within a ConversationID. ConversationIDs must be unique within a CPA (Collaborative Partner Agreement) ID. Effectively, two parties establish one or more contexts for messaging in a Partner Agreement, which may also include such Policies as Delivery Assurance levels and security parameters. Within this Policy context, unique Conversations are established and sequences of messages (message 1, message 2, message 3,) can be sent.

A receiver MUST not process a message until all messages in the Conversation with lower sequence numbers have been received and processed.

If a message is received out of sequence, the receiver MUST format and send an error message notifying the sender.

ebMS defines error handling at the SOAP level (SOAP Faults) and at the ebMS level with an error listing mechanism that provides for both errors and warnings.

In the context of STAR Reliable Messaging, ebMS provides support for Retry, Recovery, TimeOut and Duplicate Detection.

ebMS supports retransmission of unacknowledged messages. As described above, At-Least-Once and Once-And-Only-Once / Exactly-Once require the ability to resend messages. ebMS requires sending implementations to store outbound messages and resend them if an Acknowledgement is not received within an agreed upon TimeOut period. The resent message is intended to be exactly the same as the original message and at the very least it must have the exact same ConversationID and MessageID.

To support Retry and Duplicate Elimination, ebMS requires senders to store outbound messages and requires receivers to store inbound messages in a persistent store. Receivers must maintain inbound messages for a period of time agreed upon in a CPA Policy element known as PersistDuration. ebMS recommends that the persistent stores be durable (maintain information through a system failure) and resilient enough to survive the failure of any single software or hardware component. In the case of system failure, messages must be processed as if the system failure had not occurred.

ebMS supports TimeOut through an out-of-band agreement based on CPPA. Parties use CPPA to agree on values for Retries (NumberOfRetries) and RetryInterval. Implementations are expected to follow the policy agreements; if a message is sent and not acknowledge within the RetryInterval the sender will retry the message Retries number of times.

ebMS Supports Duplicate Detection through a combination of policy agreements and data elements in individual messages.

Parties agree via CPPA whether or not to use DuplicateElimination. To support duplicate elimination receivers are required to durably store MessageIDs. Individual messages that require DuplicateElimination must contain the DuplicateElimination element.

If a receiver determines a message is a duplicate, it must not forward the message for processing and it must return to the sender a copy of the original acknowledgment that was sent concerning the original message.

If an MSH is given data by an application needing to be sent reliably to the recipient, the MSH MUST do the following:

            The message MUST have a globally unique MessageID.

Here is the sample of Reliable Messaging elements in ebMS message.

…

<eb:MessageHeader>

        …

        <eb:MessageData>

        <eb:MessageId>PartsOrder.323210:e5c74:7ffc@sender.com</eb:MessageId>

        <eb:Timestamp>2003-10-31T12:22:30</eb:Timestamp>

        <eb:TimeToLive>2003-11-01T12:22:30</eb:TimeToLive>

        </eb:MessageData>

</eb:MessageHeader>

<eb:AckRequested

        SOAP-ENV:mustUnderstand="1" eb:signed="true" eb:version="2.0"/>

<eb:DuplicateElimination/>

…

If an AckRequested element is present in the received message then the receiver should generate an Acknowledgment Message is only performed when DuplicateElimination tag is present in the incoming message.

Here is a sample Acknowledgement message that is sent back to the party that sent the AckRequested.

<eb:Acknowledgment SOAP:mustUnderstand="1" eb:version="2.0">

<eb:Timestamp>2001-03-09T12:22:30</eb:Timestamp>

<eb:RefToMessageId>PartsOrder.323210:e5c74:7ffc@sender.com</eb:RefToMessageId>

<eb:From>

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

</eb:From>

</eb:Acknowledgment>