Skip to content

PIX Query

Transaction to get the master patient ID of a patient in a community using the local ID.

Overview

Primary systems shall use this transaction to retrieve the master patient ID (XAD-SPID) for patients the primary systems wants to retrieve or provide documents for. In the Swiss EPR the IHE PIX V3 profile and transactions shall be used to retrieve the master patient ID.

To retrieve the master patient ID for the patient to access the patients EPR, the the primary system shall perform a Patient V3 Query [ITI-45]. Within the query request the primary system shall provide the local ID of the patient in the primary system, as well as the data source parameter of the assigning authority of the community and the the assigning authority EPR-SPID. The local ID must match the local ID the primary system registered the patient with (see PIX Feed).

If the patient is registered in the community, the community sends a response with the master patient ID (XAD-PID) and the EPR-SPID.

Transaction

Message Semantics

Messages are encoded as described in the HL7 V3 standard with restrictions defined in the IHE PIX V3 Query profile and the ordinances to the Swiss EPR.

Request Message

Due to the genericity of the underlying HL7 V3 standard, the request message is quite lengthy. A raw version of a request message may be found here.

For a step by step interpretation of the request message, see section below.

Message Interpretation

The request message is not complex in nature, but quite lengthy due to the genericity of the HL7 V3 standard.

The SOAP Header element shall convey the following information:

  • To element: The URL of the provide and register document set service.
  • MessageID element: a UUID of the message.
  • Action element: The SOAP action identifier of the request as defined in the IHE ITI Technical Framework.

Optional elements may be included according to the specification in the W3C SOAP specification.

SOAP header
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
  <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
   https://epd-test.ith-icoserve.com:7443/PIXPDQ/services/PIXPDQV3ManagerService
  </wsa:To>
  <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">urn:uuid:c12e1f14-c2c9-4a94-ba27-6411e8c90b75</wsa:MessageID>
  <wsa:ReplyTo xmlns:wsa="http://www.w3.org/2005/08/addressing">
   <wsa:Address>http://www.w3.org/2005/08/addressing/anonymous</wsa:Address>
  </wsa:ReplyTo>
  <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing" env:mustUnderstand="1">urn:hl7-org:v3:PRPA_IN201309UV02</wsa:Action>
 </env:Header>

For the PIX query no Security header element is required, since in the Swiss EPR the access to the patient data is authorized for all applications, which are registered in the community and authenticate with a client certificate (see section Security Requirements).

The SOAP Body element conveys the administrative information required for a HL7 V3 PRPA_IN201310UV02 message in HL7 V3 syntax.

Primary systems shall set the following values:

  • creationTime: A timestamp in unix time format.
  • sender : The OID of the sender application initiating the request.
  • receiver: The OID of the receiver application which shall respond to the request.
PRPA_IN201309UV02 message
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  <PRPA_IN201309UV02 xmlns="urn:hl7-org:v3" ITSVersion="XML_1.0">
   <id extension="1694523036420" root="1.3.6.1.4.1.21367.2017.2.7.141"/>
   <creationTime value="20230912131951"/>
   <interactionId extension="PRPA_IN201309UV02" root="2.16.840.1.113883.1.6"/>
   <processingCode code="T"/>
   <processingModeCode code="T"/>
   <acceptAckCode code="AL"/>
   <receiver typeCode="RCV">
    <device classCode="DEV" determinerCode="INSTANCE">
     <id root="1.3.6.1.4.1.21367.2017.2.4.136"/>
    </device>
   </receiver>
   <sender typeCode="SND">
    <device classCode="DEV" determinerCode="INSTANCE">
     <id root="1.3.6.1.4.1.21367.2017.2.2.140"/>
    </device>
   </sender>

The query parameter are encoded in a HL7 V3 controlActProcess element of the message. Primary systems shall set the following query attributes:

  • authorOrPerformer: The OID of the primary system in the id element.
controlActProcess element
30
31
32
33
34
35
36
   <controlActProcess classCode="CACT" moodCode="EVN">
    <code code="PRPA_TE201309UV02" displayName="2.16.840.1.113883.1.6"/>
    <authorOrPerformer typeCode="AUT">
     <assignedPerson classCode="ASSIGNED">
      <id root="1.3.6.1.4.1.21367.2017.2.5.108"/>
     </assignedPerson>
    </authorOrPerformer>

The query parameter are conveyed in the queryByParameter child element:

  • queryId: A unique ID of the query.
  • dataSource: The OID of the assigning authority of the community (line 43).
  • dataSource: The OID of the assigning authority of the EPR-SPID (line 46).
  • patientIdentifier: The ID of the patient data in the primary system, with the OID of the primary system in the root element and the local ID in the extension element.
