Section: 1

administration-module.html

Work Group Standards Status:Informative

Administration Module

Introduction

The Administrative module covers the base data that is then linked into the other modules for clinical content, finance/billing, workflow, etc.
It is built on the FHIR technology platform modules.

Before any clinical data can be recorded, the basic information of the patient must be recorded, and then often the basis of the interaction (such as an encounter).

Index

Patient Registers

Track people involved in receiving healthcare, the basics nearly everything else references back to

NameAliasesDescription
Image showing the relationship between resources representing people
Patient linking should also be considered when evaluating searches with references to other resources. e.g. searching for a patients' conditions for a patient.
At present the specification does not define if the links should be also followed to include conditions that reference the linked patients too. We are currently seeking feedback on this. The Person resource may be used as a centralized register of people that may eventually be involved in healthcare, and could be used as the central core demographics register.
However, the fields/values in Person are duplicated in the other resources, and in many cases the Person resource will be hosted on external systems.

Clinical Categorization Resources

Most clinical activities occur grouped in some way. Long term care is typically covered by an EpisodeOfCare, whereas short term care is covered by encounters. Account associates the tracking of transactions back to a Patient (or other resource). Flag is just used to highlight a warning or other notification about a patient (or other resource)

NameAliasesDescription
Image showing the administration interactions
Resources shown with a dotted box are described in other sections of the specification: Coverage and Claim are from the section on Finance.

Service Provider Directory Resources

Service Provider Directory resources are usually stored in the administration section of applications, and may even be synchronized from external systems.

NameAliasesDescription
Image showing the provider directory resources

Scheduling and Appointments

The Scheduling/Appointment resources permit the planning of encounters to occur and follow on with other clinical activities.

NameAliasesDescription
Image showing the scheduling interactions

Devices and Substances

Other assets are often registered in the administration system, and maintained as master files.

NameAliasesDescription

Security and Privacy

Patient privacy is handled with security labels and tags in the Resource Meta property. This is the standard way in which that the FHIR specification provides this supporting information to a sub-system that implements it (which is not defined by FHIR).

One of the more common use cases is for marking a patient as being a celebrity.

Note that privacy considerations apply to Person, Practitioner and RelatedPerson records in addition to Patient's.

While Organization, Location, Device and other non-person-identifying records are generally subject to less stringent security precautions, such data must still be protected to avoid safety issues (e.g. someone maliciously changing the ingredients associated with a drug to cause/fail to cause alerts)

Devices can be linked to Patients. If this occurs, they must be protected as any other patient-linked element

For more general considerations, see the Security and Privacy module.

Common Use Cases

Administration Resources are cornerstone resources that are used by clinical and other domains of the FHIR Standard.

Developmental Roadmap

The Patient Administration is currently working through resources that support:

Many of the administrative resources are part of the core resources that most systems use first and have formed the basis for most people's first experiences with FHIR.
However this limited exposure has still to be proven in all contexts, such as veterinary, public health and clinical research.


async.html

Asynchronous Request Pattern

Maturity Level: 2Standards Status:Draft
the FHIR Asynchronous API and the $export Operation are under active development:

Use Case

All of the interactions defined in the RESTful API are described as synchronous operations - that is, the client makes a query and waits for the server to respond with the outcome in the HTTP response. This pattern is not suitable once significant server side processing becomes necessary or when substantial amounts of data must be returned.

A good example of this is the $export operation, where simple searches may result in large amounts of data.

The asynchronous request pattern, based on rfc 7240, caters to this use case and is applicable for all the Defined Interactions and for Operations, although for many of these uses it brings no benefit. Servers may choose which interactions the pattern should be supported on (if at all), and servers may choose to only support some of the operations using the asynchronous pattern.


Kick Off Request

The request will have whatever URL and other parameters would normally apply, but must include the headers described below.

GET [FHIR API Request]

Headers
Query String Parameters
Response - Success
Response - Error (eg. unsupported search parameter)

Bulk Data Delete Request:

After a bulk data request has been kicked-off, clients can send a delete request to the url provided in the Content-Location header to cancel the request.

Endpoint

DELETE [polling content location]

Response - Success
Response - Error Status

Bulk Data Status Request:

After a bulk data request has been kicked-off, clients can poll the url provided in the Content-Location header to obtain the status of the request.

Note: Clients should follow an exponential backoff approach when polling for status. Servers may supply a Retry-After header with a http date or a delay time in seconds. When provided, clients should use this information to inform the timing of future polling requests.

Note: The Accept header for this request should be application/json. In the case that errors prevent the export from completing, the response will contain a JSON-encoded FHIR OperationOutcome resource.

Endpoint

GET [polling content location]

Response - In-Progress Status
Response - Error Status
Response - Complete Status

File Requests:

Using the urls supplied in the completed status request body, clients can download the generated bulk data files (one or more per resource type). Note: These files may be served by a file server rather than a FHIR specific server. Also, if the requiresAccessToken field in the status body is set to true the request must include a valid access token in the Authorization header in these requests (i.e., Authorization: Bearer {{token}}).

Endpoint

GET [url from status request output field]

Headers

Specifies the format of the file being returned. Optional, but currently only application/fhir+ndjson is supported.

Response - Success
Response - Error

backboneelement-definitions.html

BackboneElement - Detailed Descriptions

Maturity Level: NormativeStandards Status:Normative

BackboneElement


backboneelement.html

BackboneElement

Maturity Level: NormativeStandards Status:Normative

The base definition for complex elements defined as part of a resource definition - that is, elements that have children that are defined in the resource. Data Type elements do not use this type, though a few data types specialize it (Timing, Dosage, ElementDefinition). For instance, Patient.contact is an element that is defined as part of the patient resource, so it automatically has the type BackboneElement.

Note that the descendant types of BackboneElement are all declared implicitly as part of the definitions of the resources.

