| Standards for Technology in Automotive Retail |
| Home - News Feed

Chapter 3. Implementing ebMS Reliable Messaging
Prev |  | Next

## Chapter 3. Implementing ebMS Reliable Messaging

## 3.1. Implementing ebMS Reliable Messaging

### 3.1.1. ebMS Delivery Assurance Profiles

This section describes how to implement the Delivery Assurance profiles with ebMS version 2.0 and CPPA version 2.0.

#### 3.1.1.1. Best-Effort

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

- NO Acknowledgment is requested (AckRequested element is not present)

- NO Duplicate Elimination is requested (DuplicateElimination element is not present)

- NO TimeToLive is specified (TimeToLive element is not present)

- Failed messages are not retried

#### 3.1.1.2. At-Least-Once (Message Acknowledgement)

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

- MUST request an Acknowledgment (AckRequested element is present)

- NO Duplicate Elimination requiested (DuplicateElimination element is not present)

- SHOULD specify TimeToLive (TimeToLive element is present)

- MUST retry failed messages

#### 3.1.1.3. At-Most-Once (NOT recommended by STAR for simplicity)

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

- MUST not request an Acknowledgment (AckRequested element is not present)

- MUST request Duplicate Elimination (DuplicateElimination element is present)

- SHOULD specify TimeToLive (TimeToLive element is present)

- MAY retry failed messages

- Parties MUST agree out-of-band to a value for RetryInterval

- Parties MUST agree out-of-band to a value for NumberOfRetries

#### 3.1.1.4. Once-And-Only-Once / Exactly-Once (Guaranteed Delivery)

Implementers MUST provide and use the following features:

- MUST include an AckRequested element

- MUST include a DuplicateElimination element

- MUST include a TimeToLive element and the value of TimeToLive must conform to TimeToLive > Timestamp + ((NumberOfRetries + 1) * RetryInterval)

- Parties MUST agree out-of-band to a value for RetryInterval

- Parties MUST agree out-of-band to a value for NumberOfRetries

### 3.1.2. ebMS Delivery Assurance Features

#### 3.1.2.1. Message Routing

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.

#### 3.1.2.2. Acknowledgment of Receipt

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.

### 3.1.3. ebMS Message Integrity

#### 3.1.3.1. Content Integrity

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.

#### 3.1.3.2. TimeToLive

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.

#### 3.1.3.3. Message Sequencing

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.

#### 3.1.3.4. ebMS Standardized Error Handling and Monitoring

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.

#### 3.1.3.5. Retry

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.

#### 3.1.3.6. Recovery Processes / Message Store

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.

#### 3.1.3.7. TimeOut

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.

#### 3.1.3.8. Duplicate Detection

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.

### 3.1.4. ebMS CPA Configuration and Examples

A CPA (Collaborative Partner Agreement) is an XML document which represents an agreement between exactly two parties who will exchange ebXML messages. This agreement defines the names of the parties involved and the messaging characteristics they will be using. ebXML message exchanges can have various reliability and security modes and can be synchronous or asynchronous. CPA’s are uniquely identified in messages using an element named CPAID.

The CPAID attribute of the CollaborationProtocolAgreement element identifies the CPA to the messaging server. It can have any form but the recommendation is to concatenate party names in alphabetical order separated by a dash. For example "ABMotorCo-DEMotorCo". For example:

<tp:CollaborationProtocolAgreement

Xmlns:tp=http://www.oasis-open.org/committees/ebXML-cppa/schema/cpp-cpa-2_0.xsd

xsi:schemaLocation=”http://www.oasis-open.org/committees/ebxml-cppa/schema/cpp-cpa-

tp:cpaid=” ABMotorCo-DEMotorCo” tp:version=”2_0a”>

The CPA provides two elements for configuring reliable messaging agreements. The ReliableMessaging tag and the MessagingCharacteristics tag.

The ReliableMessaging tag insures message handlers will create and manage AckRequest and Acknowlegment tags in the ebMS message. Without this tag, by default "Best-Effort" or no reliability is used in the message exchange. Thus optional tp:ReliableMessaging element under tp:ebXMLSenderBinding and tp:ebXMLReceiverBinding will be required in the implementation.

The ReliableMessaging Tag in the CPA can be configured as follows:

<tp:ReliableMessaging>

<tp:Retries>5</tp:Retries>

<tp:RetryInterval>PT2H</tp:RetryInterval>

<tp:MessageOrderSemantics>NotGuaranteed</tp:MessageOrderSemantics>

</tp:ReliableMessaging>

The MessagingCharacteristics in the CPA can be configured as follows:

<tp:MessagingCharacteristics

tp:syncReplyMode="none"

tp:ackRequested="always"

tp:ackSignatureRequested="none"

tp:duplicateElimination="always"/>

</tp:DeliveryChannel>

#### 3.1.4.1. ebMS Once-And-Only-Once Sending Message Behavior

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

1. Create a message from components received from the application

The message MUST have a globally unique MessageID.

1. Insert an AckRequested element

2. Save the message in persistent storage

3. Send the message to the recipient

4. Wait for the return of an Acknowledgment Message acknowledging receipt of this specific message and, if it does not arrive before RetryInterval has elapsed, the message must be resent until an acknowledgment is received or the NumberOfRetries has been reached. If a communications protocol error is encountered, then take appropriate error handling action.

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/>

…

#### 3.1.4.2. ebMS Once-And-Only-Once Receiving Message Behavior

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>

Prev |  | Next
Chapter 2. Implementing the CPA | Home | Chapter 4. Implementing ebMS Message-Level Security