Merge pull request #28 from qligier/ql-fixes

Some improvements and fixes
ehealthsuisse · Jan 27, 2025 · 3a4b2a5 · 3a4b2a5
2 parents 0a915a8 + 626a4ae
commit 3a4b2a5
Show file tree

Hide file tree

Showing 11 changed files with 91 additions and 70 deletions.
diff --git a/files/Atna.md b/files/Atna.md
@@ -32,23 +32,27 @@ The first child is a _EventIdentification_ element that describes the transactio
 <EventIdentification EventActionCode="★action_code" EventDateTime="★date_time" EventOutcomeIndicator="★outcome">
   <EventID csd-code="★transaction_code" codeSystemName="DCM" originalText="★transaction_display"/>
   <EventTypeCode csd-code="★type_code" codeSystemName="IHE Transactions" originalText="★type_display"/>
+  <PurposeOfUse csd-code="★puo_code" codeSystemName="2.16.756.5.30.1.127.3.10.5" originalText="★puo_display" />
 </EventIdentification>
 ```
 where:
 
 - `action_code`, `transaction_code`, `transaction_display`,`type_code` and `type_display` depend on the 
   transaction type and are defined in the IHE transaction profile, in the 'Security Considerations' section;
-- `date_time` is the date and time at which the transaction was made. It shall be given in UTC, and shall follow the 
-  xsd:dateTime format;
+- `date_time` is the date and time at which the transaction was made. It shall contain a timezone, and shall follow the 
+  [xsd:dateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime) format;
 - `outcome` describes whether the transaction was successful or not: `0` is a success, `4` is a minor 
   failure, `8` is a serious failure and `12` is a major failure. The choice of the failure type is left to the 
-  implementers.
+  implementers;
+- `puo_code` and `puo_display` are the _Purpose of Use_ code and display name, respectively. It is mandatory when the 
+  transaction is secured by XUA; otherwise, the whole `#!xml <PurposeOfUse>` element shall be omitted.
 
-Then two _ActiveParticipants_ describe the source and destination participants.
+Then, two _ActiveParticipants_ describe the source and destination participants.
 
-=== "First _ActiveParticipant_"
+=== "_ActiveParticipant_ source"
 
-    The first _ActiveParticipant_ describes the source participant, which is the one that has sent the transaction.
+    The first _ActiveParticipant_ describes the source participant, which often is the one that has sent the 
+    transaction (but not always).
     It has the following content:
     ```xml
     <ActiveParticipant UserID="★user_id" AlternativeUserID="★alt_user_id" NetworkAccessPointID="★nap_id" NetworkAccessPointTypeCode="★nap_type" UserIsRequest="true">
@@ -64,10 +68,10 @@ Then two _ActiveParticipants_ describe the source and destination participants.
 
     Other attributes are optional.
 
-=== "Second _ActiveParticipant_"
+=== "_ActiveParticipant_ destination"
 
-    The second _ActiveParticipant_ describes the destination participant, which is the one that has received the 
-    transaction.
+    The second _ActiveParticipant_ describes the destination participant, which often is the one that has received the 
+    transaction (but not always).
     It has the following content:
     ```xml
     <ActiveParticipant UserID="★user_id" NetworkAccessPointID="★nap_id" NetworkAccessPointTypeCode="★nap_type" UserIsRequest="false">
@@ -82,19 +86,26 @@ Then two _ActiveParticipants_ describe the source and destination participants.
 
     Other attributes are optional.
 
+!!! warning
+    In some transactions such as ITI-43, the source and destination participants are reversed. Always check the IHE 
+    specifications for the correct order. The participant "server" is the one having the "SOAP endpoint URI", the 
+    participant "client" is the one having the "process ID".
+
 Following that is the `#!xml <AuditSourceIdentification>` element.
 It contains the following:
 ```xml
-<AuditSourceIdentification AuditEnterpriseSiteID="★oid" />
+<AuditSourceIdentification AuditSourceID="★source" AuditEnterpriseSiteID="★oid" />
 ```
-where `oid` is required and must be an OID of your OID hierarchy.
+where `oid` is required by the [Amendment 1 to Annex 5][annexes] (§1.5.2) and must be an OID of your OID hierarchy.
 Please ask your community if it has requirements about the use of this OID.
-Other attributes are optional.
+The `source` value is required by the standard, but its value choice is left to the implementers;
+it should contain an "_Identifier of the source_".
+You can copy the `oid` value if you want.
 
 ## Requirements for transactions secured by XUA
 
 If the transaction is secured by XUA (like ITI-18, ITI-41, ITI-43), then additional _ActiveParticipants_ shall be 
-specified.
+specified to describe the authenticated participant of the transaction.
 
 === "First _ActiveParticipant_"
 