Content


ballot-intro.html

R4 Ballot Roadmap

Maturity Level: N/AStandards Status:Informative

Welcome to the second round of the FHIR Release 4 (R4) ballot, which is working toward our first release planned to include normative content. The R4 release of FHIR will have content with different ballot statuses:

The FHIR R4 Ballot Process

The FHIR R4 ballot process is significantly more complex than previous ballots because of the introduction of content on the normative track.

Three ballot periods are anticipated:

Draft Ballot Dec 2017 - Jan 2018 This first ballot was mainly a development ballot for the FHIR team. It allowed for:
  • The community to review the packaging and publication of the normative content
  • The FHIR Management Group to hone ballot procedures
  • Ongoing review of the FHIR content - particularly that marked as candidate-normative
Full FHIR Ballot Apr 2018 - May 2018 The full R4 ballot. It included:
  • Multiple packages of normative content (see below)
  • The rest of the content balloted for "Trial Use"
Follow up Ballot Aug 2018 - Sep 2018 A follow up ballot
  • Reballoting of normative content where substantitive changes were required in response to ballot and implementer feedback
  • Additional signficant new (added post the full FHIR ballot) or significantly revised content balloted for "Trial Use"
This is the current ballot

The key driver of this complexity is the introduction of normative content. HL7's ballot rules for normative content require that if any substantiative changes are made as a result of ballot reconciliation, the content must be reballoted. (Note that 'substantiative changes' means any change that is likely to change implementations - a very low bar).

In the past, normative ballots have undergone many cycles of balloting, a process that can take years. The FHIR ballot will be different, in that there are 2 ballot cycles allowed; any normative content that cannot pass ballot with 2 cycles will fall back to Trial Use for R4, and HL7 will try again for FHIR R5. Note that the content on the normative track has already undergone extensive testing, production implementation, and previous ballots.

To facilitate this process, the ballot is broken up into multiple normative packages:

Infrastructure Abstract base types, data types, formats, the RESTful API, and content and typing rules
Terminology and Conformance The terminology infrastructure and the base resources that define FHIR implementations
Patient The Patient resource and related content
Observation The Observation resource and related content

A full list of the pages that are in each normative package can be found below. Any content that is not in these packages is considered to be part of the general Trial Use Ballot.

In addition to these ballots of the core FHIR specification, several implementation guides are undergoing ballot as well.

R4 Ballot Background

Release 4 of the FHIR specification provides thousands of significant changes and enhancements from the third FHIR Standard for Trial Use specification HL7 published in May, 2017. These changes resulted from committee meetings, connectathons, over a thousand change proposals, and collaborations with other standards organizations. A summary of changes and a complete list of changes to resources and data types are available, along with transforms between R3 and R4 for many resources.

The FHIR specification is presented as a series of interlinked HTML pages. They can either be reviewed online or can be downloaded for exploration on your own device. (175MB zip, ~1GB unzipped). The scope of this FHIR Ballot is any page where the URL starts with http://hl7.org/fhir/2018Sep, though balloters must pay careful attention to which ballot package content is in (see below, or the Table of Contents).

A few notes to consider when balloting:

Balloting Guidelines

