MyHealth@Eu NCPeH API - Local Development build (v10.0.0-ci) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Document Retrieval

This page describes the implementation options of Document Retrieval task.

Business View

The overall business scenarios associated to this task is described in the Business view page

Application View

The implementation-indipendent sequence diagrams associated to this task is described in the in the Application view page

Implementation pre-requisites

The Myhealth@EU general architecture requires that no assumptions are made on the way the service is implemented at the national level.

This implies that any solution adopted for the NCPeH to NCPeH communications has to work properly indipendently by the fact that a HL7 FHIR server, or an XDS registry/repository or any other solution solution is locally adopted.

Implementation alternatives

There are multiple alternatives, not mutually exclusive, for searching, retrieving, or fetching documents using the HL7 FHIR API.

The selected mechanism may depend on the type of document and the usage context.

For example, searching for documents via DocumentReference - the query type used in the IHE MHD profile - enables a standardized retrieval mechanism regardless of document format. This approach is suitable for simple search mechanisms and requires that a DocumentReference instance is generated for each created document.

On the other hand, searching via DiagnosticReport allows for more advanced queries, but it is limited to imaging and diagnostic reports, as well as HL7 FHIR documents. Other mechanisms may apply in different contexts.

In this first version, this will be realized by searching per DocumentReference

Some alternatives - described only for documentation purposes - are listed below:

1. searching per Composition
2. searching per Bundle
3. searching per DiagnosticReport (only for imaging and laboratory reports)

Implementation

Beside the advantages described above, the DocumentReference Search mechanism permits to realize with a common call both the search and retrieve and the document fetch envisioned by the Document Retrieval sequence.

In the following diagram is described how the requesting NCP realizes the search or the fetch of the document by using the DocumentReference.

In summary:

• The Requesting NCP searches for a DocumentReference.
• If content data exists, the document is fetched directly from the DocumentReference.
• If content data is missing, the system retrieves it via a HL7 FHIR Bundle or Binary resource.

Step-by-Step Breakdown: DocumentReference Search

eHDSI DocumentReference Search Request

The Requesting NCP initiates a search query for a DocumentReference using the FHIR API call:

  GET $server/DocumentReference?<searchParameters><modifiers>

The query includes search parameters and modifiers to refine the search criteria.

Search Parameters

Common

Hospital Discharge Report

Laboratory Report

Imaging Study Manifest and Report

Patient Summary

Vaccination History

The provider shall support the combination of required search parameters

Please note that the date parameter refers to the date when the DocumentReference has been created. A query against the effective document creation date is perfomed by using the SearchParameter creation.

eHDSI DocumentReference Search Response

The Responding NCP returns a FHIR Bundle containing the search results. The bundle contains entries of type DocumentReference, compliant with the DocumentReference: Minimal

  Bundle.where(type='searchSet').entry.resource.ofType(DocumentReference)

Each DocumentReference may return or refer one or more representations (e.g. PDF, HL7 CDA, HL7 FHIR json) of a specific document instance.

If the document is included in the content.data element we are in the FETCH case.

If the document is referred in the content.url element we are in the SEARCH AND GET case.

In this case it is expected that the url element contains the actual url to be used for retrieving this docuemnt from the HL7 FHIR API.

Search HTTP Error Response Codes

Examples

GET $server/DocumentReference?category=http://loinc.org|LP74123-8&patient.identifier=https://ncez.mzcr.cz/standards/fhir/sid/rid|456789123&date=ge2023-02-20

GET $server/DocumentReference?category=http://loinc.org|LP74123-8&patient.identifier=https://ncez.mzcr.cz/standards/fhir/sid/rid|456789123&contenttype=application/pdf

GET $server/DocumentReference?category=http://loinc.org|LP74123-8&patient.identifier=https://ncez.mzcr.cz/standards/fhir/sid/rid|456789123&category=http://loinc.org|18725-2&date=ge2023-09-25

Step-by-Step Breakdown: Document Retrieval

Checking DocumentReference Content Availability

If DocumentReference.content.data.exists(), the document can be fetched directly from the DocumentReference.content.data field and the sequence ends.

Otherwise,

Read URL

if DocumentReference.content.data is empty, the system must search and retrieve the document from the specified URL.

The URL shall be a valid FHIR API URL in the form:

$server/[Resource]/id

The [Resource] segment shall be either Bundle or Binary.

The following rules apply:

1. If the resource is Bundle, the content type shall be application/fhir+json or application/fhir+xml.
2. If the content type is not application/fhir+json or application/fhir+xml, the resource shall be Binary.

eHDSI Get Bundle by Id Request

If the content type of the document is application/fhir+json or application/fhir+xml, the system retrieves it using a FHIR Bundle request:

  GET $server/Bundle/id

The Requesting NCP sends a request to the Responding NCP for the Bundle. The Responding NCP returns the Bundle, compliant with one of the profiles specified in the HL7 FHIR IG listed in the Data menu.

eHDSI Get Binary by Id Request

Otherwise, if the content type is not application/fhir+json or application/fhir+xml, the system retrieves it as a HL7 FHIR Binary resource:

  GET $server/Binary/id

The Requesting NCP sends a request to fetch the document as a Binary resource. The Responding NCP returns the Binary content.

Document Retrieval HTTP Error Response Codes

Examples

Retrieval of an HL7 FHIR document representation returned as a Bundle.

GET $server/Bundle/12345

Retrieval of a non-FHIR document representation returned as a Binary resource.

GET $server/Binary/67890