Describe the use of the traceparent header

Fixes #143

input/ch.fhir.ig.ch-epr-mhealth.xml

@@ -597,6 +597,11 @@ Relationship in the Swiss examples (CN=CommunityA:00000001001,OU=Relationship,DC
                     <title value="Sequence Diagrams"/>
                     <generation value="markdown"/>
                 </page>
+                <page>
+                    <nameUrl value="tracecontext.html"/>
+                    <title value="Trace Context"/>
+                    <generation value="markdown"/>
+                </page>
                 <page>
                     <nameUrl value="openissues.html"/>
                     <title value="Open Issues / Change Log"/>

input/fsh/ex-audit-65.fsh

@@ -42,4 +42,5 @@ Usage: #example
 * entity[submissionSet].role = http://terminology.hl7.org/CodeSystem/object-role#20 "Job"
 * entity[submissionSet].what.identifier.system = "urn:ietf:rfc:3986"
 * entity[submissionSet].what.identifier.value = "urn:oid:1.3.6.1.4.1.12559.11.13.2.6.2949"
-
+* entity[+].what.identifier.value = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
+* entity[=].type = https://profiles.ihe.net/ITI/BALP/CodeSystem/BasicAuditEntityType#XrequestId

input/includes/menu.xml

@@ -93,6 +93,9 @@
             <li>
                 <a href="sequencediagrams.html">Sequence diagrams</a>
             </li>
+            <li>
+                <a href="tracecontext.html">Trace Context</a>
+            </li>
             <li>
                 <a href="openissues.html">Open Issues / Change Log</a>
             </li>

input/pagecontent/iti-104.md

@@ -50,6 +50,7 @@ Add Patient [Franz Muster](Patient-PatientPIXmFeed.json.html):
 PUT http://example.org/fhir/Patient?identifier=urn:oid:2.16.756.888888.3.1|8734 HTTP/1.1
 Accept: application/fhir+json
 Content-Type: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 
 {
   "resourceType" : "Patient",
@@ -120,6 +121,8 @@ Patient Identifier Cross-reference Manager using the IUA profile with basic acce
 the _Patient Identity Feed FHIR_ [ITI-104] request must authorize using the 
 [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Patient Identity Source Audit

input/pagecontent/iti-65.md

@@ -79,6 +79,8 @@ Document Recipient using the IUA profile with extended access token. Consequentl
 the _Provide Document Bundle_ [ITI-65] request must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html)
 transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Document Source Audit

input/pagecontent/iti-66.md

@@ -32,6 +32,7 @@ _Find Document List_ example **request**:
 ```
 GET [base]/List?patient.identifier=urn:oid:2.999|11111111 HTTP/1.1
 Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 
 #### Find Document Lists Response Message
@@ -53,6 +54,8 @@ TLS SHALL be used. This national extension enforces authentication and authoriza
 Responder using the IUA profile with extended access token. Consequently the _Find Document Lists_ [ITI-66] request 
 must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Document Consumer Audit

input/pagecontent/iti-67.md

@@ -32,6 +32,7 @@ _Find Document Reference_ example **request**:
 ```
 GET [base]/DocumentReference?patient.identifier=urn:oid:2.999|11111111 HTTP/1.1
 Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 
 #### Find Document References Response Message

input/pagecontent/iti-68.md

@@ -40,6 +40,8 @@ Document Responder using the IUA profile with extended access token. Consequentl
 the _Retrieve Document_ [ITI-68] request must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html)
 transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Document Consumer Audit

input/pagecontent/iti-78.md

@@ -49,6 +49,7 @@ Query for a patient with name Muster and birthdate 1995-01-27.
 ```
 GET [base]/Patient?name=Muster&birthdate=1995-01-27
 Accept: application/fhir+json; fhirVersion=4.0
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 [Example response to above query](Bundle-PDQm-QueryResponse.json.html)
 
@@ -57,6 +58,7 @@ Query for a patient with name M returning too many results:
 ```
 GET [base]/Patient?name=M
 Accept: application/fhir+json; fhirVersion=4.0
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 [Example response to above query](Bundle-PDQm-QueryResponseTooManyResults.json.html)
 
@@ -88,6 +90,8 @@ Patient Identifier Cross-reference Manager using the IUA profile with basic acce
 the _Mobile Patient Identifier Cross-reference Query_ [ITI-83] request must authorize using the
 [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Patient Demographics Consumer Audit

input/pagecontent/iti-83.md

@@ -55,7 +55,10 @@ Query for a patient with a local id of 123 by AssigningAuthority oid 1.2.3 which
 community where the Assigning Authority is oid 5.6.7 and the MPI-PID and EPR-SPID are requested:
 
 ```
-GET [base]/Patient/$ihe-pix?sourceIdentifier=urn:oid:2.999.1.2.3|123&targetSystem=urn:oid:2.999.5.6.7&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3
+GET [base]/Patient/$ihe-pix?sourceIdentifier=urn:oid:2.999.1.2.3|123&targetSystem=urn:oid:2.999.5.6.7&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3 HTTP/1.1
+Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
+
 ```
 
 #### Response message
@@ -109,6 +112,8 @@ Patient Identifier Cross-reference Manager using the IUA profile with basic acce
 the _Mobile Patient Identifier Cross-reference Query_ [ITI-83] request must authorize using the 
 [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Patient Identifier Cross-reference Consumer Audit

input/pagecontent/iti-90.md

@@ -33,13 +33,17 @@ The _Find Matching Care Services_ message is a FHIR search operation on the mCSD
 A _Care Services Selective Consumer_ initiates a search request using HTTP GET or POST:
 
 ```
-GET [base]/[resource]?[parameters]
+GET [base]/[resource]?[parameters] HTTP/1.1
+Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 
 or
 
 ```
-POST [base]/[resource]/_search
+POST [base]/[resource]/_search HTTP/1.1
+Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 Content-Type: application/x-www-form-urlencoded
 
 param1=value&param2=value
@@ -158,6 +162,8 @@ TLS SHALL be used. This national extension enforces authentication and authoriza
 Selective Supplier_ using the IUA profile with basic access token. Consequently, the _Find Matching Care Services_
 [ITI-90] request must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 Note that the same audit message is recorded by both **Care Services Selective Supplier** and **Care Services 

input/pagecontent/tracecontext.md

@@ -0,0 +1,51 @@
+### Trace Context header
+
+For all transaction described in this implementation guide, the HTTP `traceparent`
+header is required. This header is defined in the
+[W3C Trace Context Recommendation](https://www.w3.org/TR/trace-context/).
+
+The header value is made of four parts separated by dashes: the **version**, **trace-id**, **parent-id** and
+**trace-flags**. For example:
+
+```http
+GET /request HTTP/1.1
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
+```
+
+- The **version** is currently set to `00`.
+- The **trace-id** is a unique identifier for this transaction instance (i.e. an HTTP request and its response).
+  Consecutive HTTP requests SHALL NOT have the same trace-id, even if it is a retry. The HTTP request and its response
+  SHALL have the same trace-id. It is a 16-byte array encoded as 32 hexadecimal characters, all lowercase.
+- The **parent-id** is a unique identifier for this message (a request and response are two different messages). The
+  HTTP response SHALL have a different identifier than the request. It is an 8-byte array, encoded as 16 hexadecimal
+  characters, all lowercase.
+- The **trace-flags** is used to communicate tracing flags with the consumer. This implementation guide specifies no
+  requirements for this field, it is recommended using the value `00`.
+
+Each actor shall support the `traceparent` header. Grouped actors shall use the same **trace-id** value to correlate IHE transactions.
+
+##### Audit event requirements
+
+The `traceparent` header value of the generated message SHALL be added to the generated Audit Event: for the client, the
+header value of the request; for the responder, the header value of the response.
+It is described as an `AuditEvent.entity`, with the system `https://profiles.ihe.net/ITI/BALP/CodeSystem/BasicAuditEntityType#Traceparent`, as demonstrated below.
+
+```json
+{
+  "resourceType" : "AuditEvent",
+  /* Rest of the AuditEvent */
+  "entity" : [
+    {
+      "what" : {
+        "identifier" : {
+          "value" : "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00"
+        }
+      },
+      "type" : {
+        "system" : "https://profiles.ihe.net/ITI/BALP/CodeSystem/BasicAuditEntityType",
+        "code" : "Traceparent"
+      }
+    }
+  ]
+}
+```