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:
- It builds the
eb:MessageHeaderwith a neweb:MessageIdand timestamp, and adds theeb:Manifestthat references each part. - It adds the
eb:AckRequestedandeb:SyncReplyheader blocks, which instruct the receiving message service handler to return its acknowledgment in the HTTP response to the same request. - It packages the message as MIME multipart and sends it.
- It returns the parsed header of the acknowledgment. Its
ref_to_message_idis theeb:MessageIdof the message that was sent, and itsattachmentscontain 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:
The message receives one XML signature in the SOAP header, as the ebMS 2.0 specification defines it:
- The first reference covers the envelope, without the signature itself and without the header blocks addressed to the next message service handler.
- Each subsequent reference covers one payload part, identified by its
cid:URI and digested over its bytes. - 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
- NHS Spine and Norsk Helsenett - the networks that use these exchanges