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

Chapter 1. ebMS Messaging
Prev |  | Next

## Chapter 1. ebMS Messaging

## 1.1. ebMS Messaging

### 1.1.1. ebMS Message Packaging

An ebMS Message is a MIME/Multipart message envelope referred to as a Message Package. The Message Package is structured in compliance with [SOAP] version 1.1 and SOAP Messages with Attachments [SwA] specifications.

There are two or more logical MIME parts within a Message Package:

1. The Header Container contains one SOAP version 1.1 compliant message that holds the ebMS Header elements. The large majority of ebMS Headers are placed in the SOAP Header, if any Manifest or SOAP Fault elements occur they are placed in the SOAP Body.

2. Payload Containers, which contain application level payloads. For the STAR XML Infrastructure project, these will consist mostly of STAR BODs.

### 1.1.2. Message Packaging

Figure 1.1. ebMS Message Package

Highlights of this packaging format:

- Based on a widely accepted industry de-facto standard SOAP v1.1

- Transport Metadata such as To/From Parties and MessageIDs can be placed in the SOAP Header

- Messages can be simple SOAP messages or more complex messages with multiple payloads

### 1.1.3. Payload Containers

ebMS version 2.0 and the STAR Transport require that if any payloads are present they MUST be contained in a Payload Container and MUST be referenced by a Header Manifest element entry. Payloads may be composed of any type of data including and not limited to word processor files, graphics, sound, EDI, XML or any data that can be digitized. In the context of the STAR XML Infrastructure project, the payloads will primarily be STAR BODs.

### 1.1.4. STAR ebMS Guidelines Message Elements

The ebMS Element Summary table (shown below) identifies the critical ebMS message elements for STAR ebMS Guideline. These elements were identified for the original STAR Message Infrastructure Guidelines and have been updated to account for changes between ebMS version 1.0 and ebMS version 2.0.