controlActProcess element
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
    <queryByParameter>
     <queryId extension="1694523036421" root="1.3.6.1.4.1.21367.2017.2.7.141"/>
     <statusCode code="new"/>
     <responsePriorityCode code="I"/>
     <parameterList>
      <dataSource>
       <value root="1.3.6.1.4.1.21367.2017.2.5.93"/>
       <semanticsText>DataSource.id</semanticsText>
      </dataSource>
      <dataSource>
       <value root="2.16.756.5.30.1.127.3.10.3"/>
       <semanticsText>DataSource.id</semanticsText>
      </dataSource>
      <patientIdentifier>
       <value extension="900010" root="1.3.6.1.4.1.21367.2017.2.5.103"/>
       <semanticsText>Patient.id</semanticsText>
      </patientIdentifier>
     </parameterList>
    </queryByParameter>

Response Message

The PIX V3 Feed service responds with the master patient ID (XAD-PID) and the EPR-SPID, the patient is registered with in the community.

The request message is not very complex, but quite lengthy due to the genericity of the HL7 V3 standard. A raw version of a response message may be found here.

Message Interpretation

The SOAP Header element shall conveys the following information:

  • Action element: The SOAP action identifier of the request as defined in the IHE ITI Technical Framework.
  • RelatesTo element: A copy of the unique ID of the query request.
SOAP header
1
2
3
4
5
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
  <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:Action xmlns:mustUnderstand="http://www.w3.org/2003/05/soap-envelope" mustUnderstand:mustUnderstand="1">urn:hl7-org:v3:PRPA_IN201310UV02</wsa:Action>
    <wsa:RelatesTo>urn:uuid:c12e1f14-c2c9-4a94-ba27-6411e8c90b75</wsa:RelatesTo>
  </soapenv:Header>

The SOAP Body element conveys the administrative information required for a PRPA_IN201310UV02 message in HL7 V3 syntax and the query result encoded in the controlActProcess element.

The controlActProcess element conveys the following information for the primary system in the subject child element:

The patient child element conveys the master patient ID (XAD-SPID) and the EPR-SPID as follows:

  • id : The master patient ID (XAD-SPID), with the community OID as the assigning authority in the root and the ID in the extension attribute (line 49).
  • id : The EPR-SPID, with the OID of the ZAS as assigning authority in the root and the ID in the extension attribute (line 50).
registrationEvent element
44
45
46
47
48
49
50
51
52
53
54
55
56
          <ns1:registrationEvent classCode="REG" moodCode="EVN">
            <ns1:id xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" nullFlavor="NA" xsi:type="ns1:II"/>
            <ns1:statusCode code="active"/>
            <ns1:subject1 typeCode="SBJ">
              <ns1:patient classCode="PAT">
                <ns1:id xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" assigningAuthorityName="XDS Affinity Domain" extension="7f2e05e6-673e-44b6-8b76-e17ac58ea80f" root="1.3.6.1.4.1.21367.2017.2.5.93" xsi:type="ns1:II"/>
                <ns1:id xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" assigningAuthorityName="SPID" extension="761337610435209810" root="2.16.756.5.30.1.127.3.10.3" xsi:type="ns1:II"/>
                <ns1:statusCode code="active"/>
                <ns1:patientPerson classCode="PSN" determinerCode="INSTANCE">
                  <ns1:name xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" nullFlavor="NA" xsi:type="ns1:PN"/>
                </ns1:patientPerson>
              </ns1:patient>
            </ns1:subject1>

The custodian child element conveys information on the responding system with the the OID of the provider organization in the id child element as follows:

custodian element
57
58
59
60
61
62
63
64
65
66
            <ns1:custodian typeCode="CST">
              <ns1:assignedEntity classCode="ASSIGNED">
                <ns1:id xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" extension="MyOrgID" root="1.3.6.1.4.1.21367.2010.1.2.600" xsi:type="ns1:II"/>
                <ns1:assignedOrganization classCode="ORG" determinerCode="INSTANCE">
                  <ns1:name xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:EN">
                    <ns1:given>MyOrganisation</ns1:given>
                  </ns1:name>
                </ns1:assignedOrganization>
              </ns1:assignedEntity>
            </ns1:custodian>

Transport Protocol

The primary system shall send the request messages to the registry of the community using the http POST binding as defined in the W3C SOAP specification. It may look like:

1
2
3
4
5
6
POST /PIXV3QueryService HTTP/1.1
Host: company.example.org
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

Audit Log

Primary systems shall store syslog messages to the audit record repository of the community using TLS transport protocol. The audit message uses XML formatting as specified in RFC 3881 with restrictions specified in the IHE ITI TF and the Extension 1 to Annex5 in the ordinances of the Swiss electronic patient record (see Section 1.5 "Requirements on ATNA").

The following snippet shows a example audit message to be written by the primary system:

iti-45-log.xml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<?xml version='1.0' encoding='utf-8'?>
<AuditMessage>
 <EventIdentification EventActionCode="E" EventDateTime="2020-09-30T19:32:55.368Z" EventOutcomeIndicator="0">
  <EventID csd-code="110112" codeSystemName="DCM" originalText="Query"></EventID>
  <EventTypeCode csd-code="ITI-45" codeSystemName="IHE Transactions" originalText="PIX Query"></EventTypeCode>
 </EventIdentification>
 <ActiveParticipant UserID="https://my_primary_system.com/PIXConsumer" AlternativeUserID="201818" UserIsRequestor="true" NetworkAccessPointID="0045e6d09dd0" NetworkAccessPointTypeCode="1">
  <RoleIDCode csd-code="110153" codeSystemName="DCM" originalText="Source Role ID"></RoleIDCode>
 </ActiveParticipant>
 <ActiveParticipant UserID="_SYSTEM" UserIsRequestor="true" NetworkAccessPointID="0045e6d09dd0" NetworkAccessPointTypeCode="1">
  <RoleIDCode csd-code="%All" codeSystemName="HealthShare" originalText="%All"></RoleIDCode>
 </ActiveParticipant>
 <ActiveParticipant UserID="https://ehealthsuisse.ihe-europe.net/PIXManagerService" UserIsRequestor="false" NetworkAccessPointID="ehealthsuisse.ihe-europe.net" NetworkAccessPointTypeCode="1">
  <RoleIDCode csd-code="110152" codeSystemName="DCM" originalText="Destination Role ID"></RoleIDCode>
 </ActiveParticipant>
 <AuditSourceIdentification AuditEnterpriseSiteID="2.16.756.5.30.1.109.6.1.3.1.1" AuditSourceID="my.primary.system.ID">
  <AuditSourceTypeCode csd-code="4"></AuditSourceTypeCode>
 </AuditSourceIdentification>
 <ParticipantObjectIdentification ParticipantObjectID="CHFACILITY22332^^^&amp;1.3.6.1.4.1.12559.11.25.1.19&amp;ISO" ParticipantObjectTypeCode="1" ParticipantObjectTypeCodeRole="1">
  <ParticipantObjectIDTypeCode csd-code="2" codeSystemName="RFC-3881" originalText="Patient Number"></ParticipantObjectIDTypeCode>
  <ParticipantObjectDetail type="II" value="QkMzMjJDQjAtMDM1My0xMUVCLTk5OTQtMDI0MkFDMTQwMDAy"></ParticipantObjectDetail>
 </ParticipantObjectIdentification>
 <ParticipantObjectIdentification ParticipantObjectID="1^^^&amp;BC322C7E-0353-11EB-9994-0242AC140002&amp;ISO" ParticipantObjectTypeCode="2" ParticipantObjectTypeCodeRole="24">
  <ParticipantObjectIDTypeCode csd-code="ITI-45" codeSystemName="IHE Transactions" originalText="PIX Query"></ParticipantObjectIDTypeCode>
  <ParticipantObjectQuery> <!-- omitted for brevity --> </ParticipantObjectQuery>
  <ParticipantObjectDetail type="MSH-10" value="Xl5eJkJDMzIyQ0IwLTAzNTMtMTFFQi05OTk0LTAyNDJBQzE0MDAwMiZJU08="></ParticipantObjectDetail>
 </ParticipantObjectIdentification>
</AuditMessage>

The message is made of the following blocks:

  • EventIdentification: Event related information including the timestamp (line 3 .. 6).
  • ActiveParticipant: Information related to the primary system performing the query (line 7 .. 9).
  • ActiveParticipant: Information on the user initiating the transaction (line 10 .. 12).
  • ActiveParticipant: Information on the responding service endpoint (line 13 .. 15).
  • AuditSourceIdentification: Information related to the primary system performing the query (line 16 .. 18)
  • ParticipantObjectIdentification: Information on the patients EPR accessed (line 19 .. 22)
  • ParticipantObjectIdentification: Request message related information including a BASE-64 encoded copy of the query (line 23 .. 27).

Security Requirements

To ensure privacy the transaction must be secured using https with mutual authentication, with X.509 certificates (extended validation required) and client and server side certificate validation.

Note

  • Some test environments dropped the mutual authentication or TLS for testing purposes. Please contact your test system provider on the details.

Test Opportunity

The transaction can be tested with the test suite of the EPR reference environment, test systems of the EPR communities or the EPR Playground.

Last update: 2024-08-09