Section: 23

usecases.html

Common Example Scenarios in FHIR

Maturity 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 different 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.

Personal Health Record (PHR)

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:

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/carers, 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.

Document Sharing (XDS)

One common way to integrate healthcare information from a variety of sources is to build a repository of documents around a patient record. Building a repository of documents allows for less stringent alignment around policy, procedures and record-keeping/informatics standards.

The most widely adopted framework for sharing documents within institutions, regions, states or countries is IHE Cross-Enterprise Document Sharing (XDS). XDS allows for a federated system of repositories with a registry to provide coordinated access to the documents.

FHIR provides equivalent functionality to XDS that can be used to implement XDS behind the existing XDS.b interface, to provide a simpler mobile-friendly interface to an existing XDS ecosystem, or to link document sharing into other functionality provided through a FHIR interface.

The following FHIR Resources are involved in the XDS functionality:

At present, IHE is working with the FHIR project team to use FHIR for Mobile Health Documents (MHD).

Decision Support

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:

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 particular system.

  1. There is no particular 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

Explicit Requests for Decisions

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

Request

Response

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 allowed to 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.


validation.html

Validating Resources

Maturity Level: N/AStandards Status:Informative

This page provides an overview of how the FHIR specification supports validation of resources.

Validating a resource means, checking that the following aspects of the resource are valid:

There are multiple ways to validate resources. This table summarizes the options described in this specification, and which of the aspects above they can validate:

Method XML JSON RDF Structure Cardinality Values Bindings Invariants Profiles Questionnaires Business Rules
XML Schema
XML Schema + Schematron 1
JSON Schema 2
ShEx 3
Validator
Validation Operation4

Notes:

  1. Schematron generated for a profile can test cardinality and invariants, but not bindings, and slicing is not really supported well
  2. JSON schema generated for a profile can test cardinality, and slicing is partially supported
  3. ShEx can enforce some bindings for well understood terminologies, but this is an ongoing area of development
  4. It is at the discretion of the server how much validation to perform, but most servers use the validation jar, or code derived from it, and offer the same services. Some servers also offer a web interface

Note that all these validation methods are incomplete; they can only validate the computable aspects of conformance. There are always additional rules made in narrative that they are not able to check (e.g. a rule such as "All the clinically important content in the data SHALL be in the narrative", which might be made in an implementation guide, but could never be checked by a conformance tool).

In case of disagreement between these conformance methods, note that:

Also, note that static testing of resource content is not enough to prove conformance to the specification. For further information, see FHIR Conformance Testing.

Correct Use of Validation

Servers and clients may be configured to validate content when it is received (e.g. some of the public testing services validate resources on create/update). This can be done both during development and in production use of applications in healthcare processes. While use during the development cycle is highly recommended, use during production might not always be a good idea:

On the other hand, validation during production use may be very important:

Generally, following Postel's law is recommended:

An implementation should be conservative in its sending behavior, and liberal in its receiving behavior.

Applications should consider carefully how much validation beyond the security related issues to perform at run-time, and how errors will be handled.

Using the XML schema

The XML schema can be used to validate XML representations of the resources. When validating a resource, you can nominate one of the following schema:

In addition, the validation schema includes schematron that can be initiated with transform "iso_svrl_for_xslt2.xsl" included in the XML Tools download. Note that XSLT2 is required to run the schematrons.

When running the schematron, use the file "fhir-invariants.sch". This includes all the schematrons. The individual schematron files for each resource are provided to allow implementers to build their own smaller combined file that covers the relevant resource types for them.

Using the JSON schema

The JSON schema can be used with JSON schema validation software. Links:

Using the FHIR Validator

The FHIR Validator is a Java jar that is provided as part of the specification, and that is used during the publication process to validate all the published examples. To execute the FHIR validator, follow the following steps:

Here is an example windows batch file that demonstrates the process (using the common utilities wget and 7z):

@ECHO OFF

 ECHO get the validator and unzip it 
 wget http://build.fhir.org/validator.zip
 7z.exe x validator.zip

 ECHO 1. First example shows how to validate against the base spec:
 ECHO   a. get an example to validate
 wgetpatient-example.xml -O pat-ex.xml

 ECHO   b. validate it against FHIR R3 
 java -jar org.hl7.fhir.validator.jar pat-ex.xml -version 3.0

 ECHO 2. Second example shows how to validate against a profile in the spec:
 ECHO   a. get an example to validate
 wgetobservation-example-heart-rate.xml -O obs-ex.xml

 ECHO   b. validate it
 java -jar org.hl7.fhir.validator.jar obs-ex.xml -version -profile http://hl7.org/fhir/StructureDefinition/heartrate

 ECHO 3. Third example shows how to validate against a profile in an implementation guide:
 ECHO   a. get an example to validate
 wgetobservation-example-heart-rate.xml -O obs-ex.xml

 ECHO   b. validate it. note that you have to tell the validator where to get the implementation guide information
 java -jar org.hl7.fhir.validator.jar obs-ex.xml -version 3.0 -ig http://hl7.org/fhir/us/core -profile http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient

 ECHO Press Any Key to Close
 pause

Note that it is not necessary to download the resource first; the http address can be supplied directly:

 java -jar org.hl7.fhir.validator.jar/patient-example.html -profile http://hl7.org/fhir/StructureDefinition/Patient

The validator requires an underlying terminology server. By default, this is http://fhir3.healthintersections.com.au. For further details of the parameters supported by the validator, see Using the FHIR Validator

Asking a FHIR Server

The operation validate can be used to check whether a resource conforms to a profile. The simplest way to execute this operation is to post the resource to a server:

 POST [base]/Observation/$validate?profile=http://hl7.org/fhir/StructureDefinition/heartrate
 [other HTTP headers]
 
 <Observation>... resource to check as the body

The server will return an OperationOutcome resource listing issues found in the resource.

There are several things to consider when using this operation:

Via a web interface

Some servers expose the $validate functionality through a web page. For known public implementations, see the FHIR Confluence page


versioning.html

Managing Multiple FHIR Versions

Maturity Level: N/AStandards Status:Informative

This FHIR specification is one in a series of publications of the FHIR specification. There have been previous releases, and there will be subsequent releases. Each release (or "version") introduces new features, and changes from the previous releases.

Implementers should be familiar with the kind of changes that can be made, and the change processes that apply - see the FHIR Version Management Policy for further information

Ongoing change to the specification means that implementers must be able to determine which version is in use in their context, and implement accordingly.

There are 3 ways to determine the version of FHIR in use:

CapabilityStatement.fhirVersion

Whenever resources are exchanged, the applicable FHIR version applies to the entire interaction, not just the resources. The semantics of the mime types, the RESTful URLs, the search parameters, and the overall interaction are bound to a particular FHIR version. The resource versions must be consistent with the overall interaction. It’s not possible for client/server (or, for messaging, sender/receiver) to have a coherent conversation without first agreeing on the version. The version of the interaction is specified in the CapabilityStatement resource. The sequence works this way:

Clients are advised to check the server’s capability statement before first using the server, but how often is at the discretion of the implementer, and this varies wildly. Some implementers only check the statement during the development cycle, while others check on the first connection for each process. Which is appropriate depends on a variety of circumstances, but implementers should note that the CapabilityStatement can change over time - even changing FHIR versions as the system is subject to ongoing development.

Note that there are related places where the FHIR version in use can also be stated, and these may be consulted at different points in the development cycle in place (or as well as) CapabilityStatement.fhirVersion:

Mime Type Parameter

