This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "FHIR Implementation Guides"

From HL7Wiki
Jump to navigation Jump to search
Line 2: Line 2:
 
= Introducing FHIR Implementation Guides =
 
= Introducing FHIR Implementation Guides =
  
FHIR is a platform specification. It describes a general set of capabilities that can be used to solve many healthcare data exchange problems. Because FHIR is used for all sorts of problems, in many jurisdictions, using a variety of architectures and information exchange patterns, the FHIR specification is very general and there are many ways to solve a problem. For this reason, implementers must make choices, and for particular solutions to be interoperable, the implementations must make the same set of choices.  
+
FHIR is a platform specification. It describes a general set of capabilities that can be used to solve many healthcare data exchange problems. Because FHIR is used for all sorts of problems in many jurisdictions using a variety of architectures and information exchange patterns, the FHIR specification is very general and there are many ways to solve a problem. For this reason, implementers must make choices and for particular solutions to be interoperable, the implementations must make the same set of choices.  
  
 
FHIR Implementation guides (IG) are used to describe how FHIR is used in a particular context. Many IGs fit into one of these 3 categories:
 
FHIR Implementation guides (IG) are used to describe how FHIR is used in a particular context. Many IGs fit into one of these 3 categories:
Line 10: Line 10:
 
# Domain Guide: Describes the proper way to represent particular content in FHIR (e.g. how to properly represent the breast cancer diagnostic process)
 
# Domain Guide: Describes the proper way to represent particular content in FHIR (e.g. how to properly represent the breast cancer diagnostic process)
  
Note that individual IGs may cross categories, or not fall into any of these major categories.
+
Note that individual IGs may cross categories or not fall into any of these major categories.
  
 
= Finding Implementation Guides =
 
= Finding Implementation Guides =
  
The FHIR Foundation maintains a central registry of IGs. Any publicly available IG may be registered (see instructions), and authors are encouraged to do so.  
+
The FHIR Foundation maintains a central registry of IGs. Any publicly available IG may be registered (see instructions) and authors are encouraged to do so.  
  
The FHIR Foundation also maintains a general FHIR repository, which contains a finer grained set of information. This registry includes - but is not limited to - the conformance artifacts (extensions, profiles, value sets etc) found in the implementation guides published by fhir.org and hl7.org, and authors are encouraged to keep the general registry up to date. If the content in the registry is registered through the IG upload process, the registry will provide a link to the IG where the resource is published.
+
The FHIR Foundation also maintains a general FHIR repository that contains a finer-grained set of information. This registry includes - but is not limited to - the conformance artifacts (extensions, profiles, value sets etc) found in the implementation guides published by fhir.org and hl7.org.  Authors are encouraged to keep the general registry up to date. If the content in the registry is registered through the IG upload process, the registry will provide a link to the IG where the resource is published.
  
In addition, implementation guides may be found using google etc.  
+
In addition, implementation guides may be found using Google, etc.  
  
 
= Using Implementation Guides =
 
= Using Implementation Guides =
Line 24: Line 24:
 
The primary use of an implementation guide is to read it online.  
 
The primary use of an implementation guide is to read it online.  
  
Most guides offer a download facility so that that it can be used locally while offline. Note, though, that guides that reference each other will reference back to the web location, not the local download copy.
+
Most guides offer a download facility so that that it can be used locally while offline. Note that guides that reference each other will reference back to the web location, not the local download copy.
  
 
In addition, guides include, as part of their content, a set of files that are suitable for use by validation and code generation tooling. Tools that support FHIR IGs know where to find this tooling when provided with the location (root URL) of the IG (whether a local copy, or on the web).  
 
In addition, guides include, as part of their content, a set of files that are suitable for use by validation and code generation tooling. Tools that support FHIR IGs know where to find this tooling when provided with the location (root URL) of the IG (whether a local copy, or on the web).  
  
