ebXML messaging

Exchange ebMS 2.0 messages from your services - parties, payloads, synchronous acknowledgments and message signing.

ebXML Message Service 2.0 (ebMS 2.0) is the messaging standard of several national health networks, including NHS Spine in England and Norsk Helsenett in Norway. An ebMS message is a SOAP 1.1 envelope. Its header contains an eb:MessageHeader that identifies the parties, the service and the action, its body contains an eb:Manifest that references the payloads, and the payloads are transmitted as MIME parts alongside the envelope.

ebXML messages are sent through outgoing SOAP connections with the invoke_ebxml method, which accepts the parameters of the exchange and the payload parts.

Send a message

# -*- coding: utf-8 -*-

# Zato
from zato.common.soap.ebxml import EbXMLInfo
from zato.common.util.xml_.mime_ import Part
from zato.server.service import Service

class SendPatientRecord(Service):

    name = 'demo.ebxml.send-patient-record'

    def handle(self) -> 'None':

        # Parties, service and action of the exchange
        info = EbXMLInfo()
        info.from_party = 'my-organization'
        info.to_party = 'their-organization'
        info.cpa_id = 'cpa-123'
        info.conversation_id = self.cid
        info.service = 'urn:example:records'
        info.action = 'SubmitRecord'

        # Roles that the CPA assigns to each party
        info.from_role = 'Sender'
        info.to_role = 'Receiver'

        # The business payload is a MIME part
        part = Part()
        part.content_id = 'payload-1'
        part.content_type = 'application/xml'
        part.data = b'<PatientRecord>...</PatientRecord>'

        # Send and read the acknowledgment
        conn = self.soap['Health Network']
        ack = conn.invoke_ebxml(info, [part])

        self.logger.info('Acknowledged, ref: %s', ack.ref_to_message_id)

Zato performs the following steps for each call:

  1. It builds the eb:MessageHeader with a new eb:MessageId and timestamp, and adds the eb:Manifest that references each part.
  2. It adds the eb:AckRequested and eb:SyncReply header blocks, which instruct the receiving message service handler to return its acknowledgment in the HTTP response to the same request.
  3. It packages the message as MIME multipart and sends it.
  4. It returns the parsed header of the acknowledgment. Its ref_to_message_id is the eb:MessageId of the message that was sent, and its attachments contain the payload parts of the reply, if the reply has any.

If the receiver responds with an ebMS error message, the call raises SOAPException with the error codes and descriptions from its eb:ErrorList. The call also raises SOAPException if the acknowledgment refers to a message other than the one that was sent.

Party identifiers that require a type attribute, such as the NHS urn:nhs:names:partyType:... values, are set in info.from_party_type and info.to_party_type. A service that is not an absolute URI requires a type as well, which is set in info.service_type.

The CPA (Collaboration Protocol Agreement) is the agreement that two parties establish before they exchange messages. Its identifier is set in info.cpa_id and sent in the eb:CPAId element. The remaining terms of the CPA, including the endpoint, certificates and signing, are configured in the outgoing SOAP connection and in the parameters of the call.

Sign messages

A CPA with non-repudiation of origin requires each message to be signed by the sender. Signing is enabled through a parameter of the call:

ack = conn.invoke_ebxml(info, [part], sign=True)

The message receives one XML signature in the SOAP header, as the ebMS 2.0 specification defines it:

  1. The first reference covers the envelope, without the signature itself and without the header blocks addressed to the next message service handler.
  2. Each subsequent reference covers one payload part, identified by its cid: URI and digested over its bytes.
  3. The signer's certificate is included in the signature, so that the receiver can match it against the certificate in the CPA.

The signing key and the certificate are taken from the Signing key and Signing certificate chain fields of the WS-Security definition assigned to the connection.

Mutual TLS

ebMS endpoints commonly require authentication at the transport layer as well. The connection's Client certificate and Client key fields provide it, configured as described for other SOAP connections.

Learn more