The most common strategy for handling change between versions of FHIR is to use different end-points for different versions. e.g. http://acme.com/fhir/r2 and http://acme.com/fhir/r3. However, this can be problematic because it means that the same record has a different identity depending on the version of FHIR in use - though this can also be useful; it depends on the context.

A server can support multiple versions on the same end-point, if the client specifies which version to support using the fhirVersion mime type parameter:

GET [base]/metadata
Accept: application/fhir+json; fhirVersion=3.0

This is a request to return the CapabilityStatement for the server’s support of FHIR Release 3. The client will know that the server doesn’t support R3 if it gets an error in return, or if the capability statement that comes back has a different fhirVersion (which would mean that the server does not support the fhirVersion parameter).

Notes:

Clients can determine what versions a server supports by using the $versions operation.

Storage

The same technique can be used in a database, or any other kind of storage – just store the mime type (or just the version) alongside the resource. This means that when reading resources, the application knows what version the resource has, and therefore what parser to use, before reading the resource.

Version Specific Profile

There are some circumstances where applications handle ‘naked’ resources – that is, resources where there is no wrapping envelope to carry a mimetype version parameter, nor any suitable parallel location to store the version. The most obvious circumstance is when resources are stored in files, though this may arise in other circumstances due to (legacy) application or protocol design.

When there’s no other alternative, the version has to be in the resources itself, and applications reading the resource have to scan the resource to determine the version and then read the resource as the correct version.

In these cases where the version must be placed in the resource itself, this is done by indicating that the resource conforms to specific version in meta.profile:

{
  "resourceType" : "Patient",
  "meta" : {
    "profile" : ["http://hl7.org/fhir/3.0/StructureDefinition/Patient"]
  }
}

This technique can be used with all versions of FHIR, including R2 and R3:

FHIR R1 (DSTU 1) 0.0
FHIR R2 (DSTU 2) 1.0
FHIR R3 (STU3, or just R3) 3.0
FHIR R4 (this version) 4.0 (once published)

Managing Version Identification

This means that there are 3 different methods for determining version, all of which may be applicable when exchanging data. Implementers are advised to adopt their use in the order documented:

  1. All exchange of FHIR resources will have a known version from the metadata – this always applies, and implementers are encouraged to prefer this method whenever possible.
  2. When this is not enough, or when resources are not exchanged under the rules of a CapabilityStatement, a version parameter should be stored alongside the resource, preferably using the mime type parameter documented above
  3. When there’s no other choice, use the meta.profile to indicate which version(s) a resource conforms to

When determining the version, there’s no order of preference between these methods: if the version of a resource or interaction is specified more than one way, the version statements must all agree with each other, or it is an error, and applications can process a request/resource how they wish – usually, with some kind of error.

Strategies for handling Changes Between Versions

All parts of the FHIR specification are subject to ongoing change. The types of changes allowed, and the change control process vary, as detailed in the Version Management Policy. Implementers need to be aware of what kind of changes are made and have a strategy for dealing with them. Where possible, implementers should design their solutions to be able to manage changes to the specification and, where necessary, to manage interoperability with systems that may be using different versions of the specification.

