MedMij FHIR use case Medication Information

This version is obsolete - See current publication here.

Introduction

This page technically describes how a client, e.g. a PHE, should retrieve medication information from a server, maintained by College ter Beoordeling Geneesmiddelen (CBG). This use case makes use of the IHE MHD profile and PDF/A use case, which are described in detail here.

Note: this page is part of the MedMij FHIR Implementation Guide and is a technical representation of the functional design published on this wiki page.

Retrieve Medication information by patients

This section summarizes the IHE MHD profile to exchange PDF/A documents in a MedMij context.

This FHIR implementation guide assumes that the PHR system is able to make a connection to the right XIS that contains the patient's information. It does not provide information on finding the right XIS nor does it provide information about security. Moreover, each transaction is performed in the context of a specific authenticated patient, for whose context (token) has been established using the authentication mechanisms described in the 'Afsprakenstelsel'. Each XIS Gateway is required to perform filtering based on the patient associated with the context for the request, so only the records associated with the authenticated patient are returned. For this reason, search parameters should not be included for patient identification.

Actors and transactions involved

Table 1 shows the relevant actors, systems and FHIR capability statements in a MedMij context. The capability statements demonstrate the minimum requirements to be conformant to the Medication Information use case specification.

Actors		Systems		FHIR Capability Statements
Name	Description	Name	Description	Name	Description
Patient	The user of a personal healthcare environment.	PHR	Personal health record	CapabilityStatement: Client	FHIR Client requirements
College ter Beoordeling Geneesmiddelen (CBG)	The owner of the medication information	XIS	Healthcare information system	CapabilityStatement: Server	FHIR Server requirements

Table 1. Actors, systems and FHIR capability statements

Table 2 shows the MHD actors and transactions in perspective of the systems used in a MedMij context.

Actors	System	MHD Actors	MHD Transactions
Patient
	PHR
		Document Consumer
			Find Document Reference
			Retrieve Document
College ter Beoordeling Geneesmiddelen (CBG)
	XIS
		Document Responder
			Find Document Reference
			Retrieve Document

Table 2. MHD actors and transactions in perspective of systems in a MedMij context and the medication information use case.

Transactions in scope

• Find Document References – This transaction is used to issue parameterized queries that result in a list of Document Reference resources.
• Retrieve Document – This transaction is used to get documents.

Find and retrieve medication information document

Find medication information document

Discovery of medication information documents is done with the MHD defined transaction Find Document Reference. The Find Document Reference retrieves FHIR DocumentReference Resources that represents a single reference to document per resource, for example one PDF/A file containing the medication information.

The Document Consumer requests DocumentReference, matching a set of criteria, from the Document Responder. The Document Responder returns DocumentReference or DocumentManifest Resources that match the search criteria provided by the Document Consumer.

Request message

Search

The Document Consumer executes an HTTP GET conform to the FHIR RESTfull and search specification. A search query would have the following format.

GET [base]DocumentReference?[parameters]{&_format=[mime-type]}

Search Parameters The Document Consumer may supply, and the Document Responder shall be capable of processing, all query parameters listed below. These search parameters are a selection of the defined search parameters by the HL7 FHIR specification (search parameters: DocumentReference).

DocumentReference
Name	Type	Description
type	token	Kind of document. This element is used to specifically search for the right document based on the G-Standard (ZI-nummers or HPK)
class	token	Categorization of document. The relevant categories for this use case are: patient's Instructions, scientific information, additional risk minimization information and assessment reports.

Example queries to search for DocumentReferences containing medication information.

1. GET [base]/DocumentReference?class=http://example.system.com|patientinstructions&type=urn:oid:2.16.840.1.113883.2.4.4.8|14668157
2. GET [base]/DocumentReference?class=http://example.system.com|patientinstructions&type=urn:oid:2.16.840.1.113883.2.4.4.7|01474707
3. GET [base]/DocumentReference?class=http://example.system.com|patientinstructions&type=urn:oid:2.16.840.1.113883.2.4.4.1|081140

1. Search on class (Patient Instructions) and type (ZI number for PARACETAMOL/CODEINEFOSFAAT RP TABLET 500/50MG (30 ST)).
2. Search on class (Patient Instructions) and type (HPG number for PARACETAMOL/CODEINEFOSFAAT RP TABLET 500/50MG).
3. Search on class (Patient Instructions) and type (GPK number for PARACETAMOL/CODEINE TABLET 500/50MG).

Response message

The Document Responder shall process the query to discover the DocumentReference entries that match the search parameters given. The Document Responder returns a HTTP Status code appropriate to the processing as well as a Bundle including the matching DocumentReference Resources. When the Document Responder needs to report an error or warning, it shall use HTTP error response codes and should include a FHIR OperationOutcome with more details on the failure or warning. If the request message is processed successfully, whether or not any DocumentReference or DocumentManifest Resources are found, the HTTP status code shall be 200.

The Document Responder shall place into the 'DocumentReference.content.attachment.url' element a full URL that can be used by the Document Consumer to retrieve the document using Retrieve Document transaction.

Example of a response message