@@ -185,7 +196,7 @@ where `home_community_id_b64` is the value of the homeCommunityId, base64-encode
   <ParticipantObjectIDTypeCode csd-code="2" codeSystemName="RFC-3881" originalText="Patient Number" />
 </ParticipantObjectIdentification>
 ```
-where `patient_id` is the patient identifier encoded in HL7 CX format (e.g. `value^^^&1.2.3&aISO`).
+where `patient_id` is the patient identifier encoded in HL7 CX format (e.g. `value^^^&1.2.3&ISO`).
 
 ### Submission set
 
@@ -253,4 +264,21 @@ The value must be base64-encoded.
 
 ## Sending an audit log
 
-[Amendment 1 to Annex 5][annexes], §1.5.1
+The audit log shall be sent to the community as a syslog message either over TCP (with TLS).
+The relevant specifications are:
+
+- [RFC 5424](https://tools.ietf.org/html/rfc5424): _The Syslog Protocol_ for information about the syslog message format;
+- [RFC 5425](https://tools.ietf.org/html/rfc5425): _Transport Layer Security (TLS) Transport Mapping for Syslog_ 
+  which formalizes sending Syslog messages over TCP;
+
+The choice of values in the Syslog headers is left to the implementers.
+
+An example of a Syslog message sent over TCP is:
+```
+2027 <85>1 2024-06-25T13:47:57.600Z mag-cara-695f6f7f49-zsxxw IPF 1 IHE+RFC-3881 - <?xml version="1.0" encoding="UTF-8"?><AuditMessage><EventIdentification EventActionCode="E" EventDateTime="2024-06-25T13:47:57.598829760Z" EventOutcomeIndicator="12"><EventID csd-code="110112" codeSystemName="DCM" originalText="Query" /><EventTypeCode csd-code="ITI-67" codeSystemName="IHE Transactions" originalText="Mobile Document Reference Query" /></EventIdentification><ActiveParticipant UserID="/mag-cara/fhir/DocumentReference" UserIsRequestor="true" NetworkAccessPointID="147.87.210.77" NetworkAccessPointTypeCode="2"><RoleIDCode csd-code="110153" codeSystemName="DCM" originalText="Source Role ID" /></ActiveParticipant><ActiveParticipant UserID="https://test.ahdis.ch/mag-cara/fhir/DocumentReference" AlternativeUserID="1" UserIsRequestor="false" NetworkAccessPointID="10.28.2.28" NetworkAccessPointTypeCode="2"><RoleIDCode csd-code="110152" codeSystemName="DCM" originalText="Destination Role ID" /></ActiveParticipant><AuditSourceIdentification AuditEnterpriseSiteID="1.3.6.1.4.1.21367.2017.2.7.109" AuditSourceID="IPF"><AuditSourceTypeCode csd-code="9" codeSystemName="DCM" originalText="Other" /></AuditSourceIdentification><ParticipantObjectIdentification ParticipantObjectID="urn:oid:1.1.1.99.1|215503a0-11d2-4197-822a-053791ab5a8e" ParticipantObjectTypeCode="1" ParticipantObjectTypeCodeRole="1"><ParticipantObjectIDTypeCode csd-code="2" codeSystemName="RFC-3881" originalText="Patient Number" /></ParticipantObjectIdentification><ParticipantObjectIdentification ParticipantObjectID="MobileDocumentReferenceQuery" ParticipantObjectTypeCode="2" ParticipantObjectTypeCodeRole="24"><ParticipantObjectIDTypeCode csd-code="ITI-67" codeSystemName="IHE Transactions" originalText="Mobile Document Reference Query" /><ParticipantObjectQuery>c3RhdHVzPWN1cnJlbnQmcGF0aWVudC5pZGVudGlmaWVyPXVybjpvaWQ6MS4xLjEuOTkuMXwyMTU1MDNhMC0xMWQyLTQxOTctODIyYS0wNTM3OTFhYjVhOGU=</ParticipantObjectQuery></ParticipantObjectIdentification></AuditMessage>
+```
+
+!!! info "Note"
+    Notice the UTF-8 BOM at the beginning of the payload (just before `<?xml`). It is required by the syslog protocol
+    for UTF-8 messages. 2027 is the number of bytes in the following message (2025 characters + 2 extra bytes for 
+    the BOM).
diff --git a/files/AuthenticateUser.md b/files/AuthenticateUser.md
@@ -61,7 +61,7 @@ system as specified in [Bindings for the OASIS Security Assertion Markup Languag
 
 The following snippet is taken from a sample request recorded during the EPR projectathon in September 2020. Some elements
 were ommitted to increase readability. The raw request file may be found
-[here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/Auth_samples/04_AuthnRequest_raw.xml).
+[here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/Auth_samples/04_AuthnRequest_raw.xml).
 
 The *AuthnRequest* conveys the following information to be set by the primary system:
 
@@ -109,7 +109,7 @@ The IdP server responds the SAML 2.0 IdP Assertion of the authenticated user.
 ##### Request Message
 
 The following snippet is taken from a sample request recorded during the EPR projectathon in September 2020. Some elements are omitted to increase readability. The raw request file may be found
-[here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/Auth_samples/08_ArtifactResolve_raw.xml).
+[here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/Auth_samples/08_ArtifactResolve_raw.xml).
 
 The *ArtifactResolve* conveys the following information to be set by the primary system:
 
@@ -125,7 +125,7 @@ The *ArtifactResolve* conveys the following information to be set by the primary
 
 ##### Response Message
 
-The following snippet is taken from a sample response recorded during the EPR projectathon in September 2020. Some elements are omitted to increase readability. The raw version may be found [here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/Auth_samples/09_ArtifactResponse_raw.xml).
+The following snippet is taken from a sample response recorded during the EPR projectathon in September 2020. Some elements are omitted to increase readability. The raw version may be found [here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/Auth_samples/09_ArtifactResponse_raw.xml).
 
 The *ArtifactResponse* conveys the following information which shall be evaluated by the primary system:
 

diff --git a/files/GetXAssertion.md b/files/GetXAssertion.md
@@ -20,7 +20,7 @@ Messages are encoded as described in the [WS Trust](http://docs.oasis-open.org/w
 
 #### Request Message
 
-The following snippet is taken from a sample request recorded during the EPR projectathon in September 2020. Some elements are omitted to increase readability. The raw request file may be found [here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/GetXAssertion_request_raw.xml).
+The following snippet is taken from a sample request recorded during the EPR projectathon in September 2020. Some elements are omitted to increase readability. The raw request file may be found [here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/GetXAssertion_request_raw.xml).
 
 The snippet shows a request performed by a healthcare professional performing a the normal access. For other roles and situations the claims are different. Other examples may be found at [XUA examples][XUA_samples].   
 
@@ -67,7 +67,7 @@ of the ordinances of the Swiss electronic patient dossier.
 #### Response Message
 
 The following snippet is taken from a sample response recorded during the EPR projectathon in September 2020. Some elements
-were ommitted to increase readability. The raw file may be found [here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/GetXAssertion_response_raw.xml).
+were ommitted to increase readability. The raw file may be found [here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/GetXAssertion_response_raw.xml).
 
 The response message is a XML SOAP envelope with the XUA Assertion embedded in the the *Body* element of the SOAP envelope (see example below, lines 21 to 23). Primary systems shall extract the XUA Assertion to use the im the security header of the XDS.b transactions, which require authorization. For primary systems, there is no need to extract information from the XUA assertion.  
 

diff --git a/files/IdPRenew.md b/files/IdPRenew.md
@@ -17,7 +17,7 @@ Messages are encoded as described in [Assertions and Protocols for the OASIS Sec
 Primary systems shall use this transaction to renew a assertion whose lifetime is exceeded.
 
 The following snippet is adapted from a sample request recorded during the EPR projectathon in September 2020. Some elements
-and namespaces were omitted to increase readability. The raw request file may be found [here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/Auth_samples/Renew_request_raw.xml).
+and namespaces were omitted to increase readability. The raw request file may be found [here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/Auth_samples/Renew_request_raw.xml).
 
 The *Header* element of the SOAP envelope contains the data used to sign the request message, as required from the ordinances of the Swiss EPR in [Annex 8][annexes] and specified in the [Web Service Security: SOAP Message Security 1.1.](https://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf) specification.
 
@@ -37,7 +37,7 @@ below).
 The community responds with a SAML 2.0 IdP assertion whose lifetime is updated.  
 
 The following snippet is adapted from a sample request recorded during the EPR projectathon in September 2020. Some elements
-and namespaces were ommitted to increase readability. The raw request file may be found [here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/Auth_samples/Renew_response_raw.xml).
+and namespaces were ommitted to increase readability. The raw request file may be found [here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/Auth_samples/Renew_response_raw.xml).
 
 A SAML 2.0 IdP Assertion with identical attributes but updated lifetime is conveyed in the the *Body* of the SOAP envelope (see lines 67 .. 69). Examples of Swiss EPR compliant XUA assertions may be found [here][XUA_samples].
 

diff --git a/files/PDQ.md b/files/PDQ.md
@@ -31,7 +31,7 @@ Messages are encoded as described in the HL7 V3 standard with restrictions defin
 
 Since the [HL7 V3][hl7] standard is very generic, the request message is quite lengthy and needs some
 background information to interpret. The raw version of a request message may be found
-[here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/ITI-47_request_raw.xml). For a step by step interpretation
+[here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/ITI-47_request_raw.xml). For a step by step interpretation
 of the request message, see section below.
 
 ##### Message Interpretation
@@ -88,7 +88,7 @@ see [IHE PDQ V3](https://profiles.ihe.net/ITI/TF/Volume2/ITI-47.html#3.47).
 
 Since the [HL7 V3][hl7] standard is very generic, the response message is quite lengthy and needs some
 background information to interpret. The raw version of a response message may be found
-[here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/ITI-47_response_raw.xml). For a step by step interpretation of the message, see section below.
+[here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/ITI-47_response_raw.xml). For a step by step interpretation of the message, see section below.
 
 ##### Message Interpretation
 

diff --git a/files/PIXFeed.md b/files/PIXFeed.md
@@ -40,7 +40,7 @@ and the ordinances to the Swiss EPR.
 
 Due to the genericity of the underlying [HL7 V3][hl7] standard, the request
 message is quite lengthy. A raw version of a request message may be found
-[here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/ITI-44_request_raw.xml).
+[here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/ITI-44_request_raw.xml).
 
 For a step by step interpretation of the request message, see section below.
 
@@ -56,15 +56,8 @@ The SOAP *Header* element shall convey the following information:
 
 Optional elements may be included according to the specification in the [W3C SOAP specification][soap].
 
-```xml title="SOAP header" linenums="1" hl_lines="3-5"
-<soap:Header>
-  	<Action xmlns="http://www.w3.org/2005/08/addressing">urn:hl7-org:v3:PRPA_IN201301UV02</Action>
-	<MessageID xmlns="http://www.w3.org/2005/08/addressing">urn:uuid:7a180388-6ba7-4cbc-bffe-dfcdc4e602b7</MessageID>
-	<To xmlns="http://www.w3.org/2005/08/addressing">http://epd-core.int.adswissnet.healthcare/mpi/pixmanager</To>
-	<ReplyTo xmlns="http://www.w3.org/2005/08/addressing">
-	    <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
-	</ReplyTo>
-</soap:Header>
+```xml title="SOAP header" linenums="1"
+--8<-- "samples/ITI-44_request_raw.xml:1:11"
 ```
 
 For the patient identity feed no *Security* header element is required, since in the Swiss EPR the access to the patient
@@ -79,14 +72,14 @@ Primary systems shall set the following values:
 - *sender* : The OID of the sender application initiating the request.
 - *receiver*: The OID of the receiver application which shall respond to the request.
 
-```xml title="PRPA_IN201301UV02 message" linenums="2"
---8<-- "samples/ITI-44_request_raw.xml:2:17"
+```xml title="PRPA_IN201301UV02 message" linenums="13"
+--8<-- "samples/ITI-44_request_raw.xml:13:29"
 ```
 
 The patient data are encoded in a HL7 V3 *controlActProcess* object as follows:
 
-```xml title="controlActProcess element" linenums="18"
---8<-- "samples/ITI-44_request_raw.xml:18:60"
+```xml title="controlActProcess element" linenums="30"
+--8<-- "samples/ITI-44_request_raw.xml:30:72"
 ```
 
 The *subject* child element conveys the following information in its child elements.
@@ -107,13 +100,13 @@ The patients demographic data are conveyed in the *patientPerson* child element:
 
 The *custodian* element shall convey the OID of the provider organization in the *id* child element:
 
-```xml title="custodian element" linenums="61"
---8<-- "samples/ITI-44_request_raw.xml:61:71"
+```xml title="custodian element" linenums="73"
+--8<-- "samples/ITI-44_request_raw.xml:73:84"
 ```
 
 #### Response Message
 
-The PIX V3 Feed service responds with a message indicating the success of the transaction. A raw version of a response message may be found [here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/ITI-44_response.xml).
+The PIX V3 Feed service responds with a message indicating the success of the transaction. A raw version of a response message may be found [here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/ITI-44_response.xml).
 
 ### Transport Protocol
 

diff --git a/files/PIXQuery.md b/files/PIXQuery.md
@@ -28,7 +28,7 @@ Messages are encoded as described in the HL7 V3 standard with restrictions defin
 
 Due to the genericity of the underlying [HL7 V3][hl7] standard, the request message is quite lengthy.
 A raw version of a request message may be found
-[here](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/ITI-45_request_raw.xml).
+[here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/ITI-45_request_raw.xml).
 
 For a step by step interpretation of the request message, see section below.
 
@@ -89,7 +89,7 @@ The PIX V3 Feed service responds with the master patient ID (XAD-PID) and the EP
 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](https://github.com/ehealthsuisse/EPD-by-example/tree/main/samples/ITI-45_response.xml).
+of a response message may be found [here](https://github.com/ehealthsuisse/EPR-by-example/tree/main/samples/ITI-45_response.xml).
 
 ##### Message Interpretation