A key aspect of the FHIR specification development process is gaining feedback from implementers making use of the specification. As well, the process is conditional on real world implementation in order to move through the maturity cycle. For this reason, all FHIR implementers are encouraged to register their usage here, which captures contact and other information that will allow HL7 to perform appropriate monitoring of FHIR usage. Survey information is confidential and reported in aggregate only. (Note that implementers can advertise their use of FHIR here.


versions.html

Maturity Level: NormativeStandards Status:Normative

Version Management Policy

This page documents the way version change is handled in FHIR. FHIR is a standard, so the way version change is handled is a bit different from an application API. This page describes:

See also Managing FHIR Versions for additional implementer advice about dealing with versions.

The Standards Development Process

FHIR is a standard. In order to be useful, standards need to evolve. At the same time, the evolution of standards needs to be predictable and manageable for the implementation community. This section describes how HL7 develops a standard so that implementers know what to expect as the standard evolves.

HL7 has four descriptive terms that describe the level of stability and implementation readiness associated with different aspects of the specification. They are as follows:

Standard Level Description
Draft This portion of the specification is not considered to be complete enough or sufficiently reviewed to be safe for implementation. It may have known issues or still be in the "in development" stage. It is included in the publication as a place-holder, to solicit feedback from the implementation community and/or to give implementers some insight as to functionality likely to be included in future versions of the specification. Content at this level should only be implemented by the brave or desperate and is very much "use at your own risk". The content that is Draft that will usually be elevated to Trial Use once review and correction is complete after it has been subjected to ballot
Trial Use

This content has been well reviewed and is considered by the authors to be ready for use in production systems. It has been subjected to ballot and approved as an official standard. However, it has not yet seen widespread use in production across the full spectrum of environments it is intended to be used in. In some cases, there may be documented known issues that require implementation experience to determine appropriate resolutions for.

Future versions of FHIR may make significant changes to Trial Use content that are not compatible with previously published content.

Normative This content has been subject to review and production implementation in a wide variety of environments. The content is considered to be stable and has been 'locked', subjecting it to FHIR Inter-version Compatibility Rules. While changes are possible, they are expected to be infrequent and are tightly constrained.
Informative This portion of the specification is provided for implementer assistance, and does not make rules that implementers are required to follow. Typical examples of this content in the FHIR specification are tables of contents, registries, examples, and implementer advice
Deprecated This portion of the specification is outdated and may be withdrawn in a future version. Implementers who already support it should continue to do so for backward compatibility. Implementers should avoid adding new uses of this portion of the specification. The specification should include guidance on what implementers should use instead of the deprecated portion

Mixed Normative content

Some Normative artefacts contain a few parts labeled as 'Trial Use' even though the artifact itself is labeled 'Normative':

While HL7 prefers to avoid this outcome, there are a number of resources where the overall functionality of the artefact is clearly ready to be labeled as 'normative' while some very specific parts are known not to have the requisite level of implementation experience as the rest of the resource. E.g. Bundle.signature.

Where a Normative resource contains elements marked as trial-use, these elements are clearly marked in the resource definitions. Implementers should be aware that future versions of the FHIR specification may change these parts of the resources (in addition to the other changes allowed under the inter-version compatibility rules. While HL7 will carefully consider the consequences of breaking change to these elements, implementers should be aware that reading/using these elements has the potential to cause breaking change to their applications later.

Note that this same status will arise as a matter of process when new elements are introduced into normative resources in future versions - they will undergo a period of trial use as appropriate.

Note: it is also possible that some resources in the future will be labeled as 'trial use', but contain some elements labeled as 'normative'. There is no resource like this in this specification, though all Trial Use resources contain normative content from Resource and DomainResource, and the Data types.

This release (Release 3) is a Trial Use Specification, though a little of the content (where marked specifically at the top of the page) is Draft. For Release 4, some content is planned to be Normative.

Notes:

Maturity Levels

The content of this release has been subject to significant review through ballot and other HL7 processes and many aspects of it have been implemented and subjected to interoperability testing through Connectathons and early adoption. However, the degree of testing has varied. Some resources have been well tested in a variety of environments. Others have received relatively little real-world exercise. In general, the infrastructure should be considered to be more stable than the resources themselves. In some cases, there are issues on which input is specifically requested during the Trial Use period (see the Outstanding Issue List, and known issues will arise after publication (refer to the FHIR Change Request tracker for details.) Guidance from early implementation will help address these areas.

All artifacts in this specification are assigned a "Maturity Level", known as FMM (after the well known CMM grades). The FMM level can be used by implementers to judge how advanced - and therefore stable - an artifact is. The following FMM levels are defined:

Draft (0)the resource or profile (artifact) has been published on the current build. This level is synonymous with Draft
FMM 1PLUS the artifact produces no warnings during the build process and the responsible WG has indicated that they consider the artifact substantially complete and ready for implementation. For resources, profiles and implementation guides, the FHIR Management Group has approved the underlying resource/profile/IG proposal
FMM 2PLUS the artifact has been tested and successfully supports interoperability among at least three independently developed systems leveraging most of the scope (e.g. at least 80% of the core data elements) using semi-realistic data and scenarios based on at least one of the declared scopes of the artifact (e.g. at a connectathon). These interoperability results must have been reported to and accepted by the FMG
FMM 3PLUS + the artifact has been verified by the work group as meeting the Conformance Resource Quality Guidelines; has been subject to a round of formal balloting; has at least 10 distinct implementer comments recorded in the tracker drawn from at least 3 organizations resulting in at least one substantive change
FMM 4PLUS the artifact has been tested across its scope (see below), published in a formal publication (e.g. Trial-Use), and implemented in multiple prototype projects. As well, the responsible work group agrees the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes
FMM 5 the artifact has been published in two formal publication release cycles at FMM1+ (i.e. Trial-Use level) and has been implemented in at least 5 independent production systems in more than one country
Normativethe artifact is now considered stable

Tested across scope means:

The Maturity level is strongly related to stability; the higher the maturity level, the more controls are enforced to restrict breaking changes to the resource. For further information, and discussion, see the FHIR Confluence page.

The maturity model is significantly influenced by the degree and type of implementation activity using an artifact. For this reason, we encourage implementers to register their implementations. A detailed analysis of the basis for the maturity metrics for FHIR artifacts can be found here.

FHIR Releases and Versioning

New versions of FHIR will be published on a release cycle of approximately 18-24 months. This frequency is based on the timelines necessary to consult with implementers, to develop and review new content, as well as to undertake the formal balloting and reconciliation processes required for ANSI-approved standards. This release cycle also ensures an opportunity to incorporate implementer feedback from earlier versions of the specification into subsequent versions. Limited-scope releases on a shorter timeline may occur occasionally where necessary to meet implementer needs.

Each new release is assigned a unique version number. The FHIR version policy is based on Semantic versioning, but with some differences due to the fact that FHIR is a specification, not a software API.

There is a single development version of FHIR. This undergoes cycles of development as managed by HL7. Each major cycle of development is concluded by a formal ballot (or more than one), and then a new specification is published. In version control terms, each published specification is a branch off the development trunk, which may then itself undergo further change as HL7 maintains the published specification (though such changes are usually minimal, limited to necessary technical corrections or security alerts).

Each FHIR version is identified by a string composed from 4 parts: publication.major.minor.revision.

publication
  • Incremented when HL7 publishes FHIR as an updated specification, e.g. a Trial Use or Normative version of FHIR
  • The first Trial Use was version 0
  • FHIR Release 2 (DSTU) was version 1
  • FHIR Release 3 (STU) is version 3 (skipped '2' to align the major numbers at implementer request)
major
  • Increments every time a breaking change is made (see below)
  • When a new publication is made, this is reset to 0 in the publication, and 1 in the development branch
  • Since HL7 does not make breaking changes as technical corrections to a published specification, these versions of FHIR always have a version number X.0.n.r
  • Because the development version is the subject of ongoing analysis, debate, ballot and repeated alterations, breaking changes are to be expected in STU content
minor
  • Increments every time an official snapshot release is generated that contains one or more substantive changes
  • Resets to 0 any time the major version changes
  • Snapshot releases are produced approximately 6 weeks in advance of the 3 annual HL7 working group meetings (and their associated connectathons), though they can also be produced for other major connectathons or to meet implementer requirements.
revision
  • Incremented any time a change is made to the specification
  • At present, this is the SVN version number (this allows anyone to reconstruct the source from which the version was built)
  • Changes are made numerous times a day, generally driven by change requests submitted by the implementation community

Additional notes:

Version identification

The FHIR version is usually known implicitly, but can be specified/determined by one of three methods:

For further information, see Managing Multiple FHIR Versions.

Rules for Inter-version change

The intent of these rules is to ensure that applications that are conformant to an existing specification are also conformant to subsequent versions. In practice, there are many subtle issues around inter-version change, and the exact rules are subject to further clarification based on feedback from implementers.

The following kinds of changes may be made to the specification:

NOTE: The examples provided as part of this specification are never substantive. While every effort is made to ensure that FHIR examples are correct, changes to the examples in the specification are not considered substantive.

Content with a status of Draft or Trial Use can change - including Breaking Changes - from version to version, subject to the rules described by the Maturity Process. There are no rules for maintaining any sort of compatibility between versions for content with these statuses, though of we will only make breaking changes based on feedback from the community.

Once an artifact achieves Normative status, specific rules come into play around inter-version compatibility. These rules have implication for both forward and backward compatibility and are intended to allow implementations to exercise FHIR interfaces and process the content of FHIR resources safely while exchanging data between systems using different versions of FHIR.

Forward compatibility means that content that is conformant in an old release will remain conformant with future versions. Once normative, FHIR's rules try to enforce forward compatibility. However, that doesn't guarantee that all old systems will interoperate with future systems.

Backward compatibility means that instances created against future versions of the specification will interoperate with older versions of the specification. This is not guaranteed by FHIR, though there are strategies systems can adhere to that will increase their chances of such interoperability. Specifically, when dealing with content from a system supporting an unknown normative version and wishing to maximize backwards compatibility, applications SHOULD:

However, in a healthcare context, many implementers are unwilling to consider some of these steps because of concerns about clinical risk or technical limitations in their software (e.g. schema based processing).

Forward and backward compatible rules

The following rules apply once an artifact in the FHIR core specification or in an HL7-international published implementation guide has become normative
CategoryAllowed changes
Resources New artifacts resources may be introduced. Existing resources will not have their names changed
Artifacts (resources, profiles, code systems, etc.) New artifacts including new resources and data types may be introduced. Existing artifacts will not have any computable identifiers (e.g. resource names) changed. Artifacts may be deprecated
Elements New optional elements and/or content (e.g. XML attributes, etc.) may be introduced at any location in resource and data type structures provided they do not constitute "isModifier" elements. However, the names, path and meaning of previously existing data elements will not be changed. This means there will be no change to resource names and no changes to names assigned to slices and other elements within profiles.
Cardinality Minimum element cardinalities will not be changed. Upper cardinality may change from 1 to * only in circumstances where all elements except for the first repetition can be safely ignored. Note that this may change the path to the element in some syntaxes (e.g. JSON). This may mean that an order is assigned to the repeating items or that there is no preference as to which element is retained. Systems should follow the rules above for unexpected elements.
Descriptions Descriptive information about a resource - short labels, definitions, usage notes, aliases, examples, rationale, mappings, etc. may be updated or revised to provide additional clarity or guidance, but not in such a manner as to invalidate a reasonable interpretation of the previously documented use of an element. (This does not preclude fixing obvious errors.)
Value Sets and Code Systems

The definition of any value set that is marked as immutable will never change. The expansions for immutable value sets may still change if no "stable date" is declared and the value set does not restrict code system and/or value set references to specific versions and the codes in the referenced code system(s) or value set(s) change.

For non-immutable value sets:

  • Value sets with an enumerated list of codes and having a 'fixed' binding may have additional codes introduced but will never have codes removed, though they may be deprecated.
  • Value sets making use of filters may have filters loosened or tightened to accommodate changes to underlying code systems. StableDates and referenced code system and value set versions may be adjusted to point to newer versions.
  • Definitions and display values for codes may change, but only in a manner that would not change the reasonable interpretation of data captured using the previous definitions or names.
  • Abstract codes may be made concrete. Concrete codes will not be made abstract.

For both immutable and non-immutable value sets, additional designations may be declared.

Normative CodeSystems whose content is generated from a mix of normative and non-normative contents may break these rules. For example, the code system containing the list of all resources may have codes removed or renamed as non-normative resources are removed or renamed.

These expectations only apply to Value Sets and Code Systems maintained as part of the FHIR specification. HL7 cannot enforce these rules on terminology artifacts maintained by other authorities - e.g. UCUM unit codes, ISO language codes, etc

Terminology Bindings
  • Required bindings will remain required and will continue to point to the same value set. If the reference is version-specific, it will not change
  • Extensible bindings will remain extensible and will continue to point to the same value set. If the reference is version-specific, it will not change.
  • Example bindings and preferred bindings may change to point to different value sets. Example bindings may be replaced with preferred bindings.
Data Types Except as described in the preceding paragraph, Data types will not be removed or changed except as allowed above for elements. New data types may be introduced. Types declared on existing elements will not be removed or changed, except for the special case that string may be changed to markdown. Additional data types may be added to elements which are already expressed as a choice of data types only if those elements are optional (minimum cardinality = 0).
Value Constraints The allowed list of Data types will not be added, removed or changed. Invariants, regular expressions, fixed values and patterns will not be added, removed or changed.
Flags The Is Modifier and Is Summary flags will not be changed.
Slicing Slicing rules and aggregation characteristics will not be changed.
Search Criteria Search criteria may be added but not removed or renamed. Existing criteria will not have their type or path changed or have their description altered in any way that would invalidate the reasonable behavior of existing systems (with the exception of correcting obvious errors).
Operations New operations may be defined but operations will not be removed or renamed. Existing parameters will not be removed or renamed, nor may their type or lower cardinality be changed. Upper cardinality may be changed from 1 to *. (Systems should ignore unexpected repetitions.) Additional optional parameters may be introduced. Changes to operations that would violate the preceding constraints will be handled by defining new operations and, potentially, deprecating the old operations.
Restful interface Existing endpoints will not be renamed or removed, nor have their expected behavior changed in a manner that would cause reasonable systems designed against prior versions to be non-interoperable. Additional endpoints and interactions may be introduced.
Profiles and extension definitions Profile structure, extension definitions and search criteria definitions will not be removed or have their URIs changed. New profile structures, extension definitions and search criteria definitions may be introduced. Profiles may have their statuses changed to "retired". Profiles referenced by data elements for structures or data types may be replaced with a reference to a distinct profile that is "compatible" with the previously referenced profile according to these forward and backward compatibility rules.
Capability Statements Within the CapabilityStatements for defined FHIR Services or 'core' implementation guides, additional operations may be added. These additions might be optional (MAY/SHOULD) or mandatory (SHALL). Note that the introduction of mandatory operations would break forwards compatibility and will only occur with community consultation.
Implementation Guides Additional artifacts can be added and artifacts can be changed. The list of global profiles will not change
References Where one conformance resource points to another (e.g. CapabilityStatement to profile, profile to profiles, profile to value set, etc.), the reference may change to point to a newer version of the conformance resource or to a distinct conformance resource so long as the content of the newly referenced resource adheres to the compatibility rules with respect to the previously referenced version.

NOTE: In rare circumstances, HL7 may approve changes that technically break one of the above rules in situations where there is a high level of confidence that the change will not impact existing implementers. Such deviations from these declared rules will involve broad notification, extensive community consultation and reviews by multiple levels of HL7 governance processes.

 

Deprecation / Withdrawal of Normative Content

Once content is normative, there is a process for removing it from the standard by marking it as deprecated or withdrawn (from the HTML 4.0 Standard):

DeprecatedSystems should continue to support the artefact/feature/concept, but are discouraged from making use of it
WithdrawnDocumented for historical purposes, no longer supported

The specification will provide guidance with deprecated materials showing how to avoid using them. Deprecated materials are eligible to be balloted to be withdrawn two years after their deprecated status is published.

The computable artifact labels (e.g. codes, element names, urls, etc) associated with withdrawn materials SHALL not be used in future versions of HL7 specifications. Materials marked "deprecated" may have that marking removed as part of a subsequent ballot at a later moment, while withdrawn materials SHALL NOT.

The following artefacts are deprecated in this version of FHIR:


Additional discussion on inter-versioning issues can be found here: https://confluence.hl7.org/display/FHIR/Interversion+Compatibility.

Managing Change during the development process

Regardless of the degree of prior implementation, all aspects of the FHIR specification are potentially subject to change while an artifact has a status of Draft or Trial Use. These changes may be minor (clarifications of definitions, etc.) or major (refactoring of resources, changes to serialization rules, eliminating or adding data types, etc.) There is no commitment to backward or forward compatibility during the trial use process until content is normative. Changes will not be made without cause, however the interests of long-term implementability will generally trump the impact on early adopters when determining what changes should be made. This balance will shift more towards early adopters as maturity levels increase. I.e. Impact on existing implementations will be weighted more highly for an FMM-level 5 artifact than they would for an FMM-level 1 artifact.

Implementers who are willing to accept the risk of change (perhaps for the benefit of early implementation experience, first mover advantage and the ability to leverage FHIR's intrinsic benefits) are encouraged to implement those parts of FHIR that are early in the maturity cycle in real-world systems. However, those implementers should be aware that local adaptations may be necessary to meet real-world requirements. Furthermore, such implementers should architect their solutions to be tolerant of changes to the specification and, where necessary, to manage interoperability with systems that may be using different versions of the specification or different local adaptations.

During the Trial Use period, requests for change may be submitted using the HL7 issue tracker which can be found here. Where possible, updates to the "development" version of the specification will be made in a timely fashion. Implementers should be aware that the changes are not considered "official" until such time as they are balloted and approved as part of a subsequent Trial Use or Normative publication. Change requests might be fixes to allow implementation, clarifications or enhancements. In addition, HL7 will be developing and introducing additional resources and profiles as part of the FHIR specification.

SDOs and regulatory bodies that are interested in making use of the FHIR specification should feel free to do so, but should consider and plan for the possibility that the specification will evolve and change prior to becoming Normative.

A key aspect of the FHIR specification development process is gaining feedback from implementers making use of the specification. As well, the process is conditional on real world implementation in order to move through the maturity cycle. For this reason, all FHIR implementers are encouraged to register their usage here, which captures contact and other information that will allow HL7 to perform appropriate monitoring of FHIR usage. Survey information is confidential and reported in aggregate only.

Extensions for converting between versions

Many implementations need to convert resources from one FHIR version to another. Once resources become normative (once sufficiently mature and stable), converting resources forwards from past versions is not needed. Converting back to older versions presents a challenge, however, in that the newer version may add additional elements that are not present in the older version. In some cases, the elements are simply irrelevant since the requirements they represent are not in scope for older applications, but in other cases, it is necessary to represent the data in order to cater for round-tripping.

A more complex problem arises with resources that are not yet stable (early in the maturity process). If applications have implemented less stable resources, not only do they have the problem of new elements for new requirements, the specification may change in either compatible or incompatible ways, and it may be necessary to carry data elements from past versions forward in order to allow seamless round-tripping.

In order to help implementers with this problem, any element defined in any version of FHIR is automatically assigned an extension URL that uniquely identifies the element and can be used in the relevant FHIR version. The extension URL for an element can automatically be derived:

http://hl7.org/fhir/[version]/StructureDefinition/extension-[Path]

where [version] is taken from this list:

This technique can be used with all versions of FHIR, including R2 and R3:

FHIR DSTU2 1.0
FHIR R3 (STU3, or just R3) 3.0
FHIR R4 (this version) 4.0 (once published)

Note that this extension framework only applies back to DSTU2. The [Path] is actually the ElementDefinition.id from the relevant StructureDefinition for the element. This leads to URLS like the following:

http://hl7.org/fhir/4.0/StructureDefinition/extension-Bundle.signatureR4 Signature Element on Bundle
http://hl7.org/fhir/3.0/StructureDefinition/extension-Patient.animal.speciesSTU3 Species Element on Patient
http://hl7.org/fhir/1.0/StructureDefinition/extension-ValueSet.extensibleDSTU2 ValueSet.extensible

Implementers should be aware of the following issues when using these extensions:

This table shows the mapping between primitive data types across versions:

R4 R3 DSTU2
base64Binary base64Binary base64Binary
boolean boolean boolean
canonical (uri) (uri)
code code code
date date date
dateTime dateTime dateTime
decimal decimal decimal
id id id
instant instant instant
integer integer integer
markdown markdown markdown
oid oid oid
positiveInt positiveInt positiveInt
string string string
time time time
unsignedInt unsignedInt unsignedInt
uri uri uri
url (uri) (uri)
uuid uuid (id)

Formal Definitions for extensions:

Format: R2 Package R3 Package R4 Package
R2 Extensions: n/a hl7.fhir.extensions.r2:3.0.1 hl7.fhir.extensions.r2:4.0.0
R3 Extensions: hl7.fhir.extensions.r3:1.0.2 n/a` hl7.fhir.extensions.r3:4.0.0
R4 Extensions: hl7.fhir.extensions.r4:1.0.2 hl7.fhir.extensions.r4:3.0.1 n/a

Note for balloters: these packages will be created when R4 is finalized. Until then, these are broken links.

Plans for future releases

While implementation of this Trial Use release is occurring, development will be progressing on the next release. This next release will include additional resources, profiles and quality enhancements over the current release. It will also incorporate fixes for issues raised with the FHIR issue tracker. It may be useful for implementers of the STU to review the development release to get a sense of what changes are likely coming and perhaps to find more robust definitions and guidance than are available in the first release. The FHIR development release can be found at build.fhir.org. Some implementers who are dependent on content that exists in a draft release may choose to implement based on a particular snapshot of the development release, though in doing so, they will limit their potential communication partners and would not be considered to be completely FHIR conformant.

The next major publication of FHIR will be Release 4. It is our hope that this release will include the transition of some of the content of the specification to Normative. This should include many of the core infrastructure resources (e.g. StructureDefinition, ValueSet as well key pages such as the XML and JSON syntaxes, RESTful protocol, etc. It should also include at least a few of the administrative resources such as Patient. Much content, including most if not all clinical and business resources, will remain at the Trial Use level as they are not expected to meet the criteria for Normative.

The anticipated timeline for Release 4 involves a finalization of scope by the end of 2017, balloting in April of 2018 and publication around October 2018. The specific timing may vary based on implementer feedback and the volume of contents received during the ballot process. More information on plans for Release 4 can be found on the HL7 product director's blog. (Subscribing to this blog is a good way to keep current on significant events in FHIR development, including ballot and publication timelines.)

There will be additional releases of FHIR with a frequency of between 18 and 24 months for the foreseeable future. These releases will include new content (e.g. in the public health, financial or clinical research spaces), revisions reflecting implementer feedback and increasing maturity on Trial Use artifacts and the migration of additional content to normative status. As well, HL7 will gradually shift focus to providing additional guidance through the publication of implementation guides and profiles where consensus can be found at the international level.


w5.html

FHIR W5 Report

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

This page is deprecated and will be a removed in a future version of this publication. Instead, see the FiveWs pattern.

Concise

Full


wglist.html

FHIR Workgroup List Report

Maturity Level: N/AStandards Status:Informative

See also the QA Page


workflow-ad-hoc.html

Maturity Level: 2Standards Status:Trial Use

Ad-Hoc Workflow Communication Patterns

TODO: Discussion (or reference to one) on Polling and Subscription

Option A: Simple RESTful POST or PUT

Steps

  1. The placer makes a RESTful call to create or update a record or a POST to invoke an operation over HTTP
  2. The receiver responds with a 2xx HTTP response indicating whether the request was successfully processed or not and, if appropriate, provides the response to the request in the payload of the HTTP response

Benefits

Limitations

Usage Recommendations

This is by far the most common pattern in FHIR for simple changes as it requires the least overhead. However, it covers only automated responses, and does not support any actual workflows of more than one step. If human processing is involved in the request execution, then this approach won't suffice. This approach is listed here to make sure that implementers consider whether they can make this one work first before falling back to one of the more sophisticated patterns.

Usage Examples

???

Option B: Direct POST of request to fulfiller's system

Diagram showing direct POST of request to fulfiller's system workflow

Steps

  1. Placer system invokes a create by POSTing a 'request' resource (e.g. MedicationRequest, ServiceRequest, etc.) to the appropriate RESTful resource endpoint (e.g. [base]/MedicationRequest) on the filler system and places an actionable tag on the resource that indicates the request is intended to be acted upon, not merely stored.
  2. The filler synchronously responds with a "201" indicating that they have received and stored (created) the resource on their system
  3. At some later point, the filler POSTs an 'event' resource (e.g. MedicationDispense, DiagosticReport, Encounter, etc.) to the appropriate resource endpoint on the placer system, including a basedOn link to the 'request' resource that the action was performed in fulfillment of.
  4. The placer system synchronously responds with a "201" indicating they've received and store (created) the resource on their system

Benefits

Limitations

Usage Recommendations

Use this approach when there's no ability to have queue servers and no support/need for complexity of Task, polling or pub/sub (and no need for negotiation or the ability for the filler to say "no"). This is a pseudo-messaging architecture that doesn't actually use messaging architecture.

Usage Examples

Option C: POST of request to placer/queue server system, receiver uses polling or subscription

Diagram showing POST of request to placer/queue server system, receiver uses polling workflow

Steps

  1. Placer system creates a 'request' resource (e.g. ServiceRequest etc.) by a system action or a POST on either its own system or a third party queue server system and places an "actionable" tag on the resource that indicates the request is intended to be acted upon. The request explicitly identifies the intended fullfiller
  2. The filler system uses polling (or a subscription) at the placer or queue server system to see if there are any "new" requests that: are tagged as "actionable", have the filler identified as the intended performer, and are a type of request "of interest" to the filler.
  3. At some later point, the filler creates an 'event' resource (e.g. MedicationDispense, DiagosticReport, Encounter, etc.) via a system action, or a POST on either its own system, the same queue server as the request was placed on, or some alternate queue server, including a link to the 'request' resource that the action was performed in fulfillment of
  4. The placer system uses polling (or a subscription) to the filler or queue server system to see if there are any "new" events that are tied to any outstanding requests the placer has initiated

Benefits

Limitations

Usage Recommendations

This pattern could be used when there's no support/need for complexity of Task, usually for simple two step workflows. This is a more typically RESTful approach where data resides on the server "owned" by the data creator and is accessed by other systems.

Usage Examples

Option D: Messaging request from placer to filler & acknowledgment

TODO: needs review and update

Steps

  1. Placer sends message to filler system including Request resource (and other relevant resources) along with a MessageHeader with an "event" code saying "please fulfill" and "data" element pointing to the Request resource as the item to fulfill. Message could potentially use Task instead of MessageHeader.event to convey desired action (ongoing discussion)
  2. Filler system sends a response indicating receipt of the message and, optionally an indication of their intention to fulfill the request
  3. Filler system may send incremental messages to the placer showing progress (e.g. specimen collected, preliminary results, final results)

Benefits

Limitations

Usage Recommendations

Existing messaging infrastructure (e.g. v2 LTP, MLTP, WSI Web Services, Direct, VISA, REST, etc.) and a need to stay consistent with that architecture

Option E: Services request from placer to filler & acknowledgment

TODO: Needs review, update and more work - there's not a lot of experience using FHIR services to manage the fulfillment process

Steps

  1. Placer may create and store a Request resource on their own system or a queue server.
  2. Placer invokes a service on the filler system saying "please fulfill this order", including the content or a reference to the request resource and any other relevant data
  3. Filler system responds (synchronously if using HTTP, but may be asynchronous if using SOAP or other transport mechanisms) with conformation of receipt and, optionally indication of intention to fulfill and/or results

Benefits

Limitations

Usage Recommendations

TBD

Additional Scenarios

TODO: needs review and update. Possibly add options about using messaging and/or services instead of polling/subscription in above scenarios

Querying the status of a workflow using REST

  1. Placer sends query for Task(s) that have a focus of the request of interest to a system (placer system, queue server or filler) that holds tasks related to their request.
  2. System returns a query response showing all related tasks (typically just one). Task shows current status.

Querying the status of a workflow using services

  1. Placer invokes a "what's the status of this order" service, passing the request business identifier or URL of the request
  2. Services responds with a Task showing the current state of the fulfillment of the request

Cancellation of a Task using REST - placer owns

  1. Placer sends an update to the Task setting the status to "cancelled" signalling they are no longer concerned about the outcome of the task
  2. Filler receives notification of the update (because the task is on their system, or because they poll it, or are subscribed to it) and ceases work if they are able

Cancellation of a Task using REST - filler owns

  1. Placer creates a new task requesting cancellation of the original fulfillment task
    Fulfillment of the "cancellation task" can be requested using any of the mechanisms above
  2. Filler decides whether they are able to cancel the task and update the "cancellation" task to indicate either cancellation is complete or has been refused

workflow-communications.html

Maturity Level: 2 Standards Status: Trial Use

Workflow Execution and Communication Patterns

As described in previous sections, many FHIR resources can be used within workflows without using FHIR to manage the execution of the workflows. When we want to manage workflow execution with FHIR, there are several mechanisms available. In addition to managing workflow with FHIR, there are also cases where management of workflow execution is not necessary, and supporting workflow becomes simply the use of the resource patterns in an ad-hoc fashion. In deciding how best to interoperate around workflow with FHIR, there are several considerations:

The answers to these (and other) questions will guide the selection of communication patterns to be used for a specific interoperability use case. It is recommended that domain workgroups analyze the support for workflow execution within their domains and provide recommendations for an appropriate subset of patterns, with a discussion on where and how to use them. Implementation guides, by their nature, should prescribe which patterns to use for workflow execution management.

Communication Patterns Conventions

This section highlights some of the more common patterns and identifies their characteristics and limitations and provides recommendations on when each approach may be most useful or relevant. Please note that this list of patterns is not exhaustive. Patterns can be combined in various ways and there are likely some possibilities we haven't thought about yet (feel free to submit additional patterns using the 'submit a change' link at the bottom of the page). As well, the recommendations given here are just that - recommendations. Implementers are free to choose which patterns they wish to support. Because of this, tight interoperability around workflow execution (as with any other tight interoperability using FHIR) will depend on communicating participants doing some up-front negotiation around how they plan to support workflow execution or all communicating partners will need to adhere to an implementation guide that sets out clear interoperability expectations.

Prior to reviewing this list of options, readers are encouraged to be familiar with the following pages and resources: REST, messaging, operations, services and the Subscription resource.

The scenarios used to illustrate the patterns below make use of a few conventions:

Workflow State

One of the key distinguishing characteristics in the patterns below is whether the pattern supports the tracking of the workflow's state by both the placer and the filler. The workflow state is represented by the Task resource. The Task state machine, which is also presented here, shows the use of Task.status to represent the general infrastructure state of the Task resource.

Diagram showing typical state machine for the Task resource

The combination of Task.status, Task.statusReason and Task.businessStatus provide the mechanism for tracking the workflow state. The following two examples illustrate how that could be accomplished with regards of specific workflows. Note that these examples avoid any specificity on where the described resources exist, or any reference to a specific communication pattern. The goal of the examples is to demonstrate the use of the Task attributes to represent the workflow state.

Example: Workflow states for a lab order for a blood test

The following table shows the steps for a simple blood test order, and the corresponding values of the Task attributes. A lot of details on other attributes have been omitted in order to focus on the state changes.

Workflow step Task.status Task.statusReason Task.businessStatus
Provider orders a blood test for a patient. A ServiceRequest resource is created to represent the order, and a Task resource is created to represent the request to the lab. Task.basedOn points to the ServiceRequest instance. Requested New order Ordered
The lab accepts the order. Accepted Able to perform the test. Accepted
The patient is at the lab, and blood is drawn. In progress Obtained the specimen Specimen available
Work on the blood sample is in progress, preliminary results are available, a DiagnosticReport resource is created, and Task.output.value[1] references the DiagnosticReport resource. In progress Preliminary results available Preliminary results
Final results are available Complete Final results are available Final results

Example: Workflow states for a referral from a PCP to a specialist

The following table shows the steps for a referral workflow, and the corresponding values of the Task attributes. A lot of details on other attributes have been omitted in order to focus on the state changes.

Workflow step Task.status Task.statusReason Task.businessStatus
Provider A is seeing a patient with a specific complaint. Based on the exam, Provider A refers the patient to a specialist at clinic B. It is an urgent referral, requesting to see the specialist within 4 days. A ServiceRequest resource is created to represent the referral order, and a Task resource is created with Task.priority set to Urgent, and Task.restriction.period.end set to 4 days in the future. Requested New referral Referred
Clinic B receives the referral and puts it on the urgent queue to be reviewed. Received Received by organization Pending
Upon reviewing the referral, the clinic determines they have no capacity to see the patient within the specified time period, and they decline the referral. Rejected Provider unavailable Declined
Provider A changes the referral request to clinic C. This creates a new Task resource, with the appropriate information Requested Changed the referred to provider Referred
Clinic C accepts the referral and it is placed on a scheduler's queue. Accepted Able to provide the service. Accepted
An appointment is scheduled for the patient at Clinic C. In progress Appointment scheduled Scheduled
Soon after the appointment is scheduled, the patient calls provider A to ask for a different location for the referral appointment, as he lost his transportation, and he cannot reach Clinic C. The provider requests a cancel for the referral. Suspended Patient unable to make appointment. Cancel requested
Clinic C confirms the cancellation of the existing task. In progress
Failed
Referral cancelled Cancelled as requested
Provider A changes the referral to Clinic D, which is located close to where the patient lives, and can be conveniently reached using public transportation. This creates a new Task resource, with the appropriate information. Requested Changed the referred to provider Referred
Clinic D accepts the referral and it is placed on a scheduler's queue. Accepted Able to provide the service. Accepted
An appointment is scheduled for the patient at Clinic D. In progress Appointment scheduled Scheduled
Patient is seen at Clinic D. A diagnosis is made by the specialist, a prescription is given, and a follow-up appointment is made at clinic D. Task.output.value[1] references a Compositions resource, which contains the encounter summary. In progress Intermediary consultation note available Preliminary notes
Patient comes for follow-up appointment at clinic D. The specialist is satisfied by the progress the patient has made and creates the final consultation note. Task.output.value[2] references a Compositions resource, which contains consultation note. Completed Final consultation note available Final notes

List of patterns

The patterns that facilitate the execution of workflow using the Task resource are grouped in the Workflow Management Patterns section. The patterns where no Task resource is used are grouped in the Ad-hoc Workflow Patterns section. The list of patterns is as follows:

Ad-Hoc Workflow Patterns
Option A: Simple RESTful POST or PUT
Option B: Direct POST of request to fulfiller's system
Option C: POST of request to placer/queue server system, receiver uses polling or subscription
Option D: Messaging request from placer to filler & acknowledgment
Option E: Services request from placer to filler & acknowledgment
Workflow Management Patterns
Option F: Creation of Task on placer's system
Option G: POST of Task to fulfiller's system
Option H: POST of Task to a workflow broker
Option I: POST of Task to fulfiller's system, POST of sub-Task on placer's system
Option J: Messaging Task from placer to fulfiller
Option K: Service request referencing Task from placer to fullfiller
Additional Scenarios and Variations

TODO: Insert Jose's decision tree here?


workflow-examples.html

Maturity Level: 2Standards Status:Trial Use

Usage Examples for Workflow Patterns

Future home for examples


workflow-management.html

Maturity Level: 2Standards Status:Trial Use

Workflow Management Communication Patterns

TODO: Discussion (or reference to one) on Polling and Subscription

Option F: Creation of Task on placer's system

Diagram showing creation of Task on placer system workflow

Steps

  1. Placer creates the request in its own system via POST, an internal action, or POSTs it to a queue server system
  2. Placer creates a Task resource in its own system via POST, an internal action, or POSTs it to a queue server system, pointing to the request resource and seeking fulfillment.
    The Task may have a specified performer, in which case step 3 is expected to be done by that performer.
    If the Task does not have a specified "performer" (although may have performer type), then this is a case of an "open" task, where any number of fulfillers may attempt to "claim" the task. Who succeeds is determined by local policies and procedures.
  3. Fulfiller system uses either polling or pub/sub to become aware of the existence of the task
    1. A common case may be the conveyance of the Task id to a fulfiller by other means. For example, a lab test is ordered, and the patient takes a requisition to the lab of his choice. The requisition contains the Task id (as a bar code, or stored in the patient's healthcare smart card), and the lab system can execute a direct GET for the Task, thus eliminating the need for subscription or polling.
  4. Fulfiller system queries to retrieve the referenced request and updates the Task to indicate "acceptance" and agreement to fulfill
  5. Fulfiller may update the Task to indicate interim progress notes
  6. Placer is made aware of the acceptance of the Task and any changes to the Task either through its ownership of the resource or using polling or a subscription to a queue server system to determine the same
  7. Fulfiller creates an event resource in its own system via POST or internal action, or POSTs it to a queue server system
  8. Fulfiller PUTs an update to the Task resource to change its status to completed and to point to the event resource
  9. Placer is aware of the completion of the Task either through the ownership of the resource, or via polling or subscription to a queue server system, and retrieves the referenced event resource
  10. Placer updates the request resource to indicate completion via PUT or an internal action, or PUTs the update to a queue server system

Benefits

Limitations

Usage Recommendations

Usage examples

Lab order to known performer

A provider orders a bilirubin test for a patient, to be done at the provider's facility lab....

"Open" lab order

A patient is scheduled for their physical, and the provider sends her a secure message to have a fasting blood test performed before the office visit. The message has a link to a requisition, and a list of possible lab locations where the test can be done. The patient chooses a lab location near her place of employment and a test is scheduled. The lab gets the requisition from the patient and, using the information on how to retrieve the Task from the provider's system, claims the test to be performed...

Option G: POST of Task to fulfiller's system

Diagram showing POST of Task to filler system workflow

Steps

  1. Placer creates the request in its own system via POST or an internal action, or POSTs it to a queue server system
  2. Placer POSTs a Task resource to the filler system, pointing to the request resource and seeking fulfillment
  3. Fulfiller system GETs the referenced request
  4. Fulfiller updates the Task to indicate acceptance of the task
  5. Placer either polls the Task to note acceptance or uses a subscription to determine the same
  6. Fulfiller may further update the Task to reflect the progress made. Using the same method as in step 5, the placer becomes aware of these updates
  7. Fulfiller creates an event resource in its own system via POST or an internal action, or POSTs it to a queue server system
  8. Fulfiller Updates the Task resource to change its status to completed and to point to the event resource
  9. Placer either polls the Task to note completion and changes or uses a subscription to determine the same
  10. Placer system queries to retrieve the referenced event resource
  11. Placer updates the request resource to indicate completion via PUT or an internal action, or PUTs the update to a queue server system

Benefits

Limitations

Usage Recommendations

Usage Examples

Outpatient prescription

A patient is suffering from a poison ivy rash and is prescribed a steroid medication to manage the reaction. The provider asks the patient for his preferred pharmacy and creates the Task at the specified pharmacy's system. The patient is running late and by the time he arrives at the pharmacy, it is closed. He calls the clinic where the provider practices and requests that the pharmacy where the order is to be fulfilled is changed to one that is open around the clock. The staff at the clinic cancels the Task at the original pharmacy and creates a new Task at the requested new one. By the time the patient arrives at the new pharmacy, the medication is ready for pickup. Once the request is fulfilled, the clinic receives the notification that the Task is complete and the prescription is also marked as complete.

Option H: POST of Task to a workflow broker

TODO: Still needs review and update

Diagram showing workflow broker workflow

Steps

  1. Placer POSTs the request to its own system or to a queue server system
  2. Broker detects that new un-assigned request (without a Task yet created and falling within the scope of the Broker to ensure fulfillment) via polling or subscription
  3. Broker POSTs a Task resource to its own system or a queue server system, pointing to the request resource and seeking fulfillment from a specific filler
    Task does not have a specified "performer" (but may have performer type)
  4. If the Task is rejected by one potential recipient, the broker may create a new task to seek fulfillment from others
  5. Continue as per Option G

Benefits

Limitations

Usage Recommendations

Appropriate in environments that have a workflow engine that takes on responsibility for ensuring fulfillment

Usage Examples

Option I: POST of Task to fulfiller's system, followed by POST of sub-Task on placer's system

Diagram showing mutual POSTs of a Task to filler system and Task to placer system workflow

Steps

  1. Placer creates the request in its own system via POST or an internal action
  2. Placer POSTs a Task resource to the filler system, pointing to the request resource and seeking fulfillment
  3. Fulfiller system GETs the referenced request
  4. Fulfiller updates the Task to indicate acceptance of the task
  5. Fulfiller POSTs a Task, which also points to the request resource and uses the Task.partOf attribute to point to the Task from step 2 (indicating it is a sub-Task)
  6. Fulfiller may further update both Tasks to reflect the progress made. Since the sub-Task is on the placer's system, the placer is aware of these updates
  7. Fulfiller creates an event resource in its own system via POST or an internal action
  8. Fulfiller Updates the Task resource to change its status to completed and to point to the event resource
  9. Fulfiller updates the sub-Task resource as completed and points to the event resource. Since the sub-Task is on the placer's system, the placer is aware of the completion and changes.
  10. Placer system queries to retrieve the referenced event resource
  11. Placer updates the request resource to indicate completion via PUT or an internal action

Benefits

Limitations

Usage Recommendations

Usage Examples

Outpatient referral

A patient is seen by her Primary Care Provider (PCP) for shortness of breath and the provider decides to refer her to a cardiologist. Because of the referral, the provider's system creates ServiceRequest resource and POSTs a Task resource to a cardiologist's practice system, requesting a referral. This places the referral request on a referral coordinator's work list to review. Upon accepting the referral, the Task is updated as accepted and a new sub-Task, referencing both the ServiceRequest and the Task created by the provider's system, is created on the provider's system. The patient gets an appointment with the cardiologist and the sub-Task is updated with that information, allowing the provider's system to inform the provider of the change.

The patient misplaces the information about the appointment and misses the visit with the cardiologist. The cardiologist's system updates the sub-Task to indicate the no-show and the PCP is alerted of the missed appointment. The provider's staff gets hold of the patient and schedules another appointment for her with the cardiologist. Because of the cardiologist's system scheduling the appointment, the sub-Task is updated with that information. The patient is seen and the sub-Task is updated accordingly. The cardiologist document the findings about the patient and updates the sub-Task as complete, adding references to the resources representing the findings. The PCP is alerted of the updates and marks the referral as complete, which updates the original Task and the ServiceRequest as complete as well.

Option J: Messaging Task from placer to fulfiller

TODO: needs more details

Steps

  1. Placer sends message to filler with a MessageHeader, where the "data" element points to the Task resource, also contained in the message. The message might or might not contain any other relevant resources (e.g. the actual request resource), or an "event" code saying "please fulfill"
  2. Filler system sends a response containing the same Task resource, indicating receipt of the message and, optionally, an indication of their intention to fulfill the request
  3. Filler system may send incremental messages to the placer showing progress (e.g. specimen collected, preliminary results, final results) by including an updated Task resource
  4. Placer system may also send messages to the fulfiller containing the Task resource and updating the state of the workflow, for example cancelling the texk

Benefits

Limitations

Usage Recommendations

Appropriate when existing messaging infrastructure can be used (e.g. HL7 over HTTP, v2 LTP, MLTP, WSI Web Services, Direct, VISA, REST, etc.), and a need to stay consistent with that architecture.

Usage examples

Option K: Service request referencing Task from placer to fulfiller

TODO: This scenario needs work - there's not a lot of experience using FHIR services to manage the fulfillment process

Steps

  1. Placer creates a request resource on their own system or a queue server
  2. Placer may create a Task resource on their own system or a queue server
  3. Placer invokes a service on the filler system saying "please fulfill this request", including the content or a reference to the request resource and any other relevant data
  4. Filler system responds (synchronously if using HTTP, but may be asynchronous if using SOAP or other transport mechanisms) with conformation of receipt and, optionally indication of intention to fulfill and/or results

Benefits

Limitations

Usage Recommendations

TBD

Usage examples

Additional Scenarios

TODO: needs review and update. Possibly add options about using messaging and/or services instead of polling/subscription in above scenarios

POST of "request" resource for filler system, response via Task

This is a variation ofOption H, where the Workflow broker is essentially merged with the fulfiller. It still allows the placer to only use a POST of the request, and be made aware of the changes to the other resources via subscription or polling.

Diagram showing POST of "request" resource for filler system, response via Task workflow
  1. Placer system invokes a "create" action by POSTing a 'request' resource (e.g. ServiceRequest etc.) to the appropriate RESTful resource endpoint (e.g. [base]/MedicationRequest) on the filler, placer or queue server system and sets a "tag" on the resource that indicates the request is "actionable"
  2. Filler POSTs a Task resource to its own system or a queue server system, pointing to the request resource and indicating intent to fulfill or refusal to fulfill
  3. Placer system uses either polling or pub/sub to become aware of the existence of the task and fulfillment intent
  4. Fulfiller may update the Task to indicate interim progress notes
  5. Placer either polls the Task to note acceptance and changes or uses a subscription to determine the same
  6. Fulfiller POSTs an event resource to its own system or to a queue server system
  7. Fulfiller Updates the Task resource to change its status to completed and to point to the event resource
  8. Placer system becomes aware of the update via polling or subscription
  9. Placer system retrieves the event
  10. Placer system marks the request as "complete"

workflow-module.html

Work Group Standards Status: Informative

Workflow Module

The workflow module focuses on the coordination of activities within and across systems. This includes three primary aspects:

Index

Infrastructure
Scheduling
Clinical Process

Introduction

Workflows can be performed through direct posting of resources to a target server (combined with a specific tag), by using the Task resource, through the use of messaging or via FHIR services. This specification includes a workflow page that describes the concepts underlying the discussion of workflows, and points to a number of different communication and architectural workflow patterns.

In addition to the Task resource, this specification defines three logical models - Definition, Request and Event that define the patterns for resources that are typically involved in workflow. These patterns include elements defining common attributes of each type of resource as well as relationships between them. These relationships are summarized on the workflow page, along with a complete list of resources that follow (or are hoped to soon follow) the request and event patterns.

Finally the PlanDefinition and ActivityDefinition resources combine to support the creation of protocols, orders sets, guidelines and other workflow definitions by describing the types of activities that can occur and setting rules about their composition, sequencing, interdependencies and flow.

Common use Cases

Workflow manifests in many places in the healthcare environment:

FHIR provides multiple ways to enable these scenarios (and many others). Common mechanisms, along with their pros and cons can be found in the workflow sections on patterns.

Security and Privacy

Resources related to workflow need to adhere to the same security and privacy guidelines that apply to all FHIR resources, including specific considerations for those that may contain personally-identifying information. There are a couple of additional security and privacy considerations specific to workflow:

1. Some workflows are ad-hoc without pre-defined participants or flows. These can be challenging for security and privacy processes to manage appropriately

2. Workflow can drive automated behavior. I.e. The mere existence of an electronic record can cause information to flow, procedures to be performed, records to be changed and money to be transferred, potentially without any intervention, oversight or sanity checking by a human being. As such, even greater care must be taken to ensure that:

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

Developmental Roadmap

Initial work has taken place on aligning most (though not yet all) resources with the Definition, Request and Event patterns. In the lead-up to R4, we'll be looking to align the remaining resources, reviewing and potentially increasing the consistency of existing alignments (where beneficial to implementers) and examining the potential for exposing alignment with the patterns in a computably useful manner (e.g. as interfaces).

Work will continue on the workflow patterns, including vetting the patterns against various clinical scenarios and enhancing pattern documentation. We also hope to examine both messaging and services in more detail with further guidance about when and how such mechanisms should be used for workflow and how they relate to the Task resource. As well, we'll examine the possibility for developing "standardized" workflows for certain domains and how such patterns might be documented. We will look for implementer feedback to guide this work.

The PlanDefinition and ActivityDefinition resources will continue to evolve based on feedback from the implementer community. We'll explore using them in a variety of ways, including clinical order sets, medication protocols, workflow protocols, clinical pathways, administrative protocols, etc.

Additional topics for future work include: