SanteDB HL7v2 Implementation
Last updated
Last updated
Any implementation of HL7 Version 2 messaging has its own method of processing messages, and SanteDB is no different. This page discusses the particulars of the SanteDB's implementation of the HL7v2 message specification.
SanteDB uses HL7 Version 2.5 as its internal canonical model for HL7 messages. All services in SanteDB's HL7 layer are implemented using Version 2.5 structures, and wire versions are translated to/from that version.
Because of this implementation, HL7v2.5 is the latest version of messaging supported by SanteDB.
SanteDB supports common HL7 Version 2.5 transports including:
TCP Sockets -> Raw messages sent over a simple TCP socket, containing no special control characters.
Lower Layer Protocol -> Unsecured TCP socket which uses the LLP control characters (VT, FS, CR, etc.) for delineation of message boundaries.
Secure Lower Layer Protocol -> A TLS wrapped TCP socket which uses the LLP control characters. This transport also supports client authentication.
Each service in the HL7 message handler defines an address
attribute which has a URI. The scheme of this URI dictates the selected transport for messaging. The schemes for this URI are:
Each service also requires the definition for which trigger events and which handlers should be used on that particular service endpoint which are configured using the <handler>
element.
When using the TLS option, you must provide an <sllp>
element, which controls how the encryption for the channel is setup.
A simple encrypted channel over SLLP where no client authentication is required is configured as:
Within an HL7 message, identifiers using the CX
datatype (composite identifier) carry an fourth component which indicates the authority under which the identity was assigned.
Whenever the CX.4
component carry a simple value such as: 304-304-203^^^SSN
the namespace ID is mapped to the DomainName
property of an assigning authority. In this case, SanteDB would search its data store for a configured assigning authority with DomainName
of SSN.
Whenever the CX.4
component carries a universal identifier, such as : 304-304-203^^^&2.16.840.1.113883.4.1&ISO
the SanteDB server will map the CX.4.2
to the Oid
property of the assigning authority.
When using both a NamespaceID and a UniversalID , for example: 304-304-203^^^SSN&2.16.840.1.113883.4.1&ISO
then SanteDB will ensure that both components agree on the authority to be resolved.
Some older PACS systems do not include clearly specified identity domains in the CX.4
, for example, if a sender issues a request such as:
The SanteDB instance must attempt to resolve the authority under which RJ-438
is registered. To do this, the SanteDB server will attempt to locate any assigning authority which the authenticated application principal is permitted to assign. In this case the assigning application would be PACS
. If more than one candidate authority is located, then a CR
indicating ambiguous authorities were found.
In order for no namespace resolution to be enabled, the value of strictCx4
in the configuration must be set to false
If your deployment uses the PID-19
field to convey a national social security number, you must configure the ssnAuthority
element in your HL7 configuration which links the SSN authority with a registered identity domain. For example, in the US to configure PID-19
to use the built-in SSN authority name:
This will allow the resolution of the simple string in PID-19
to map to an authority.
If your deployment uses PID-19
to map to another identity such as national social insurance number, etc. you should modify the ssnAuthority
element to match.
When SanteDB responds or receives a message in HL7v2, it is possible to reference the UUID for the object using the PID-3
segment if the localAuthority
element is configured.
For example, to allow a client to explicitly merge two discrete records (known UUIDS) on the SanteDB server, with the configuration above, the source system would send:
The built-in HL7 message process or supports the following Query By Parameter (QBP) triggers:
Trigger | QPD Field | Notes |
---|---|---|