SOAP industry profiles

Health networks and public registries publish profiles that define the SOAP version, the security mechanisms, the attachment packaging and the addressing headers of every exchange.

Configuration common to all profiles

Every profile is implemented with the same three objects, created in the Dashboard:

1. An outgoing SOAP connection, under Connections > Outgoing > SOAP, holds the address of the endpoint, the SOAP action and, on its SOAP tab, the SOAP version and the WS-Addressing and MTOM checkboxes.
2. A WS-Security definition, under Security > WS-Security, holds the credentials, keys and certificates of the exchange, and is assigned to the connection on its Security tab.
3. The Client certificate and Client key fields on the same Security tab provide mutual TLS for networks that authenticate clients at the transport layer.

Systems that submit messages to Zato connect to a SOAP channel, under Connections > Channels > SOAP, which accepts the same SOAP versions and packaging.

The profiles differ only in which of these settings they require. The platform adds envelopes, security headers and attachments from this configuration when invoke runs.

Immunization registries (CDC IIS)

U.S. state and city immunization registries implement the SOAP interface that the CDC publishes for immunization information systems (IIS). The interface defines the connectivityTest and submitSingleMessage operations, and HL7 v2 messages, such as VXU submissions and QBP queries, are transmitted as text in the SOAP body.

A WS-Security definition in UsernameToken mode stores the credentials that the registry issued, and two rows on the connection's Body credentials tab, username and password in that order, write them as the first elements of the operation during invoke:

request = SOAPMessage()
request.namespace = 'urn:cdc:iisb:2014'
request.hl7Message = 'MSH|^~\\&|MYAPP|MYFAC|IIS|STATE|20260115||VXU^V04^VXU_V04|123|P|2.5.1'

response = self.soap['State Registry'].invoke('submitSingleMessage', request)

A system that accepts submissions over the same interface is a SOAP channel whose service reads request.hl7Message and returns the HL7 acknowledgment in acknowledgment. The channel replies in the SOAP version of each request and reports validation errors raised by the service as faults of the same version.

IHE document exchange

The IHE profiles define document exchange between healthcare organizations: XDS.b for document submission and retrieval, XCA for cross-community access and XUA for user assertions. TEFCA and eHealth Exchange in the United States, gematik ePA in Germany and the Swiss EPD are based on these profiles and use the transport requirements of the IHE technical framework.

The SAML definition uses the Issuer and Subject that the network agreement assigns, and its Signing key and Signing certificate chain sign each assertion. With the definition assigned and both checkboxes enabled, the service submits the document as bytes:

request = SOAPMessage()
request.namespace = 'urn:ihe:iti:xds-b:2007'
request.Document = document_bytes

response = self.soap['Document Exchange'].invoke('ProvideAndRegisterDocumentSet', request)

status = response.ProvideAndRegisterDocumentSetResponse.status

The request is sent as a SOAP 1.2 envelope with wsa:Action and wsa:MessageID headers, a signed SAML assertion in wsse:Security and the document as an MTOM part.

A repository that accepts submissions is a SOAP channel with the version set to 1.2 and MTOM enabled for responses. The receiving tutorial implements such a repository with document submission as its example.

ebXML networks

NHS Spine and Norsk Helsenett exchange messages in ebXML Message Service 2.0 (ebMS 2.0). Messages are sent with the invoke_ebxml method of an outgoing SOAP connection, which uses SOAP 1.1, the default version of every connection. The platform builds the eb:MessageHeader and eb:Manifest and packages the payloads as MIME parts, as ebXML messaging describes.

The two networks differ in the layer they protect. NHS Spine authenticates the message handler at the TLS layer, and Norsk Helsenett protects each payload with a signature and encryption.

NHS Spine

NHS Spine is the national service that connects health and care systems in England. Its asynchronous exchanges identify both parties with NHS party identifiers and refer to the CPA that each party agreed during onboarding.

The connection presents the client certificate and key issued for the endpoint, and the call provides the Spine identifiers:

info = EbXMLInfo()
info.from_party = 'my-party-id'
info.from_party_type = 'urn:nhs:names:partyType:ocs+serviceInstance'
info.to_party = 'spine-party-id'
info.to_party_type = 'urn:nhs:names:partyType:ocs+serviceInstance'
info.cpa_id = 'S2001919A2011852'
info.conversation_id = self.cid
info.service = 'urn:nhs:names:services:pdsquery'
info.action = 'QUPA_IN000006UK02'

part = Part()
part.content_id = 'payload-1'
part.content_type = 'application/xml'
part.data = hl7v3_query

ack = self.soap['Spine MHS'].invoke_ebxml(info, [part])

Norsk Helsenett

Health messaging in Norway uses the ebXML framework of the national health network. The Norwegian profile requires each payload to be signed by the sender and encrypted for the recipient.

The WS-Security definition holds the Signing key and Signing certificate chain of the sender, the Peer certificate of the recipient, and the Decryption key and Trust anchors for replies. The call is built as for NHS Spine, with HER-ids as the party identifiers and both protections enabled:

ack = self.soap['Helsenett'].invoke_ebxml(info, [part], sign=True, encrypt=True)

Each payload is signed and then encrypted for the recipient. The signatures and the wrapped content keys are placed in the security header of the message.

Learn more