FHIR IGs have NPM package descriptions, so that IG dependency may be managed using NPM.
+
FHIR IGs have [https://www.npmjs.com/ NPM] package descriptions, so that IG dependency may be managed using NPM.
  
 
= Authoring FHIR Implementation Guides =
 
= Authoring FHIR Implementation Guides =
Line 35: Line 35:
  
 
* Getting Started
 
* Getting Started
** Describe your Implementation Guide (IG), it's scope, and it's canonical URL
+
** Describe your Implementation Guide (IG), its scope, and its canonical URL
*** for HL7 guides, this will be hl7.org. for other guides, it may be fhir.org, ihe.org etc
+
*** For HL7 guides, the root of the canonical URL will be http://hl7.org. For other guides, it may be http://fhir.org, http://ihe.org etc
** choose a template for your IG
+
** Choose a template for your IG
** create an initial implementation Guide resource with no content
+
** Create an initial ImplementationGuide resource with no content
** set up version control for your IG
+
** Set up version control for your IG
 
** Build the IG using the IG publisher
 
** Build the IG using the IG publisher
*** if the github repository is public, set up auto-publishing so that the latest version of the guide is always found on build.fhir.org  
+
*** If the github repository is public, set up auto-publishing so that the latest version of the guide is always found on build.fhir.org  
  
 
* Developing Content
 
* Developing Content
** add conformance resources (see below) that describe your implementation
+
** Add conformance resources (see below) that describe your implementation
** write narrative (html, xhtml, or markdown according to taste)
+
** Write narrative (html, xhtml, or markdown according to taste)
** add examples, images, etc to fill out the implementation guide
+
** Add examples, images, etc. to fill out the implementation guide
  
* Publishing once Complete
+
* Publishing (once complete)
** milestone builds should be published to the canonical location (copying the set generated html files around)
+
** Milestone builds should be published to the canonical location (copying the set generated html files around)
** the canonical location layout should generally follow the FHIR version publication pattern  
+
** The canonical location layout should generally follow the FHIR version publication pattern  
 
** Content to be published on hl7.org or fhir.org must be generated via the FHIR IG publisher
 
** Content to be published on hl7.org or fhir.org must be generated via the FHIR IG publisher
  
Typically, an IG will iterate between developing and publishing many times over it's time as it is drafted, and then consensus builds.  
+
Typically, an IG will iterate between developing and publishing many times over its time as it is drafted and then published in official consensus builds.  
  
 
= Kinds of content in a typical Implementation Guide =
 
= Kinds of content in a typical Implementation Guide =
  
Note that Authors should keep Best practice Guidelines for IGs in mind while developing their IGs
+
Note that Authors should keep [[Best practice Guidelines for IGs]] in mind while developing their IGs
  
  
Line 68: Line 68:
 
In addition, the following tools may be useful for IG authors while building IGs:
 
In addition, the following tools may be useful for IG authors while building IGs:
 
* Editing Profiles / extension definitions / logical models: Forge
 
* Editing Profiles / extension definitions / logical models: Forge
* Editing Implementation Guide resources
+
* Editing Implementation Guide resources: Forge (limited)
 
* Editing Value Sets, Concept Maps & Code systems:
 
* Editing Value Sets, Concept Maps & Code systems:
 
* Editing Example Scenarios:
 
* Editing Example Scenarios:

Revision as of 04:40, 25 April 2018

Introducing FHIR Implementation Guides

FHIR is a platform specification. It describes a general set of capabilities that can be used to solve many healthcare data exchange problems. Because FHIR is used for all sorts of problems in many jurisdictions using a variety of architectures and information exchange patterns, the FHIR specification is very general and there are many ways to solve a problem. For this reason, implementers must make choices and for particular solutions to be interoperable, the implementations must make the same set of choices.

FHIR Implementation guides (IG) are used to describe how FHIR is used in a particular context. Many IGs fit into one of these 3 categories:

  1. Jurisdication Base: Describes based rules for using FHIR in a jurisdiction (usually a country specific set of rules)
  2. Application Solution: Describes how FHIR is used to solve a particular problem (e.g. EHR App access)
  3. Domain Guide: Describes the proper way to represent particular content in FHIR (e.g. how to properly represent the breast cancer diagnostic process)

Note that individual IGs may cross categories or not fall into any of these major categories.

Finding Implementation Guides

The FHIR Foundation maintains a central registry of IGs. Any publicly available IG may be registered (see instructions) and authors are encouraged to do so.

The FHIR Foundation also maintains a general FHIR repository that contains a finer-grained set of information. This registry includes - but is not limited to - the conformance artifacts (extensions, profiles, value sets etc) found in the implementation guides published by fhir.org and hl7.org. Authors are encouraged to keep the general registry up to date. If the content in the registry is registered through the IG upload process, the registry will provide a link to the IG where the resource is published.

In addition, implementation guides may be found using Google, etc.

Using Implementation Guides

The primary use of an implementation guide is to read it online.

Most guides offer a download facility so that that it can be used locally while offline. Note that guides that reference each other will reference back to the web location, not the local download copy.

In addition, guides include, as part of their content, a set of files that are suitable for use by validation and code generation tooling. Tools that support FHIR IGs know where to find this tooling when provided with the location (root URL) of the IG (whether a local copy, or on the web).

FHIR IGs have NPM package descriptions, so that IG dependency may be managed using NPM.

Authoring FHIR Implementation Guides

The general workflow for authoring an implementation guide is as follows:

  • Getting Started
    • Describe your Implementation Guide (IG), its scope, and its canonical URL
    • Choose a template for your IG
    • Create an initial ImplementationGuide resource with no content
    • Set up version control for your IG
    • Build the IG using the IG publisher
      • If the github repository is public, set up auto-publishing so that the latest version of the guide is always found on build.fhir.org
  • Developing Content
    • Add conformance resources (see below) that describe your implementation
    • Write narrative (html, xhtml, or markdown according to taste)
    • Add examples, images, etc. to fill out the implementation guide
  • Publishing (once complete)
    • Milestone builds should be published to the canonical location (copying the set generated html files around)
    • The canonical location layout should generally follow the FHIR version publication pattern
    • Content to be published on hl7.org or fhir.org must be generated via the FHIR IG publisher

Typically, an IG will iterate between developing and publishing many times over its time as it is drafted and then published in official consensus builds.

Kinds of content in a typical Implementation Guide

Note that Authors should keep Best practice Guidelines for IGs in mind while developing their IGs


Tooling Support for Authoring FHIR Implementation Guides

Main tool chains for publishing FHIR IGs:

In addition, the following tools may be useful for IG authors while building IGs:

  • Editing Profiles / extension definitions / logical models: Forge
  • Editing Implementation Guide resources: Forge (limited)
  • Editing Value Sets, Concept Maps & Code systems:
  • Editing Example Scenarios:
  • Editing Questionnaires:

Other resources have to be edited by hand.