Element / Attribute Name Required Required if Present (Optional) [attribute] default | Infrastructure Sample/Recommendation
Content-Type | text/xml
Charset | UTF-8
?xml |
[version=”1.0”] |
([encoding]) | UTF-8
SOAP-ENV:Header |
MessageHeader |
[SOAP:mustUnderstand=”1”] |
[version=”2.0”] |
([id]) |
From |
PartyID | Logical identifier
[type] | DUNS, string
(Role) | Agreed to by both parties, if CPA is used, value must match CPA
To |
PartyID | Logical identifier
[type] | DUNS, string
Role | Agreed to by both parties, if CPA is used, value must match CPA
CPAId | If no CPA exists, FromPartyId-ToPartyId-cpa[-x.x]
ConversationId | Timestamp + unique host identifier
Service [type] | For BOD Payloads: STARBOD
Service | For BOD Payloads: STAR BOD Noun
Action | For BOD Payloads: STAR BOD Verb
MessageData |
MessageId | Service Name concatenated with a period (.) followed by the GUID, followed by an at sign (@) followed by the company name in domain name format. Must conform to [RFC2392]
Timestamp | UTC with no offsets. Represents the time the message was created.
RefToMessageID (Required for Error or Acknowledgement or Pong) | MessageId from earlier message
TimeToLive |
MessageOrder |
AckRequested |
[SOAP:mustUnderstand=”1”] |
[signed] | false or true
[version=”2.0”] |
[SOAP:actor=”urn:oasis:names:tc:ebxml- msg:actor:ToPartytMSH”] |
Acknowledgement |
[SOAP:mustUnderstand=”1”] |
[SOAP:actor=”urn:oasis:names:tc:ebxml- msg:actor:nextMSH”] | If present, must match this value
[version=”2.0”] |
[id] |
Timestamp | UTC with no offsets, represents the time the Acknowledgment was created
RefToMessageID | MessageID of message being acknowledged
ErrorList Element |
[SOAP:mustUnderstand=”1”] |
[highestSeverity=(Error I Warning)] |
[version=”2.0”] |
[id] |
Error |
[codeContext=”URI” (default=” http://www.ebxml.org/messageServiceErrors ”) |
errorCode=(ValueNotRecognized I NotSupported I Inconsistent I OtherXml I |
DeliveryFailure I TimeToLiveExpired I SecurityFailure I MimeProblem I Unknown ) |
severity=(Warning I Error) |
location (Xpointer I CID) |
xml:lang=”en-US” |
Id] |
ds:Signature | Must confirm to the [XMLDSIG] specification.
SOAP-ENV:Body | Every direct child of SOAP-ENV:Body has an automatic attribute of SOAP-ENV:mustUnderstand=”1”. (see SOAP 1.1 sect 4.3.1)
Manifest | Required if one or more payloads (i.e. ebXML wrapped BOD) are present
[version=”2.0”] |
[id] |
Reference |
[xlink:href] | URI of the payload object referenced.
[xlink:type=”simple”] |
[id] |
Schema |
[location] | /STAR/Rev1.2/BODs/Standalone/ProcessPartsOrder.xsd
[version] |
Description |
xml:lang=”en-US” |
StatusRequest |
[version=”2.0”] |
[id] |
RefToMessageId | MessageId from earlier message
StatusResponse |
[version=”2.0”] |
RefToMessageId | MessageId of the original message being reported on
TimeStamp | The Timestamp of the original message being reported on
[messageStatus= (UnAuthorized | NotRecognized | Received | Processed | Forwarded] | MessageId of the original message being reported on
[id] |

### 1.1.5. ebMS MessageHeader Elements

#### 1.1.5.1. From/To PartyId Elements

Within the ebMS MessageHeader, the REQUIRED From and To elements include a PartyId element which identifies the sending or receiving party for the message. The PartyId element value is defined by the PartyId type attribute. Commonly used types are the Uniform Resource Identifier (URI) and the Uniform Resource Name (URN), however a generic string type is also allowed providing that it is understood by both parties. STAR recommends the use of the following PartyId types:

- For OEMs and large institutions: The urn:duns type if a DUNS number is available

- For Automotive Dealers: A string type containing the short manufacturer code followed by the dealer number

- For Non-Automotive Dealers: A string type containing unique identification information.

Examples:

Example of a Volkswagen OEM: <eb:PartyId type=”urn:duns”>006972475</eb:PartyId>

Example of a Volkswagen Automotive Dealer: <eb:PartyId type=”string”>VW400110</eb:PartyId>

#### 1.1.5.2. CPAId Element

The CPAId element is a REQUIRED ebXML element. It is a string that identifies the parameters governing the exchange of messages between the parties. The recipient of a message MUST be able to resolve the CPAId to an individual set of parameters, taking into account the sender of the message. This does NOT mean that a formal CPA conforming to the ebXML CPA specification must be in place for ebXML messaging to be used. If no formal CPA exists, the CPAId is simply the location of party specific information such as IP addresses and dealer Ids. This is a temporary format until party id formats can be established in a future versions of this publication.

For STAR, the CPAId element shall have the following format:

<CPAId>fromPartyId-ToPartyId-cpa</CPAId>

The CPAId may also optionally contain a version number:

<CPAId>fromPartyId-ToPartyId-cpa-x.x</CPAId>

Examples:

<eb:CPAId>VW400110-006942475-cpa</eb:CPAId> <eb:CPAId>VW400110-006942475-cpa-1.0</eb:CPAId>

#### 1.1.5.3. ConversationId Element

The REQUIRED ConversationId element is a string identifying the set of related messages that make up a conversation between two Parties. It MUST be unique within the From and To party pair. The Party initiating a conversation determines the value of the ConversationId element that SHALL be reflected in all messages pertaining to that conversation. The value for ConversationId in the STAR XML Infrastructure environment SHOULD be datestamp + timestamp + a unique host identifier; UTC format is used for datestamp. For example, if two salespeople at the same dealership submit an inquiry at the same time (obviously from separate terminals), then the algorithm to generate the ConversationId should be such that this situation would generate two separate ConversationIds.

The ConversationId enables the recipient of a message to identify the instance of an application or process that generated or handled earlier messages within a conversation. It remains constant for all messages within a conversation.

#### 1.1.5.4. Service and Action Elements

The REQUIRED Service and Action elements identify the service that acts on the message.

For STAR XML Infrastructure, the value of the type attribute of the Service element for messages that contain a STAR BOD payload MUST be “STARBOD” and the value of the Service element MUST be the STAR BOD Noun. The value of the Action element MUST be the STAR BOD Verb.

Exceptions to this include ebMS standalone error messages and asynchronous acknowledgments, whose Service Action values are defined by ebMS version 2.0.

An example of the Service and Action elements for an STAR BOD payload follows:

<eb:Service eb:type=”STARBOD”>PartsOrder</eb:Service> <eb:Action>Process</eb:Action>

#### 1.1.5.5. MessageData Element

The REQUIRED MessageData element provides a means of uniquely identifying an ebMS message.

MessageId element

Message IDs MUST be Globally unique and conformant to ebMS specifications which require that the value is conformant to RFC2392.

STAR requires three (3) data elements within the Message ID:

1. Company Name, in domain name format, for example starstandards.org

2. Service Identifier, the name of the service being invoked

3. A Globally Unique Identifier (GUID), as specified in RFC2822 section 3.6.4

The Service Name should be concatenated with a period (.) followed by the GUID, followed by an at sign (@) followed by the company name in domain name format.

Example:

<eb:MessageId>PartsOrder.323210:e5c74:7ffc@starstandards.org</eb:MessageId>

Timestamp element

The REQUIRED Timestamp is a value representing the creation time of the message header and MUST be in UTC format (Universal Time Code as defined by ISO 8601).

#### 1.1.5.6. Digital Signature

A STAR ebMS Message can be digitally signed to provide security countermeasures. Application of Digital Signature is a Recommendation, in other words, conformant implementations should be capable of processing messages with Digital Signature, but individual implementations may choose not to use Digital Signature features.

#### 1.1.5.7. Manifest Element

The Manifest is a composite element that summarizes message payloads. A Manifest element MUST be present if one or more Payloads exist, and all Payloads MUST be referenced in the Manifest. The purpose of the Manifest is:

- To make it easier to directly extract a particular payload

- To allow an application to determine whether it can process a payload without having to parse it

The structure and content of the Manifest element MUST conform to the ebMS version 2.0 specifications.

#### 1.1.5.8. Acknowledgment Element

The Acknowledgment element is used by the To Party that received a message, to let the From Party that sent the message know the message was received. The RefToMessageId in a message containing an Acknowledgment element identifies the message for which the receipt is being generated. The RefToMessageId is the MessageId of the original message.

Prev |  | Next
I.VI. References | Home | Chapter 2. Implementing the CPA