This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon

7.10 Common Example Scenarios in FHIR

FHIR Infrastructure icon Work GroupMaturity Level: N/AStandards Status: Informative

FHIR is a framework standard that defines a common way to solve healthcare problems and provides a set of resources that can be used in many ways. This page describes how certain common usage scenarios are implemented using the capabilities that FHIR defines. The provided scenarios are examples of usage and are not in any way exhaustive. FHIR can and will be used in a wide variety of circumstances.

In addition, to the information on this page, see also Resource Guide.

Note: Further significant development in the area of consumer centered data exchange is expected for the next release of this specification (R5).

In the PHR scenario, an Electronic Medical Record system (EMR, though many other names and acronyms are also used) provides a RESTful API that allows patients to access their own medical record via a common web portal or mobile application, usually provided by a third party. In this scenario, the PHR provider:

  • Provides the patient with a login that identifies them (or links the patient record to an external identity provided by OpenID, Facebook, Google, etc.)
  • Authenticates the client using an appropriate OAuth server for the login (possibly their own) and restricts the client to viewing records associated with the specific patient (or patients, where appropriate access has been arranged)

The EMR exposes a FHIR server that supports the search and read operations on the following resources:

  1. the Patient resource in order to provide demographics to the client. When a client searches patients with no search criteria, they get a list of all patients they have access to
  2. search and read on the Document Reference resource to provide access to general patient documents in the form of PDFs etc. (PDFs are preferred)
  3. search and read on a set of clinical resources

Here is the Capabilities Statement for this scenario: XML or JSON.

The EMR may also choose to provide additional functionality, such as shared access to patient records by relatives/caregivers, to allow the patient to upload their own documents, medication statements, observations (e.g. from patient monitoring devices) and/or to allow the patient to make appointments. This additional functionality will involve additional API capabilities to be implemented and exposed. The EMR server may also choose to expose the search, read and history operation on the AuditEvent resource for the patient-specific records to allow patient review of record access. Note that all usage of the RESTful API should be logged in an AuditEvent resource.

One common way to integrate healthcare information from a variety of sources is to build a Document Sharing icon community around a patient record.

The most widely adopted framework for Document Sharing icon within institutions, regions, states or countries is IHE icon Cross-Enterprise Document Sharing (XDS) icon, and Cross-Community Access (XCA) icon that allows for federated access to many communities that may be XDS or not.

The Mobile access to Health Documents (MHD) icon defines one standardized interface to Health Document Sharing (a.k.a. an Application Programming Interface (API)) using FHIR Resources. The Mobile Health Document Sharing icon provides a full set of services to support Document Sharing, including Patient Identity Management, Provider Directory, Services Discovery, Consent, Authorizations, Vocabulary, Auditing, and other.

The following FHIR Resources are involved in the Document Sharing icon functionality:

  • The DocumentReference resource describes a document that is located elsewhere. A document registry is a system that maintains a set of Document References
  • The Binary support can be used to store the actual documents on a FHIR server. A repository is a system that stores the binary document in addition to Document References (or sometimes without)
  • Patient, Practitioner and Organization resources provide support for identifying people and organizations
  • The AuditEvent resource tracks usage of the document registry and repository
  • The List resource describes a set of documents that are grouped together. Two uses of this grouping, one for tracking publication - SubmissionSet; and another that is more dynamic - Folder
  • The Consent resource tracks individual Consent status

One common use of healthcare information systems is to integrate some form of decision support software into clinical systems. Common uses of clinical decision support are:

  • Drug-drug interaction checking, and more generally, prescription safety checks
  • Suggesting commonly missed diagnostic data interpretations (including delta checking)
  • Patient surveillance for early warning of deteriorating patient health (both acute and ambulatory care)
  • Identifying candidates for alternative treatment plans for improved efficacy

Note that in addition to clinical decision support, there are also infrastructural uses, such as managing access control.

The various forms of decision support each involve different interaction patterns, so there is no single decision support implementation in the FHIR specification. Generally, the patterns fall into several classes:

  1. The decision comes from an engine entirely hidden behind a system interface and has no direct impact on the data exchange
  2. The decision support engine uses existing data and generates alarm messages concerning patient state that are visible on the FHIR interface
  3. The decision support engine is consulted through a described interface; it accepts a request for, and returns a decision

Any decision support may fall into multiple categories at once, depending on the perspective of a given system.

  1. There is no support required from the FHIR specification, though there will be ongoing review of the contents of the resources to ensure that they support common decision support practices appropriately
  2. There is no suitable resource for this use yet. The Flag resource is intended for clinical notes about the patient, and is not intended for this use. A resource called "Alarm" is under preparation for this purpose
  3. A request for a decision support is understood as a search using a named _query that takes a set of parameters. See below

When a query is initiated in order to get a decision made, the following considerations apply:


  • The request for a decision is made using one of the interaction patterns described for search/query: A RESTful search, a query posted to /Mailbox, a query message, or the Asynchronous query pattern
  • The request has a _query parameter that identifies the decision that is being requested
  • The request also has a set of parameter values. These parameter values may be the data that describes the decision being made or they may be references to specific resources that contain the request. In general, the more complex the decision request is, the more likely it is that a full resource is appropriate, particularly since this provides a ready-made way to record and manage the requests themselves.
  • In some of the query interaction patterns, the resources identified in the parameter value can be bundled up with the request. In others, only the references can be passed
  • Which of the query patterns is most appropriate depends on the complexity of the decision support input, and the length of time the decision is expected to take. As either of these increases, the more complex query patterns become more appropriate


  • If the decision support engine is unable to provide the requested decision, it returns an OperationOutcome Resource describing the issue
  • Otherwise it returns a resource that represents the decision, along with other resources as supporting information, as described by the resource, or applicable profiles
  • In principle, the decision provider can choose to make a copy of the returned decision resource available through a normal RESTful interface, or it can choose not to. This decision may be constrained by applicable profiles, policy decision, or the innate nature of the query
  • If either the decision provider or the requester chooses to retain a copy of the decision, they must ensure that the (lack of) currency of the decision is appropriately considered when it is used

It follows from this then, that decisions that may be requested need at least a response resource defined, and possibly a request resource. This table summarizes known decisions for which resources have been defined.

Decision Resources Invocation
What immunizations should this patient have? Response: ImmunizationRecommendation The exact way to invoke this decision is not yet defined

Implementers are can use existing resources for decisions not documented here, but there is no guarantee that they will be suitable. Improving decision support will be a focus for ongoing development during the Trial Use period.