4. EPR Primary System Integration
4.1 Introduction
The REST variants of XDS transactions presented here are based on CH EPR FHIR, itself based on various IHE profiles.
Don't forget to properly encode the HTTP parameters in the queries (especially colons and pipes).
For readability, parameters are shown decoded, and the Authorization
and Accept
headers are omitted from the examples.
For HTTP GET requests, there is usually an equivalent HTTP POST request that should be supported.
4.2 Authentication
The sequence diagram shows the currently implemented authentication flow.
You should integrate one of the supported IDPs in your application. The OAuth/IUA flow is supported for clients, the SAML flow is the only one implemented between the Mobile Access Gateway and the IDP.
Once you get the IDP SAML assertion, you can trade it for the community SAML assertion, which binds your IDP
identification to a specific patient and a purpose of use.
It is an HTTP POST request to /assertion
, with the header Scope
and the IDP SAML assertion as body.
The header Scope
contains the following values:
purpose_of_use
(token, required):
a value from EprPurposeOfUsesubject_role
(token, required):
eitherHCP
,ASS
,PAT
orREP
in the systemurn:oid:2.16.756.5.30.1.127.3.10.6
person_id
(string, required):
the patient EPR-SPID in the CX formatprincipal
(string, only if role isASS
):
the name of the healthcare professional on whose behalf an assistant is actingprincipal_id
(token, only if role isASS
):
the GLN of the healthcare professional on whose behalf an assistant is actinggroup
(string, only if role isASS
):
the name of the organization or group on whose behalf an assistant is actinggroup_id
(token, only if role isASS
):
the OID of the organization or group on whose behalf an assistant is acting
POST /assertion HTTP/1.1
Scope: person_id=761337610445502987^^^&2.16.756.5.30.1.127.3.10.3&ISO purpose_of_use=urn:oid:2.16.756.5.30.1.127.3.10.5|NORM subject_role=urn:oid:2.16.756.5.30.1.127.3.10.6|HCP
Content-Type: application/xml
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0">
<!-- Content of the IDP assertion… -->
</saml2:Assertion>
The response then looks like:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "U0FNTGFzc2VydGlvbg",
"token_type": "IHE-SAML",
"expires_in": 60000,
"scope": "resourceId/761337610445502987 purposeOfUse/NORM role/HCP"
}
The base64-url encoded SAML assertion is given in
access_token
, and that value has to be prefixed with Bearer
and inserted in an Authorization
HTTP header for
all transactions that require it.
GET /... HTTP/1.1
Authorization: Bearer U0FNTGFzc2VydGlvbg
4.3 Patient Directory
The patient directory, called the Master Patient Index (MPI), contains identifiers and demographics for all registered patients. Identifiers include the MPI-PID and EPR-SPID, and identifiers used by primary systems that choose to share them. Demographics include the given and family names, date of birth, gender, nationality, telecoms and address information. It can be queried and updated.
4.3.1 Retrieving Patient Identifiers [ITI-83]
Patient identifiers (commonly the MPI-PID and EPR-SPID) can be queried with an ITI-83 (Mobile Patient Identifier Cross-reference Query) transaction.
The transaction is an HTTP GET request to the endpoint /Patient/$ihe-pix
, with the following parameters:
sourceIdentifier
(token, required):
the known patient identifiertargetSystem
(uri, 1..2):
to restrict the results to the EPR-SPID (required) and MPI-PID (optional)
Examples
GET /Patient/$ihe-pix?sourceIdentifier=urn:oid:2.999.42|1234&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3 HTTP/1.1
GET /Patient/$ihe-pix?sourceIdentifier=urn:oid:2.16.756.5.32|{ahvn13}&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3 HTTP/1.1
GET /Patient/$ihe-pix?sourceIdentifier=urn:oid:2.16.756.5.30.1.191.1.0.12.3.101|{mpi-pid}&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3 HTTP/1.1
GET /Patient/$ihe-pix?sourceIdentifier=urn:oid:2.16.756.5.30.1.127.3.10.3|{epr-spid}&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3&targetSystem=urn:oid:2.16.756.5.30.1.191.1.0.12.3.101 HTTP/1.1
4.3.2 Patient Matching [ITI-119]
The patient's participation in the Swiss EPD can be queried with an ITI-119 (Patient Demographics Match) transaction.
The patient data shall conform to this profile: http://fhir.ch/ig/ch-epr-fhir/StructureDefinition/ch-pdqm-patient
.
The transaction is an HTTP POST request to the endpoint /Patient/$match
.
There are two ways to perform the match:
- Using a
Parameters
resource that contains the patient as an input parameter - Posting the
Patient
resource directly as the body of the request
Example
POST /Patient/$match HTTP/1.1
Content-Type: application/fhir+json
{
"resourceType" : "Parameters",
"parameter" : [
{
"name" : "resource",
"resource" : {
"resourceType" : "Patient",
"identifier" : [
{
"system" : "urn:oid:2.16.756.5.30.1.127.3.10.3",
"value" : "761337611735842172"
}
]
}
}
]
}
Example
POST /Patient/$match HTTP/1.1
Content-Type: application/fhir+json
{
"resourceType" : "Patient",
"identifier" : [
{
"system" : "urn:oid:2.16.756.5.30.1.127.3.10.3",
"value" : "761337611735842172"
}
],
"name" : [
{
"family" : "NEFF-WINGEIER",
"given" : [
"Trong Sang"
]
}
],
"gender" : "male",
"birthDate" : "1987-10-08"
}
4.3.3 Retrieving Patient Demographics
4.3.3.1 Patient Read
A single patient can be retrieved by performing the transaction with the EPR-SPID specified.
The transaction is an HTTP GET request to the endpoint /Patient/{id}
, where {id}
is the identifier value.
GET /Patient/761337615866818761 HTTP/1.1
4.3.3.2 Patient Search [ITI-78]
Patient demographics can also be queried with an ITI-78 (Mobile Patient Demographics Query) transaction (not part of the CH EPR FHIR specification).
The transaction to retrieve a single patient can be done by specifying patient's information. These search parameters can be used to search the patient:
family
andgiven
(string)identifier
(token)telecom
(token)birthdate
(date)address
(string): to search in any part of the addressaddress-city
,address-country
,address-postalcode
,address-state
(string)gender
(token)
GET /Patient?family=MOHR&given=ALICE&gender=female HTTP/1.1
4.3.4 Feeding Patient Information
4.3.4.1 Feed by Local PID (with EPR-SPID) [ITI-104]
Feeding patient information can be done with the ITI-104 (Patient Identity Feed FHIR) transaction.
The following profile shall be used: http://fhir.ch/ig/ch-epr-fhir/StructureDefinition/ch-pixm-patient-feed
.
The EPR-SPID is required as identifier
element according the profile.
You don't have to re-specify the other identifiers, they won't be deleted if they're missing from the request.
If you want to add an identifier, you can put it in another identifier
element.
Example
PUT /Patient?identifier=urn:oid:2.999.1.2.3.4|8734 HTTP/1.1
Content-Type: application/fhir+json
{
"resourceType": "Patient",
"id": "2.999.1.2.3.4-8734",
"identifier" : [
{
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "MR"
}
]
},
"system" : "urn:oid:2.999.1.2.3.4",
"value" : "8734"
},
{
"system" : "urn:oid:2.16.756.5.30.1.127.3.10.3",
"value" : "EPR-SPID"
}
],
"active": true,
"name": [
{
"family": "NEFF-WINGEIER",
"given": [
"Trong Sang"
]
}
],
"gender": "male",
"birthDate": "1987-10-08"
}
4.3.4.2 Feed by Local PID (without EPR-SPID)
Performing the patient information feed transaction without specifying the EPR-SPID is possible, but it is not conformant with the CH EPR FHIR specification.
Example
PUT /Patient?identifier=urn:oid:2.999.1.2.3.4|8734 HTTP/1.1
Content-Type: application/fhir+json
{
"resourceType": "Patient",
"id": "2.999.1.2.3.4-8734",
"identifier" : [
{
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "MR"
}
]
},
"system" : "urn:oid:2.999.1.2.3.4",
"value" : "8734"
},
{
"system" : "urn:oid:2.16.756.5.32",
"value" : "AHVN13"
}
],
"active": true,
"name": [
{
"family": "NEFF-WINGEIER",
"given": [
"Trong Sang"
]
}
],
"gender": "male",
"birthDate": "1987-10-08"
}
4.4 Document Directory
The document directory stores documents (in the document repository) and their metadata (in the document registry).
4.4.1 Searching [ITI-67]/[ITI-66]
You can search the document registry with the ITI-67 (Find Document References) transaction.
The transaction is an HTTP GET request to the endpoint /DocumentReference
, the search parameters are described in
the MHD ITI-67 specifications.
Examples
GET /DocumentReference?patient.identifier=urn:oid:2.999|11111111&status=current HTTP/1.1
GET /DocumentReference?patient.identifier=urn:oid:2.999|11111111&category=http://snomed.info/sct|371531000&type=http://snomed.info/sct|419891008 HTTP/1.1
GET /DocumentReference?patient.identifier=urn:oid:2.999|11111111&creation=ge2023-07-10&creation=le2023-07-17 HTTP/1.1
You can also search for SubmissionSets with the ITI-66 (Find Document Lists) transaction (not part of the CH EPR FHIR specification).
Examples
GET /List?patient.identifier=urn:oid:2.999|11111111 HTTP/1.1
GET /List?patient.identifier=urn:oid:2.999|11111111&code=submissionset&status=current&designationType=http://loinc.org|1234-5 HTTP/1.1
4.4.2 Reading [ITI-68]
Retrieving a document is done with the ITI-68 (Retrieve Document) transaction.
It is a simple HTTP GET request to an URL that you will find in the linked DocumentReference (that you can obtain
with search results): DocumentReference.content.attachment.url
.
4.4.3 Publishing [ITI-65]
You can publish a document with the ITI-65 (Provide Document Bundle) transaction.
The transaction is an HTTP POST request to the endpoint /
.
The Bundle.meta.profile
element shall have the following value: https://profiles.ihe.net/ITI/MHD/StructureDefinition/IHE.MHD.Comprehensive.ProvideBundle
.
Example
POST / HTTP/1.1
Content-Type: application/fhir+json
{
"entry": [
{
"fullUrl": "urn:uuid:59f3a738-11c1-4a0e-a89b-c4552d0fe9a7",
"request": {
"method": "POST",
"url": "Binary"
},
"resource": {
"contentType": "application/pdf",
"data": "VGhlIHBkZiBmaWxlIGdvZXMgaGVyZQ==",
"resourceType": "Binary"
}
},
{
"fullUrl": "urn:uid:eb00c215-61cf-43a3-b99a-020ab21828fa",
"request": {
"method": "POST",
"url": "List"
},
"resource": {
"code": {
"coding": [
{
"code": "submissionset",
"display": "SubmissionSet as a FHIR List",
"system": "http://profiles.ihe.net/ITI/MHD/CodeSystem/MHDlistTypes"
}
]
},
"date": "2023-01-06T14:23:14+01:00",
"entry": [
{
"item": {
"reference": "urn:uuid:5ae558f6-c103-4566-9a7e-63242abd24ab"
}
}
],
"extension": [
{
"url": "http://profiles.ihe.net/ITI/MHD/StructureDefinition/ihe-sourceId",
"valueIdentifier": {
"value": "urn:oid:2.16.756.5.30.1.145.20.1"
}
},
{
"url": "http://fhir.ch/ig/ch-epr-fhir/StructureDefinition/ch-ext-author-authorrole",
"valueCoding": {
"code": "HCP",
"display": "Healthcare professional",
"system": "urn:oid:2.16.756.5.30.1.127.3.10.6"
}
},
{
"url": "http://profiles.ihe.net/ITI/MHD/StructureDefinition/ihe-designationType",
"valueCodeableConcept": {
"coding": [
{
"code": "71388002",
"display": "Procedure (procedure)",
"system": "http://snomed.info/sct"
}
],
"text": "Procedure (procedure)"
}
}
],
"identifier": [
{
"system": "urn:ietf:rfc:3986",
"use": "official",
"value": "urn:uuid:ab1862da-e31e-4ca9-ab01-24883cda5404"
},
{
"system": "urn:ietf:rfc:3986",
"use": "usual",
"value": "urn:oid:2.999.123"
}
],
"mode": "working",
"resourceType": "List",
"status": "current",
"subject": {
"reference": "Patient/2.16.756.5.30.1.191.1.0.2.1-c55f4ca7-bd4e-4134-8dcd-56b793ade958"
}
}
},
{
"fullUrl": "urn:uuid:5ae558f6-c103-4566-9a7e-63242abd24ab",
"request": {
"method": "POST",
"url": "DocumentReference"
},
"resource": {
"author": [
{
"reference": "#practrole"
}
],
"category": [
{
"coding": [
{
"code": "405624007",
"display": "Administrative documentation (record artifact)",
"system": "http://snomed.info/sct"
}
]
}
],
"contained": [
{
"birthDate": "1993-01-27",
"gender": "male",
"id": "1",
"identifier": [
{
"system": "urn:oid:2.16.756.5.30.1.191.1.0.12.3.101",
"value": "MAGMED006"
},
{
"system": "urn:oid:2.16.756.5.30.1.191.1.0.2.1",
"value": "c55f4ca7-bd4e-4134-8dcd-56b793ade958"
}
],
"name": [
{
"family": "Sesztáková",
"given": [
"Jett Flynn"
]
},
{
"family": "Sesztáková",
"given": [
"Jett Flynn"
]
}
],
"resourceType": "Patient"
},
{
"address": [
{
"city": "Zürich",
"country": "CH",
"line": [
"Krankenstrasse 2"
],
"postalCode": "8005"
}
],
"id": "org",
"identifier": [
{
"system": "urn:oid:2.51.1.3",
"value": "7601000234438"
}
],
"name": "Hausarzt",
"resourceType": "Organization"
},
{
"id": "pract",
"identifier": [
{
"system": "urn:oid:2.51.1.3",
"value": "7601000234438"
}
],
"name": [
{
"family": "Hausarzt",
"given": [
"Familien"
]
}
],
"resourceType": "Practitioner"
},
{
"id": "practrole",
"organization": {
"reference": "#org"
},
"practitioner": {
"reference": "#pract"
},
"resourceType": "PractitionerRole"
}
],
"content": [
{
"attachment": {
"contentType": "application/pdf",
"creation": "2011-11-29T11:00:00+01:00",
"language": "de-CH",
"url": "urn:uuid:59f3a738-11c1-4a0e-a89b-c4552d0fe9a7",
"title": "Document example title"
},
"format": {
"code": "urn:che:epr:EPR_Unstructured_Document",
"system": "urn:oid:2.16.756.5.30.1.127.3.10.10"
}
}
],
"context": {
"facilityType": {
"coding": [
{
"code": "264358009",
"display": "General practice premises(environment)",
"system": "http://snomed.info/sct"
}
]
},
"practiceSetting": {
"coding": [
{
"code": "394802001",
"display": "General medicine(qualifier value)",
"system": "http://snomed.info/sct"
}
]
},
"sourcePatientInfo": {
"reference": "#1"
}
},
"date": "2011-11-29T11:00:00+01:00",
"description": "file.pdf",
"extension": [
{
"url": "http://fhir.ch/ig/ch-epr-fhir/StructureDefinition/ch-ext-author-authorrole",
"valueCoding": {
"code": "HCP",
"display": "Healthcare professional",
"system": "urn:oid:2.16.756.5.30.1.127.3.10.6"
}
}
],
"identifier": [
{
"system": "urn:ietf:rfc:3986",
"use": "usual",
"value": "urn:oid:2.25.161286146254585515369612173924762763705"
}
],
"masterIdentifier": {
"value": "urn:uuid:f3b905a6-f0e4-4ba6-9b6e-c7e7692c0438"
},
"resourceType": "DocumentReference",
"securityLabel": [
{
"coding": [
{
"code": "17621005",
"display": "Normally accessible",
"system": "http://snomed.info/sct"
}
]
}
],
"status": "current",
"subject": {
"reference": "Patient/2.16.756.5.30.1.191.1.0.2.1-c55f4ca7-bd4e-4134-8dcd-56b793ade958"
},
"type": {
"coding": [
{
"code": "772786005",
"display": "Medical certificate (record artifact)",
"system": "http://snomed.info/sct"
}
]
}
}
}
],
"meta": {
"profile": [
"http://profiles.ihe.net/ITI/MHD/StructureDefinition/IHE.MHD.Comprehensive.ProvideBundle"
]
},
"resourceType": "Bundle",
"type": "transaction"
}
4.4.4 Updating Metadata [CH:MHD-1]
You can update document metadata with the CH:MHD-1 (Update Document Metadata) transaction.
The transaction is an HTTP PUT request to the endpoint /DocumentReference/{id}
, where {id}
is the id value.
Example
PUT /DocumentReference/1c8d1f74-1686-4188-9c35-0c5727c771cc HTTP/1.1
Content: application/fhir+json
{
"resourceType": "DocumentReference",
"id": "1c8d1f74-1686-4188-9c35-0c5727c771cc",
"contained": [
{
"resourceType": "Patient",
"id": "pat",
"identifier": [
{
"use": "usual",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MR"
}
]
},
"system": "urn:oid:2.999.1.2.3.4",
"value": "8734"
}
]
}
],
"extension": [
{
"url": "http://fhir.ch/ig/ch-epr-fhir/StructureDefinition/ch-ext-deletionstatus",
"valueCoding": {
"system": "urn:oid:2.16.756.5.30.1.127.3.10.18",
"code": "urn:e-health-suisse:2019:deletionStatus:deletionNotRequested"
}
},
{
"url": "http://fhir.ch/ig/ch-epr-fhir/StructureDefinition/ch-ext-author-authorrole",
"valueCoding": {
"system": "urn:oid:2.16.756.5.30.1.127.3.10.6",
"code": "HCP",
"display": "Healthcare professional"
}
}
],
"masterIdentifier": {
"system": "urn:ietf:rfc:3986",
"value": "urn:oid:1.3.6.1.4.1.12559.11.13.2.1.2951"
},
"identifier": [
{
"system": "urn:ietf:rfc:3986",
"value": "urn:uuid:50383ae5-49e5-4dea-b0e6-660cb9e7b91f"
}
],
"status": "current",
"type": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "721912009",
"display": "Medication summary document (record artifact)"
}
]
},
"category": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "422735006",
"display": "Summary clinical document (record artifact)"
}
]
}
],
"subject": {
"identifier": {
"system": "urn:oid:2.16.756.5.30.1.127.3.10.3",
"value": "761337610411353650"
}
},
"description": "Changed Description for -MedicationCard",
"securityLabel": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "17621005",
"display": "Normal (qualifier value)"
}
]
}
],
"content": [
{
"attachment": {
"contentType": "text/xml",
"language": "de-CH",
"url": "http://example.com/xdsretrieve?uniqueId=urn:uuid:413eb0f7-aa72-4405-86a4-7793a23fcc27&repositoryUniqueId=2.999.756.42.1",
"creation": "2020-06-29T11:58:00+00:00"
},
"format": {
"system": "http://ihe.net/fhir/ihe.formatcode.fhir/CodeSystem/formatcode",
"code": "urn:ihe:pharm:pml:2013",
"display": "Pharmacy PML"
}
}
],
"context": {
"facilityType": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "264358009",
"display": "General practice premises (environment)"
}
]
},
"practiceSetting": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "394802001",
"display": "General medicine (qualifier value)"
}
]
},
"sourcePatientInfo": {
"reference": "#pat"
}
}
}
4.5 Professional and Organization Directory
The HPD (Healthcare Provider Directory) contains information about the healthcare professionals and organizations that are part of the EPR. Relationships between them (i.e. membership of professionals to organizations, or relationships between organizations) are also available.
4.5.1 Searching [ITI-90]
Professionals, organizations and relationships can be queried with an ITI-90 (Find Matching Care Services) transaction. See the specifications for the complete list of search parameters.
For professionals, the endpoint is /Practitioner
.
GET /Practitioner?family=Müller HTTP/1.1
GET /Practitioner?identifier=urn:oid:2.51.1.3|7601000102737 HTTP/1.1
GET /Practitioner/DrPeterPan HTTP/1.1
For organizations, the endpoint is /Organization
.
GET /Organization?active=true&name:contains=Medical HTTP/1.1
GET /Organization/SpitalXDept3 HTTP/1.1
For relationships (memberships), the endpoint is /PractitionerRole
.
GET /PractitionerRole?organization=Organization/HUG&_include=PractitionerRole:practitioner HTTP/1.1
GET /PractitionerRole/PeterPanPraxisP HTTP/1.1
4.5.2 Updating [ITI-59]
The HPD update is not supported in a REST transaction. Please use the ITI-59 (Provider Information Feed) transaction.
4.6 Audit Messages
4.6.1 Creating [ITI-20]/RESTful
For all transactions, it is required to send the same audit messages. You can use the regular ITI-20 (Record Audit Event) transaction, or use the RESTful one.
See the mapping from DICOM to FHIR.
Example
POST /ARR/fhir/AuditEvent HTTP/1.1
Content-Type: application/fhir+xml
<Bundle>
<entry>
...
<request>
<method value="POST"/>
</request>
</entry>
</Bundle>
4.6.2 Reading [ITI-81]
You can read the audit messages for a given patient with an ITI-81 (Retrieve ATNA Audit Event) transaction.
Warning
The endpoint for this transaction is the EPR community itself, not the Mobile Access Gateway. This transaction is still implemented on a previous CH:ATC specification (March 2020), based on the IHE RESTful ATNA Supplement Rev. 2.2. A lot has changed since.
The transaction is an HTTP GET request on the endpoint, with the parameter entity-id
that contains the patient EPR-SPID,
and date
to constraint the audit message date.
The Authorization
header uses the prefix IHE-SAML
and the SAML assertion is encoded with the regular base64
alphabet.
The community will ask other communities for their audit messages and regroup them all. If a foreign community is not reachable, an OperationOutcome may be added to the response Bundle.
Example
GET /ARR/fhir/AuditEvent?entity-id=urn:oid:2.16.756.5.30.1.127.3.10.3|{epr-spid}&date=ge2023-07-10&date=le2023-07-17 HTTP/1.1
Authorization: IHE-SAML Zm9vYmE=