HL7 ballot rules require that participants sign up prior to opening of the ballot. If you did not sign up in advance, you can still submit comments using the Propose a Change link at the bottom of each page of the specification. Feedback from balloters will be given priority but all suggestions will be considered as much as time allows. (And be sure to sign up to the FHIR list-server and/or follow the #FHIR hash-tag so you don't miss the chance to vote in the next ballot cycle.)

If you are signed up to ballot, you can download the balloting spreadsheet from the Ballot Desktop. All ballot feedback must be provided using the spreadsheet template provided. (There's a help tab that explains the meaning of each of the columns.) For FHIR, you have the option of making your comments directly in the spreadsheet or submitting your comment using the FHIR Change Tracker tool. If you take the latter approach, you must include a reference to each tracker item in your ballot spreadsheet along with a vote (negative, affirmative typo, etc.). The other columns can (and should) be left blank. All spreadsheets must be submitted along with an overall vote by end of day Eastern time on the designated ballot closure date for the comments to be considered as part of ballot disposition.

IMPORTANT: We encourage balloters to capture their comments using the HL7 issue tracker and to use the spreadsheet only to list their tracker item numbers and votes. (If you include additional information beyond tracker item and vote, we need to cross-check to ensure the content is aligned, which eliminates any savings. So if you keep additional columns for internal review, please wipe them before submission.) Tracker-based comment submission dramatically reduces administrative overhead in managing the ballot. It also means that you can receive automatic notifications when your comment is scheduled for discussion, commented on, or resolved.

When submitting your ballot feedback, if you have a general comment on something that you see occurring multiple times, please include at least a couple of specific locations where you see the issue. As much as possible, capture each separate concern as a distinct row in the ballot sheet or separate tracker item. (If using tracker items for your submissions, you MUST still submit a ballot spreadsheet referencing the relevant tracker items.) It makes our job of reconciling much easier. Also, don't forget to fill in the section numbers (gray numbers to the left of each heading) and URLs. Only one URL should be placed in the "url" element or column. If you want to reference additional URLs, include them in the text of your ballot comment.

If you have questions that are interfering with the ability to review the specification or submit ballot comments, please contact one of the co-chairs of the FHIR Management Group: Lloyd McKenzie or David Hay.

Thanks for taking the time to review the FHIR specification. We appreciate any feedback you can provide.

Rules for Round 2 Ballot (Follow up ballot)

This is the round 2 ballot for FHIR R4. As such, the scope of this second ballot for the R4 cycle is limited to the changes made from the 2018-May ballot cycle. Feedback not related to changes made will most likely be found "not related" and/or deferred to consideration as part of R5.

To assist balloters, for the Normative ballot, each substantitive change made is listed, along with links to the page and the task that prompted the change. Also, diff links are provided to assist with reviewing the non-substantitive changes.

For the Trial-Use ballot, the significant new content areas or changes are indicated.

The specification has been updated to include R3/R4 maps and difference analysis, but these have not been updated. This will be done proper to publication of the final specification In the mean time, balloters are welcome to comment on suggested improvements to the mappings and difference statements, but these cannot be the basis for negative votes. Contributions may also be made directly (join the conversation at chat.fhir.org).

The lists below provide 2 "diff" links - these are links that ask a W3C differencing engine to compare the 2 pages of the specification. There are two different types of link:

The W3C differencing engine is the best free html diff engine that we know of, but does have issues. In particular, when reviewing differences for resources and types, the special presentation forms (tables, svg) which are rich in rendering metadata makes the difference analysis a little confusing or even unreliable in places. Reviewers will find it easier to looks the differences for the definitions rather that the tables structures - e.g. when reviewing based on the diffs, review the definitions page changes first.

Normative Ballot Packages

Infrastructure

Abstract base types, data types, formats, the RESTful API, and content and typing rules

Please consult the Round 2 ballot guide above before commenting on this ballot.

Substantive Changes since the first Normative ballot

Description Committee + Tasks Pages
Scope Changes
Mark Managing Resource Identity as trial-use, not normative (move normative parts to Resource)FHIR-I:
Base Documentation
Make it explicit about canonical URLs with fragments FHIR-I:
Added reference.typeFHIR-I:
Clarify definition of is-modifier + impacts on modifier extensions
Note: this lead to breaking changes on a few extensions (changed from modifierExtension to normal extension)
FHIR-I:
Multiple language support on narrativesFHIR-I:
Rules around extensible bindings (intended to be clarifications, but may be substantiative for some)Vocab:
Enhance/extend rules around changes between versionsFHIR-I:
Add note about namespaces in types in FHIRPath consequence to FHIRPath changesFHIR-I:
Add draft Terminology Service API to FHIRPath FHIR-I:
Fix missing code for 1.0.2 FHIR versions Code System FHIR-I:
RESTful API
Add fhirVersion parameter to application/fhir mime type FHIR-I:
Fix HTTP response status codes for If-Match header Breaking change! FHIR-I:
Clarify about 406 and 415 status codes Breaking change! FHIR-I:
Rewrite intermediaries section, and refocus on custom headers FHIR-I:
Clarify version requirements in Location header FHIR-I:
Decribe use of :below on reference for searching canonicals FHIR-I:
Change rules around optionality of Bundle.entry.request and .response Breaking change!FHIR-I:
Add _list parameter to history interactionFHIR-I:
Add conformance language about errors and operation outcomeFHIR-I:
Mark Conditional Create, Update, Patch, and Delete as Trial-useFHIR-I:
Add mode parameter to /metadata FHIR-I:
Search Page
Rename the "recurse" modifier on _include to "iterate" Breaking change! FHIR-I:
Add rule that search parameter names cannot differ only by case FHIR-I:
Describe use of exponential form when searching numbers (+ clarifications for precision) FHIR-I:
Describe use of :below on token for searching mime types FHIR-I:
Introduce special search parameter typeFHIR-I:
Note about timezones (not substantive?)FHIR-I:
Details about searching on versionsFHIR-I:
Operations
Remove support for operations on historical resources Breaking change! FHIR-I:
Add the $versions operationFHIR-I:
Data Types
Fix OID regexFHIR-I:
Allow exponential form for decimals (with corresponding consequences for precision) FHIR-I:
Change Money Type to make it simpler Breaking change! FHIR-I:
Change Identifier.type codes to use v2 codes now that they are defined Breaking change! FHIR-I:,
Change Annotation.text to support markdownFHIR-I:
Add minutes to Duration value setFHIR-I:
Addition of expression in metadatatypes (not normative, but appears in multiple places)FHIR-I:
ElementDefinition
Make it clear and consistent that ElementDefinition specializes BackboneElement FHIR-I:
Clarify use of slicing entryFHIR-I:
Make ElementDefinition.constraint.expression optional, and ElementDefinition.constraint.xpath trial-useFHIR-I:
Add ElementDefinition.sliceIsConstraining (trial-use)FHIR-I:
Change ElementDefinition.binding.valueSet to only be of type Canonical Breaking change! FHIR-I:
Add a note restricting use of ElementDefinition.contentReference FHIR-I:
Make additional constraint on valid Element names FHIR-I:
Resources
Make it clear that contained resources can't contain security labels FHIR-I:
Contained resources MAY contain narrativeFHIR-I:
Remove restriction on Bundle containing multiple versions of the same resource Breaking change! FHIR-I:
Add deleted as an issue type FHIR-I:
New codes, adjustments, and fixed definitions to codes for OperationOutcome.issue.code FHIR-I:,
Deprecate OperationOutcome.locationFHIR-I:
Rename Binary.content to Binary.data and exclude it from summary (which makes it optional) Breaking change! FHIR-I:,

Terminology and Conformance

The terminology infrastructure, and the base resources that specify content

Please consult the Round 2 ballot guide above before commenting on this ballot.

Substantive Changes since the first Normative ballot

Description Committee + Tasks Pages
Scope Changes / General
Remove ConceptMap from Normative package Vocab:
Change the canonical URL for all v2 and v3 CodeSystems and ValueSets to http://terminology.hl7.org (from the Unified Terminology Process) Breaking change! (no task: Vocab committee decision) todo
CodeSystem
Remove codesystem-deprecated extension Vocab:
Rationalise ordinal value extensions (not normative) Breaking change! FHIR-I: (later removed)
Mark section "Code systems with detailed metadata" informative Vocab:
ValueSet
Remove ValueSet.$expand profile parameter, and add parameters from ExpansionProfile Breaking change! Vocab: &
Remove ValueSet.$expand.limitedExpansion parameter, and document how to use count instead Breaking change! Vocab:
Document Valueset.expansion.parameters better, along with new requirements Vocab:,,
Move Valueset.extensible to an extension Vocab:
Add note about Supplements and future rules around expansions Vocab:
Add datetime as an allowed type for ValueSet.expansion.parameter.value Vocab:
Add "Any Version" special value for ValueSet.compose.include.version Vocab:
Allow a value set to contain neither compose or expansion (metadata only) Breaking change? Vocab:
Add contextDirection as a parameter for $expand Vocab:
StructureDefinition
Update StructureDefinition invariants FHIR-I:
CapabilityStatement
Mark many attributes in CapabilityStatement as trial-use FHIR-I:
Fix minor errors in CapabilityStatement invariants FHIR-I:
Make CapabilityStatement.rest.resource.searchParam.definition mandatory for search parameters defined in the FHIR Specification Breaking change! FHIR-I:
Add CapabilityStatement.implementation.custodian FHIR-I:
Change all documentation elements in CapabilityStatement to use markdown FHIR-I:
Add CapabilityStatement.imports FHIR-I:
Fix search parameter generation so that context related search parameters are defined FHIR-I:
Revoke constraint cpb-8 on CapabilityStatement.rest cardinality FHIR-I:
OperationDefinition
Add OperationDefinition.title FHIR-I:
Add OperationDefinition.parameter.referencedFrom FHIR-I:

Patient

The Patient resource, and related content

Please consult the Round 2 ballot guide above before commenting on this ballot. Patient is being reballoted solely because of changes driven by terminology standardization, which means that the Coding.system values for Patient.maritalStatus and Patient.contact.relationship. There is no other change.

Substantive Changes since the first ballot

Description Committee + Tasks Pages
Change the canonical URL for all v2 and v3 CodeSystems and ValueSets to http://terminology.hl7.org (from the Unified Terminology Process) (no task: Vocab committee decision) todo

Observation

The Observation resource, and related content

Please consult the Round 2 ballot guide above before commenting on this ballot.

Substantive Changes since the first ballot

Description Committee + Tasks Pages
Change the canonical URL for all v2 and v3 CodeSystems and ValueSets to http://terminology.hl7.org (from the Unified Terminology Process) (no task: Vocab committee decision) todo
Updated the definition of subject and added a note to the FHIR safety page about not being surprised by the focus element. OO:
Created a standard extension event-relatedArtifact to reference other knowledge resources used for citations and documentation of the Observation instance. OO:
Created a standard extension event-supportingInfo to reference other resources from the patient record that were used in creating the Observation instance. OO:
Created a standard extension observation-precondition to reference other observations that must be known to correctly interpret the observation. OO:
The code system for value set observation-interpretation is changed from HL7 Version 2 Table 0078 to v3-ObservationInterpretation as part of the HL7 Unified Terminology Governance Project. Added clarifying text to indicate that all use cases where interpretations are relevant might not be covered by the observation-interpretation value set. Breaking change! OO:, UTG Process
Changed cardinality of Observation.interpretation and Observation.component.interpretation from 0..1 to 0..* OO:
Added guidance on how other observations or code translations provide additional context that may alter the semantics of the observation. OO:
Changed Observation.context to Observation.encounter and changed type from Reference(EncounterIEpisodeOfCare) to Reference(Encounter). Update search parameter definition and add a standard extension event-episodeOfCare. Breaking change! OO:

Trial-Use R4

This ballot includes everything else not listed above, including draft, informative and externally derived content. Balloters are welcome to comment about these, though there is no difference between ballot comments on these content and normal content.

There have been many changes to the content; balloters should use the "Ballot Comparison" link at the bottom of page to compare the differences. For implementer convenience, some of the more signficant (not all) changes are listed here:


best-practices.html

Best Practices

Maturity Level: N/AStandards Status:Informative

The base FHIR specification is used across the world in many different contexts, with a great variety of use cases. There are many existing restrictions from common practice and regulation that constrain the agreements that the specification represents. In particular there are large amounts of existing data in legacy record stores that need to represented and exchanged using FHIR resources.

The requirements analysis that occurs during the design of the FHIR process often leads to a clear understanding of how information should be represented, but also can make clear that for a variety of reasons, such best practices cannot be imposed as standards requirements in all contexts. However, it is useful for the FHIR standard to be able to docuemnt what are known best practices.

Committees can document best practice by one of two different ways:

When using the FHIR validator, implementers are able to ask for best practice rules to be enforced if they wish.

This page indexes the best practices documented in this specification:


cda-intro.html

Clinical Document Architecture (CDA) on FHIR

Maturity Level: N/AStandards Status:Informative

What is CDA on FHIR?

CDA on FHIR specifies how to implement CDA R2 with the FHIR Composition resource.
The original HL7 Clinical Document Architecture (CDA) defined the structure and semantics of "clinical documents" for the purpose of exchange. A clinical document is a documentation of clinical observations and services, with the following characteristics:

A CDA document on FHIR is a defined and complete information object that can include text, images, sounds, and other multimedia content.

Scope of the CDA on FHIR

The scope of CDA on FHIR is the standardization of clinical documents for exchange.

The data format of clinical documents outside of the exchange context (e.g. the data format used to store clinical documents) is not addressed in this specification.

CDA on FHIR does not specify the creation or management of documents, only their exchange markup. While it may be possible to directly use the CDA Schema in a document authoring environment, such use is not the primary purpose of the CDA specification.

Document management is critically interdependent with the CDA specifications, but the specification of document management messages is outside the scope of the CDA.

Goals and Design Principles

The goals of CDA on FHIR are:

A number of design principles follow from consideration of the above goals:

General CDA on FHIR Concepts

Major Components of a CDA on FHIR Document

This section serves as a high-level introduction to the major components of a CDA document, all of which are described again and in greater detail later on. The intent here is to familiarize the reader with the high-level concepts to facilitate an understanding of the sections that follow. [EDITORS: in CDA r2 there is a bunch of detail about how CDA is wrapped - and an example. Consider whether the discussion is relevant here: "A CDA document is wrapped by the <ClinicalDocument> element, and contains a header..."]

Human Readability and Rendering CDA Documents

The CDA requirement for human readability guarantees that a receiver of a CDA document can algorithmically display the clinical content of the note on a standard Web browser.

These principles and requirements have led to the current approach, where the material to be rendered is placed into the Section.content. [EDITORS: The current design doesn't make it clear where to consistently find narrative.]


change.html

Appendix: The Role of Informatics in the Shift from Reactive to Proactive Healthcare

Maturity Level: N/AStandards Status:Informative

FHIR offers more than a standard solving existing problems in interoperability, it provides a platform for the future. Interoperability is "all about the people"; in order to get past the peak of inflated expectations to the plateau of productivity on the hype cycle it is imperative that there is a shared vision of what is trying to be achieved. Healthcare is in the midst of a transformation driven by the convergence of biological and information revolutions, by economic imperative and social change. FHIR's strength lies in it being grounded in the real world which is changing rapidly. This appendix offers a high-level view of the disruption underway and helps place FHIR into a wider context.

Just as John Snow used a branch of informatics and geospatial analysis to identify the source of cholera in London and so prove the germ theory and revolutionize medicine in 1854, so too will the application of informatics and associated technology be instrumental in the next big change in healthcare.

In countries with advanced economies, health systems are facing increased demand from aging populations and increased incidence of chronic disease. In many of these countries, there is also a shortage of skilled workers. Mounting evidence points to avoidable errors causing serious harm to patients. Indeed, optimal care only occurs about half the time in even the best performing health systems (1). Small incremental improvements will not be enough to address the looming crisis in sustainable healthcare.

Convergence of trends in health care, biology, informatics and technology together with the associated social changes and economic imperative is driving a paradigm shift (2) that may be the answer. Informatics has a role in most aspects of this. The figure below provides a summary of the convergence of these trends and the likely results of disruption that will move us from reactive to proactive healthcare.

In terms of our understanding of physiological pathways, informatics is now the major tool of molecular biology. For example, the time spent computing exceeds chemical analysis for gene sequencing by 3 to 1. Informatics is being used to map neural networks and to build the models of systems biology (3) with ever increasing levels of precision and complexity that can't be done without the help of machines. Our understanding has changed so much in recent times that the American Academy of Science is now arguing that it is time for a new taxonomy (4).

Personalization is occurring both because of social change and increased biological knowledge and is being facilitated by cheap mobile computing, sensors and devices. These social forces and the enabling technologies are allowing greater participation by 'non-experts' in decision making, treatment, discovery and knowledge management.

Greater knowledge about how we think (5), advances in the information sciences and the increased availability of computing power means that our capacity to acquire knowledge and use it to predict the course of pathology has increased enormously, and that is fortuitous, because the explosion of information is impossible to deal with otherwise. These new capabilities can be used to provide better advice and to better prevent disease through discovery, monitoring and treatment.

The health system itself can also benefit from what looks like a second phase of utilization of information technology through on-line care provision, real integrated measurement of quality and integration of knowledge in work-flow. With openness and transparency there is also the prospect of co-opetition (cooperative competition) and with integrated outcome measures that pay-for-success contracting can be used as an economic lever.

Large scale change in the way healthcare is done is both essential and inevitable. It is likely that this will derive from the merging of the knowledge and machines of the biological and information revolutions facilitating a shift from reactive treatment to proactive personalized medicine. Only by such significant changes could the needed quantum improvement in the effectiveness and efficiency of healthcare be made.

The development of digital technology has disrupted other sectors, notably media, retail and manufacturing, and the health sector is unlikely to remain immune (6). Digitization of biology and health will allow machines to help, lead to a demystification of disease, the democratization of healthcare, and a move from the treatment of disease to the promotion and maintenance of wellness.

References

  1. CareTrack: assessing the appropriateness of health care delivery in Australia. Runciman WB, Hunt TD, Hannaford NA, Hibbert PD, Westbrook JI, Coiera EW, Day RO, Hindmarsh DM, McGlynn EA, Braithwaite J. 2, 16 July 2012, Med J Aust. 2012 Jul 16;197(2):100-5. PubMed PMID: 227, Vol. 197(2), pp. 100-5
  2. Kuhn, Thomas S. The Structure of Scientific Revolutions. Chicago : University of Chicago Press, 1962
  3. Hood, Leroy. Institute of Systems Biology. [Online] [Cited: 25 May 2013.] https://www.systemsbiology.org/leroy-hood
  4. Board on Life Sciences, Committee on A Framework for Developing a New Taxonomy of Disease. Toward Precision Medicine; Building a Knowledge Network for Biomedical Research and a New Taxonomy of Disease. Washington, DC : The National Academic Press, 2011
  5. Kahneman, Daniel. Thinking, Fast and Slow. New York : Farrar, Straus and Giroux, 2011
  6. Topol, Eric. The Creative Destruction of Medicine - How the Digital Revolution Will Create Better Health Care. New York : Basic Books, 2012.

This page maintained by Michael Legg


clinicalreasoning-cds-on-fhir.html

Work Group Maturity Level: 2Standards Status: Trial Use

Clinical Decision Support Services

This section of the clinical reasoning module discusses the evaluation use case for clinical decision support and how the various knowledge artifacts can be integrated into clinical workflow. The topic focuses on two main scenarios:

  1. Using CDS Hooks to evaluate remote clinical decision support
  2. Using CDS Hooks to surface clinical decision support behavior

Note that this topic is a very high-level approach to using CDS Hooks to support these two use cases. It is not a normative description of any of the CDS Hooks content. Please refer to the CDS Hooks specification itself for more details. At the time of this publication, the CDS Hooks specification has been balloted but is still in the process of being published. Because the links on this page deep-link the CDS Hooks specification, they are still referencing the original CDS Hooks specification. When it is published, the CDS Hooks specification will be located at http://cds-hooks.hl7.org.

Consuming Decision Support Using CDS Hooks

CDS Hooks is an open source specification focused on user-facing remote clinical decision support. CDS Hooks can use FHIR to represent patient information and recommendations, but is architecturally an independent specification. The basic components of CDS Hooks are:

ServiceA decision support service that accepts requests containing patient information, and provides responses
HookA defined point within the client system's workflow with well-known contextual information provided as part of the request
EHRAn electronic health record, or other clinical information system that consumes decision support in the form of services
CardGuidance from decision support services is returned in the form of cards, representing discrete recommendations or suggestions that are presented to the user within the EHR
Configuration

The first phase in consuming a CDS Service using CDS Hooks is to configure the integration from the EHR. The CDS Service publishes a set of endpoints to advertise available functionality using the discovery endpoint. For each endpoint, the service declares the hook during which it expects to be invoked, and optionally, any prefetch information that could be provided to the service.

Each hook identifies contextual information that is available within the EHR. For example, the medication-prescribe hook specifies the patient in context, as well as the medications being prescribed. When invoking the service from this hook, the EHR is expected to provide this contextual information as part of the request.

In addition, the CDS Service may specify additional information using prefetch templates. Each prefetch template is a FHIR query URL, parameterized by the data available in context, and describing information needed by the CDS Service to perform its processing. By providing this information as part of the request, the EHR alleviates the need for the CDS Service to request the additional information.

The following example illustrates a typical service discovery response:

{
  "services": [
    {
      "hook": "medication-prescribe",
      "prefetch": {
        "medication": "MedicationOrder?patient\u003d{{context.patientId}}\u0026status\u003dactive"
      },
      "title": "Opioid Morphine Milligram Equivalence (MME) Guidance Service",
      "description": "CDS Service that finds the MME of an opioid medication and provides guidance to the prescriber if the MME exceeds the recommended range.",
      "id": "cdc-opioid-guidance"
    },
    {
      "hook": "patient-view",
      "prefetch": {
        "patient": "Patient/{{context.patientId}}"
      },
      "title": "Zika Virus Intervention",
      "description": "Identifies possible Zika exposure and offers suggestions for suggested actions for pregnant patients",
      "id": "zika-virus-intervention"
    },
}
Evaluation

The second phase is the actual request/response call to the CDS Service. Once the integration has been configured using the above information, the EHR can make requests to decision support services at the appropriate times based on the hooks it supports. To make a request, the EHR prepares a request object containing the contextual information required for the hook, as well as any additional prefetch information.

For example, the following request illustrates a call to the cdc-opioid-guidance service:

{
  "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
  "fhirServer": "https://example.org/fhir",
  "hook": "medication-prescribe",
  "context":
    {
      "medications": [
        {
          "resourceType": "MedicationOrder",
          "id": "medrx001",
          ... <FHIR Resource - snipped for brevity>
        }
      ],
      "patientId": "Patient/Patient-12214",
      "userId": "Practitioner/example"
    },
  "patient": "Patient/Patient-12214",
  "prefetch": {
    "medication": {
      "resource": {
        "resourceType": "Bundle",
        "entry": [
          {
            "fullUrl": "https://example.org/fhir/open/MedicationOrder/medrx002",
            "resource": {
              "resourceType": "MedicationOrder",
              "id": "medrx002",
              ... <FHIR Resource - snipped for brevity>
          }
        ]
      }
    }
  }
}

This request identifies:

The service responds with a set of cards describing any recommendations or suggestions that should be presented to the user:

{
   "cards":[
      {
         "summary":"High risk for opioid overdose - taper now",
         "detail":"Total morphine milligram equivalent (MME) is 110 mg/d. Taper to less than 50.",
         "indicator":"warning",
         "source": {
           "label": "Centers for Comprehensive Disease Control (CDC)",
           "url": "http://cdc.gov"
         },
         "suggestions":[
            {
               "label": "Total morphine milligram equivalent (MME) is 110 mg/d. Taper to less than 50.",
               "actions":[
                  {
				     "type": "update",
                     "description":"Total morphine milligram equivalent (MME) is 110 mg/d. Taper to less than 50.",
                     "resource": { ... <Updated FHIR Resource - snipped for brevity> ... }
                  }
               ]
            }
         ],
         "links":[
            {
               "label":"CDC guideline for prescribing opioids for chronic pain",
               "type": "absolute",
               "url":"https://www.cdc.gov/mmwr/volumes/65/rr/rr6501e1.htm"
            },
            {
               "label":"MME Conversion Tables",
               "type": "absolute",
               "url":"https://www.cdc.gov/drugoverdose/pdf/calculating_total_daily_dose-a.pdf"
            }
         ]
      }
   ]
}

Each card contains:

At this point, the EHR processes the response and determines the most appropriate mechanism for displaying the results to the end-user. However, it is often the case that the results of the decision support interaction need to be persisted for future reference. The GuidanceResponse and RequestGroup resources provide a general mechanism that supports this use case.

In general, a CDS Hooks Response can be captured as a single GuidanceResponse that represents the overall response from the CDS Service, and a single RequestGroup containing the cards and suggestions, as illustrated by the following object-level mappings:

CDS Hooks ObjectFHIR Resource MappingDescription
ResponseGuidanceResponse and RequestGroupA CDS Hooks Response is 1 to 1 with a GuidanceResponse and an associated RequestGroup
CardRequestGroup.actionEach Card in the response is represented as a top level action in the RequestGroup. The selectionBehavior of the action (i.e. among suggestions on the card) is specified by the selectionBehavior element of the card.
SuggestionRequestGroup.action.actionEach suggestion on a card is represented as a nested action within the action for the card. The selectionBehavior of the action (i.e. among the actions described in the suggestion) is all, because CDS Hooks specifies that when a suggestion is accepted, all the actions on the suggestion are performed.
ActionRequestGroup.action.action.actionEach CDS Hooks Action on a card is represented as a nested action within the RequestGroup action for the suggestion, and the resource in the CDS Hooks Action populates the resource element of the RequestGroup action.

And the following table lists the element-level mappings:

CDS Hooks ElementFHIR Resource Mapping
Request.hookInstanceGuidanceResponse.requestId & RequestGroup.identifier
Request URLGuidanceResponse.moduleUri & RequestGroup.instantiatesUri
Response statusGuidanceResponse.status
Request PatientGuidanceResponse.subject & RequestGroup.subject
Request timeGuidanceResponse.occurrenceDateTime & RequestGroup.authoredOn
Request serviceGuidanceResponse.performer & RequestGroup.author (as a Device)
Response.cardRequestGroup.action
Response.card.summaryRequestGroup.action.title
Response.card.detailRequestGroup.action.description
Response.card.indicatorRequestGroup.priority | RequestGroup.action.resource.priority, using the mapping specified here
Response.card.sourceRequestGroup.action.relatedArtifact.where(type = 'documentation')
Response.card.selectionBehaviorRequestGroup.action.selectionBehavior
Response.card.suggestionRequestGroup.action.action
Response.card.suggestion.labelRequestGroup.action.action.title
Response.card.suggestion.uuidRequestGroup.action.action.id
Response.card.suggestion.actionRequestGroup.action.action.action
Response.card.suggestion.action.typeRequestGroup.action.action.action.type
Response.card.suggestion.action.descriptionRequestGroup.action.action.action.description
Response.card.suggestion.action.resourceRequestGroup.action.action.action.resource

Note that these examples all assume a FHIR DSTU2 service is being used.

To support these scenarios, this module defines the CDS Hooks GuidanceResponse and CDS Hooks RequestGroup profiles.

Surfacing Clinical Decision Support Guidance Using CDS Hooks

In addition to supporting the user-facing remote decision support use case, CDS Hooks can be used to surface clinical decision support behavior represented by knowledge artifacts in the Clinical Reasoning module. In this use case, a FHIR server functioning as a knowledge provider exposes CDS Hooks Services using the discovery endpoint, and provides guidance using the CDS Service endpoint. To support this, several mappings from Clinical Reasoning functionality to CDS Hooks services are used:

  1. Hooks - Hooks in CDS Hooks are mapped to the TriggerDefinition structure in FHIR
  2. Services - Services in CDS Hooks are mapped to the PlanDefinition resource in FHIR to provide evaluation behavior
  3. Prefetch - Prefetch templates in CDS Hooks are mapped to the DataRequirement structure in FHIR
Representing Hooks in FHIR

A hook in CDS Hooks is a pre-defined point in the workflow of a clinical information system such as an EHR. Each hook defines context, which is the information available as part of the current activity in the system. Each hook represents a point in the workflow that can be augmented by decision support from an external system. Within CDS Hooks, each hook defines the set of available context values, along with whether or not that context value can be used as a prefetch token.

For example, the patient-view hook defines patientId and encounterId as context values, and indicates that they are both available for use as prefetch tokens (meaning that they can be used to parameterize prefetch templates).

Within FHIR, the concept of a hook can be represented using a combination of TriggerDefinition and ParameterDefinition:

CDS Hooks ElementFHIR Mapping
Hook.nameTriggerDefinition.where(type = 'named-event').name
Hook.context.fieldParameterDefinition.name
Hook.context.priorityParameterDefinition.min & ParameterDefinition.max
Hook.context.descriptionParameterDefinition.documentation & ParameterDefinition.type & ParameterDefinition.profile

Note that using TriggerDefinition to represent hook information requires that hook details be duplicated everywhere they are used. Another approach would be to use the EventDefinition resource to capture the hook information once, and then reuse that by reference wherever it is needed.

Representing Services in FHIR

A service in CDS Hooks is a clinical decision support service that can be used to provide guidance to users at pre-defined points in a workflow. The PlanDefinition resource can be used to describe the behavior of decision support functionality, which can then be exposed via a CDS Hooks service. In the simplest case, there is a one-to-one correspondence between a PlanDefinition and a CDS Service:

CDS Hooks ElementFHIR Mapping
Service.idPlanDefinition.url (without the base)
Service.titlePlanDefinition.title
Service.descriptionPlanDefinition.description
Service.hookPlanDefinition.action.trigger
Service.prefetchPlanDefinition.data-requirement

To support this representation, this module defines a CDS Hooks Service PlanDefinition profile, which also supports specifying the CDS Hooks endpoint on which the PlanDefinition should be exposed.

The PlanDefinition/$apply operation can then be used to provide the behavior of the CDS Hooks service, as described in the Processing CDS Hooks Requests section below.

Representing Prefetch in FHIR

In addition to the contextual information defined by the hook, services in CDS Hooks can request that additional information be supplied with each request in the form of prefetch templates. These templates are parameterized FHIR query URLs that can be fulfilled by the EHR as part of the request, reducing the number of round-trips between the CDS Service and the EHR's FHIR server.

The concept of prefetch data is represented within Clinical Reasoning as a DataRequirement, which can be transformed to an instance level read or type level search interaction as follows:

DataRequirement ElementMapping to FHIR URL
type[type]{[id] | ?[parameters]}
subjectsubject={{patientId}}
codeFilter[path]{=|:in}[code|valueSet]
dateFilter[path]{eq|lt|gt|ge|le}[valueDateTime|valuePeriod|valueDuration]
sort_sort=[sort]
limit_limit=[limit]

This prefetch data can be automatically determined from the data requirements of the PlanDefinition, and provided as part of the service definition to the CDS Hooks discovery response.

Processing CDS Hooks Requests

Once the available PlanDefinition resources are advertised through the discovery endpoint, a CDS Hooks endpoint can be used to perform the actual evaluation, as illustrated in the following diagram:

Surfacing Clinical Reasoning Behavior via CDS Hooks

As depicted in the above diagram, an EHR invokes a CDS Hooks request at the appropriate point in the workflow, providing the requested context and data. The CDS Service responds by performing an $apply operation against the specified PlanDefinition, and transforming the resulting RequestGroup into a CDS Hooks response.

Because PlanDefinitions can be used in a broad range of use cases, this module defines the CQL Library and Computable PlanDefinition profiles to describe the special case of a PlanDefinition being used as an event-condition-action rule with conditions and other dynamic behavior specified in a CQL Library. This arrangement provides a common and consistent pattern for describing decision support that can be easily integrated using the CDS Hooks specification.


clinicalreasoning-knowledge-artifact-distribution.html

Work Group Maturity Level: 2Standards Status: Trial Use

Sharing Knowledge Artifacts

One of the primary use cases of the Clinical Reasoning Module is to enable the sharing and distribution of computable clinical knowledge artifacts:

Knowledge Artifact Sharing

The distribution use case involves enabling knowledge artifacts to be distributed as resources via a FHIR server. The search and read interactions defined by the FHIR infrastructure can be used for this purpose. The Library, ActivityDefinition, PlanDefinition, Questionnaire, and Measure resources can all be used to represent knowledge artifacts, and so define several search parameters specifically to enable searching based on the various attributes of a knowledge artifact. A FHIR service that supports at least searching and retrieval of these resources is then a basic Knowledge Artifact Repository. More advanced knowledge management capabilities such as change management, semantic indexing, and dependency tracking can all be provided on top of this basic infrastructure.

In particular, the useContext and topic elements are intended to provide both semantic and topical indexing functionality for use in knowledge repositories. For example, the following fragment illustrates the use of the useContext element to indicate semantic usage context for an example suicide risk order set:

  <coverage>
    <patientAgeGroup>
      <coding>
        <system value="http://snomed.info/sct"/>
        <code value="133936004"/>
        <display value="Adult"/>
      </coding>
    </patientAgeGroup>
    <clinicalFocus>
      <coding>
        <system value="http://snomed.info/sct"/>
        <code value="87512008"/>
        <display value="Mild major depression"/>
      </coding>
    </clinicalFocus>
    <clinicalFocus>
      <coding>
        <system value="http://snomed.info/sct"/>
        <code value="394687007"/>
        <display value="Low suicide risk"/>
      </coding>
    </clinicalFocus>
    <targetUser>
      <coding>
        <system value="http://snomed.info/sct"/>
        <code value="309343006"/>
        <display value="Physician"/>
      </coding>
    </targetUser>
    <clinicalVenue>
      <coding>
        <system value="http://snomed.info/sct"/>
        <code value="440655000"/>
        <display value="Outpatient environment"/>
      </coding>
    </clinicalVenue>
  </coverage>

The useContext element can contain any number of characteristics that define the particular context of use for the artifact. Note that the base resource does not communicate the intended semantics when multiple useContext elements are present. To accomplish this, a core extension is defined, usagecontext-group. All use contexts within a group apply, while groups of use contexts indicate that any group applies.

In addition, the useContext element is intended to convey prescriptive semantics about the appropriate context of use for an artifact, while the topic element is intended to convey descriptive semantics suitable for indexing and searching using the topic search parameter.

The FHIR search interaction specifies that search results are returned in a Bundle, and the entries in that bundle allow a score to be specified, consistent with the Decision Support Service (DSS) relevance result. Note that the DSS score range is 1 to 100, while the FHIR score range is 0..1.

The algorithm for determining relevance is not prescribed by this guidance. When calculating relevance, implementations are encouraged to take advantage of the metadata represented within the artifact to help users understand the relevance of the returned artifacts to their search criteria.

To reduce the size of returned results and ensure efficient searching and retrieval, the Bundle returned SHOULD consist only of resources of the requested type. Dependencies of the resources returned SHOULD NOT be included unless specifically referenced by including the resources using the _include and _revinclude parameters.

Support for two different distribution use cases can be provided using the basic GET interaction:

The following table lists the search criteria elements defined by the Decision Support Service (DSS) standard along with their appropriate representation in FHIR:

DSS Search CriteriaFHIR Equivalent
Maximum Results_count global search parameter
Minimum ScoreKnowledgeArtifact.minScore search parameter
Knowledge Artifact TraitKnowledge search parameters (identifier, topic, title, description, version)
Knowledge Artifact StatusKnowledgeArtifact.status search parameter
Evaluation Result SemanticsNot Implemented
Data RequirementsNot Implemented
Relationships to specific Knowledge ArtifactsNot Implemented

Support for exclusion criteria as described in the DSS is provided by the :not search parameter modifier of FHIR.

Implementing at least the FHIR search and get interactions for the clinical reasoning resources (Library, ActivityDefinition, PlanDefinition, and Measure) is then a basic implementation of a Knowledge Artifact Repository. For example, the following GET retrieves all measures that reference a specific value set:

GET [base]/ValueSet/zika-affected-areas?_revinclude=Library:depends-on&_revinclude:recurse=Measure:depends-on

More sophisticated management functionality including semantic indexing, change management, and dependency tracking can be provided on top of this basic functionality using the same resource structures.