<Bundle>
    <id value="021aeba5-1d9d-4c06-92cd-d7c037bbcc" />
    <meta>
        <lastUpdated value="2018-02-16T14:57:34+00:00" />
    </meta>
    <type value="searchset" />
    <total value="1" />
    <link>
        <relation value="self" />
        <url value="http://test.fhir.org/r3/DocumentReference?class=http://example.system.com|patientinstructions&type=urn:oid:2.16.840.1.113883.2.4.4.8|14668157" />
    </link>
    <entry>
        <fullUrl value="http://test.fhir.org/r3/DocumentReference/example" />
        <resource>
            <DocumentReference>
                <id value="example" />
                <meta>
                    <versionId value="1" />
                    <lastUpdated value="2017-11-28T08:30:39+00:00" />
                </meta>
                <contained>
                    <Practitioner>
                        <id value="a2" />
                        <name>
                            <family value="Smitty" />
                            <given value="Gerald" />
                        </name>
                    </Practitioner>
                </contained>
                <masterIdentifier>
                    <system value="urn:ietf:rfc:3986" />
                    <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.7" />
                </masterIdentifier>
                <identifier>
                    <system value="urn:ietf:rfc:3986" />
                    <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.7.1234" />
                </identifier>
                <status value="current" />
                <docStatus value="preliminary" />
                <type>
                    <coding>
                        <system value="urn:oid:2.16.840.1.113883.2.4.4.8" />
                        <code value="14668157" />
                        <display value="PARACETAMOL/CODEINEFOSFAAT RP TABLET 500/50MG (30 ST)" />
                    </coding>
                </type>
                <class>
                    <coding>
                        <system value="http://example.system.com" />
                        <code value="patientsinstructions" />
                        <display value="Patient Medication Instructions" />
                    </coding>
                </class>
                <subject>
                    <reference value="Patient/xcda" />
                </subject>
                <created value="2005-12-24T09:35:00+11:00" />
                <indexed value="2005-12-24T09:43:41+11:00" />
                <author>
                    <reference value="Practitioner/xcda1" />
                </author>
                <author>
                    <reference value="#a2" />
                </author>
                <authenticator>
                    <reference value="Organization/f001" />
                </authenticator>
                <custodian>
                    <reference value="Organization/f001" />
                </custodian>
                <relatesTo>
                    <code value="appends" />
                    <target>
                        <reference value="DocumentReference/example" />
                    </target>
                </relatesTo>
                <description value="Patients Medication Instruction for " />
                <content>
                    <attachment>
                        <contentType value="application/hl7-v3+xml" />
                        <language value="en-US" />
                        <url value="http://example.org/xds/mhd/Binary/07a6483f-732b-461e-86b6-edb665c45510" />
                        <size value="3654" />
                        <hash value="2jmj7l5rSw0yVb/vlWAYkK/YBwk=" />
                    </attachment>
                </content>
            </DocumentReference>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
</Bundle>

Retrieve medication information document(s)

After obtaining the location of the medication information document in the DocumentReference.content.attachment.url, the Document Consumer requests the document from the Document Responder. The Document Responder sequentially serves the document to the Document Consumer. The context that was established in the initial request shall also apply when retrieving/serving the document contents.

Request Message

This message is an HTTP GET request to retrieve the document. See an example below.

GET http://example:9556/svc/fhir/Binary/1e404af3-077f-4bee-b7a6-a9be97e1ce32

The Document Consumer may provide a HTTP Accept header, according to the semantics of the HTTP protocols (see RFC2616, Section 14.1). The only MIME type assured to be returned is the MIME type indicated in the DocumentReference.content.attachment.contentType'. The HTTP If-Unmodified-Since header shall not be included in the GET request.

Response Message

The Document Responder shall process the request message. The Document Responder returns a HTTP Status code appropriate to the processing as well as a Bundle with the medication information in a FHIR Binary Resource. Binary resources behave slightly differently to all other resources on the RESTful API. Specifically, when a read request is made for the binary resource that doesn't explicitly specify the FHIR content types "application/fhir+xml" or "application/fhir+json", then the content should be returned using the content type stated in the resource. e.g. if the content type in the resource is "application/pdf", then the content should be returned as a PDF directly.[1]

When the Document Responder needs to report an error or warning, it shall use HTTP error response codes and should include a OperationOutcome with more details on the failure or warning. If the Retrieve Document message is processed successfully the HTTP status code shall be 200.

Example of a response message

 
<Bundle xmlns="http://hl7.org/fhir">
    <id value="5905e2ee-8505-4f13-8701-63b33b531291" />
    <meta>
        <versionId value="f80e4263-f7ef-4a6f-9996-95ee7607f553" />
        <lastUpdated value="2017-10-25T12:24:26.69+00:00" />
    </meta>
    <type value="searchset" />
    <total value="1" />
    <link>
        <relation value="self" />
        <url value="http://example:9556/svc/fhir/Binary/1e404af3-077f-4bee-b7a6-a9be97e1ce32" />
    </link>
    <entry>
        <fullUrl value="http://example:9556/svc/fhir/Binary/1e404af3-077f-4bee-b7a6-a9be97e1ce32" />
        <resource>
            <Binary>
                <id value="1e404af3-077f-4bee-b7a6-a9be97e1ce32" />
                <meta>
                    <versionId value="948f3653-c9a3-4831-bae5-f629319c194f" />
                    <lastUpdated value="2017-09-20T17:55:14.098+00:00" />
                </meta>
                <contentType value="application/pdf" />
                <content value="JVBERi0xLjUNJeLjz9MNCjU1I........"/>   
            </Binary>
   </entry>
<Bundle>

Interactions, operations, search parameters

Interactions

The following logical interactions are needed for this use case:

• Search
• Read

Operations

There are no defined operations for this use case.

Search parameters

The following search parameter types need to be supported for this use case. No search result parameters need to be supported.

Search parameter types:

• token
• reference
• date
• uri

List of StructureDefinitions

The following HL7 FHIR STU3 StructureDefinitions are defined for MHD:

• http://ihe.net/fhir/StructureDefinition/IHE.MHD.DocumentReference