How To Build This Implementation Guide
Intended Audience
This section describes the type of audience that the section or page is targeted at (if any) where none is stated then the page should be seen as a general page for every reader.
| Audience | Description |
|---|---|
| Clinical | Someone who is reviewing the implementation guide from a clinical perspective, including clinical safety, clinical pathway and informatics; as a clinical professional involved in initial implementations or further roll-out approaches |
| Business | Someone who is reviewing the implementation guide from a business process perspective; as a business analyst looking into workflow and the impact on existing business processes |
| Architect | Someone who is reviewing the implementation guide from an architectural perspective; as a solution architect looking into how this implementation will fit in with existing systems and interfaces |
| FHIR | Someone who is reviewing the implementation guide from a standards perspective; as a person with FHIR knowledge involved in reviewing the implementation guide for compliancy with the FHIR standard or alignment with other FHIR implementations |
| Developer | Someone who is reviewing the implementation guide from a development perspective, the developer who will be coding or involved in the building of the API or system |
| Other | Someone looking into the contents of the implementation guide for any other reason, for example as part of their education or a research project. This type of audience is implied and not shown in the table below. |
Format and Structure
The table below gives the reader of this implementation guide guidance about the structure of the guide and an indication of the purpose and intended audience of the sections and pages the guide contains. The intended audience is included to illustrate which type of reader the page is primarily aimed at and of course does not exclude other types of readers from reviewing and feeding back to the team producing the implementation guide.
Note: not all pages described in the table will be present in every implementation guide as the content is dependent on things such as:
- How the information is exchanged (which FHIR Paradigm used RESTful, Messaging, Document etc.)
- Whether Clinical headings are used in the exchange of the information
- Which FHIR assets are used in the information exchange
- The type of information that is being exchanged
| Page | Subpage(s) | Description and purpose | Usage | Intended Audience |
|---|---|---|---|---|
| Home | This is the starting point for readers and should be the page that is used when a link is provided to the Implementation Guides | Will be present | ||
| Introduction | This gives a brief overview of the implementation guidance around things such as: uses cases, scope etc. | Will be present | ||
| How to use this implementation guide | This gives a generated site map of the implementation guide and guidance to help them understand the implementation guide | Will be present | ||
| Release notes | Gives the change history and any additional information to help the reader understand the changes to the guide. The latest changes will be added to the top of the page. | Will be present | ||
| Guide versioning | Details versioning of implementation guides and what the different stages are, links to a separate guide | Will be present | ||
| Glossary | A glossary of terms and acronyms used, links to a separate guide | Will be present | ||
| FHIR Assets | A section that has subpages for each of the FHIR assets, not all FHIR assets are used for all implementations | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| Profiles | The page will contain the Profiles for this implementation guide | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| Extensions | The page will contain the Extensions used by this implementation guide | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| CodeSystems | The page will contain the CodeSystems for this implementation guide | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| ValueSets | The page will contain ValueSets for this implementation guide | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| ConceptMaps | The page will contain the ConceptMaps for this implementation guide | May be present | Clinical, Business, Architect, FHIR, Developer | |
| SearchParameters | The page will contain the SearchParameters for this implementation guide | May be present | Business, Architect, FHIR, Developer | |
| OperationDefinitions | The page will contain the OperationDefinitions for this implementation guide | May be present | Business, Architect, FHIR, Developer | |
| CapabilityStatements | The page will contain the CapabilityStatements for this implementation guide | May be present | Clinical, Business, Architect, FHIR, Developer | |
| Message Definition | The page will contain the Message Definitions for this implementation guide | May be present | Clinical, Business, Architect, FHIR, Developer | |
| Naming Systems | The page will contain the Naming Systems for this implementation guide | May be present | Clinical, Business, Architect, FHIR, Developer | |
| All Assets | This page is a navigation page and lists the FHIR Asset types | Will be present | ||
| Design | This section details the design of the FHIR implementation/ use case, it will detail such things as the interactions, transport used, how the data is exchanged etc. | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| Design overview | An overview of the design approach | Will be present | ||
| Data Mapping | The mapping of the data to be exchanged to the FHIR assets. This may be a defined national dataset or just an agreed list of data items for a first of type | May be present | Business, FHIR | |
| Interactions | This page will contain text and diagrams which describe how the systems/users/device interact with each other | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| Clinical headings | This page describes how the information is structured using clinical headings if they are used | May be present | Clinical, Business | |
| Clinical heading[X] | This page may repeat once for each bundle type used, The [X] will be replaced with the heading type or name | May be present | Clinical, Business | |
| Transport | This page will detail the transport layer used for this implementation guide | May be present | Business,Architect | |
| FHIR document bundle [X] | This page may repeat once for each bundle type used, The [X] will be replaced with the bundle type or name | May be present | Clinical, Business, Architect, FHIR, Developer | |
| FHIR document rendering | This page gives guidance and information on how to render the FHIR document if this is the method of exchange | May be present | Clinical, Business, Developer | |
| FHIR document replacement and updates | This page gives guidance and information on how to render the FHIR document if this is the method of exchange | May be present | Business, Developer | |
| Use of attachments | If attachments are allowed, this page will detail how they are used, and the types allowed | May be present | Business, Developer | |
| Acknowledgments and responses | What acknowledgements or responses are used, if any and how and when to use them | May be present | Clinical, Business,Architect,FHIR | |
| Events model | If a events model is used this page will detail what it is and how its used | May be present | Clinical, Business,Architect,FHIR | |
| Events publishing and receiving requirements | If this implementation is event based this page will detail publishing and receiving requirements | Clinical, Business,Architect,FHIR | ||
| Build | This section is about how to build a system or API using this implementation guide | Will be present | ||
| How to construct bundle | This section details how to construct bundles | May be present | Developers | |
| Bundle [X] | This page may repeat multiple times if there are multiple bundles types exchanged and will give guidance to developers on how to construct the bundles. The [X] will be replaced with the bundle type or name | May be present | Developers | |
| How to construct message | This section details how to construct messages | May be present | Developers | |
| How to construct message[X] | This page may repeat multiple times if there are multiple message types exchanged and will give guidance to developers on how to construct the messages. The [X] will be replaced with the message type or name | May be present | Developers | |
| How to construct clinical coded structures | This section gives guidance on how to construct clinical structures in FHIR instances, for example how to represent a patient's allergies | May be present | Developer | |
| How to construct [X] | This page may repeat multiple times if there are multiple clinical structure types exchanged and will give guidance to developers on how to construct the structure type. The [X] will be replaced with the clinical structure type or name | May be present | Developers | |
| API usage | This page is used to describe how the API is used in a real life environment | May be present | Clinical, Business, Architect, FHIR, Developer | |
| Error handling | Describes any error handling that is applicable for the implementation guide | May be present | Clinical, Business, Architect, FHIR, Developer | |
| Query types | The query types supported by this implementation guide, only applicable for REST | May be present | Clinical, Business, Architect, FHIR, Developer | |
| Operation responses | This page is used to describe the search operations supported by the API and their responses. | May be present | Clinical, Business, Architect, FHIR, Developer | |
| Examples | This page gives an overview of the examples section. | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| Example [X] | A page which contains a FHIR example structure. This may be just a single FHIR resource or multiple resources for example a Bundle. The example may be in JSON or XML or both depending on the format used by the implementation | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| Authentication | This page needs a brief overview of the authentication section | May be present | Architect, Developer | |
| Access control | This page describes the access control guidance or requirements | May be present | Architect, Developer | |
| Access tokens | This page describes the access tokens guidance / requirements | May be present | Architect, Developer | |
| Auditing | This page describes the auditing requirements | May be present | Architect, Developer | |
| Security | This page describes the security guidance / requirements | May be present | Architect, Developer | |
| Integration with SPINE | This page describes any guidance / requirements about integration with SPINE. | May be present | Architect, Developer | |
| Downloads | This page provides link(s) to download artefacts that may be useful to help with developments such as NPM packages for validation | Will be present | Clinical, Business, Architect, FHIR, Developer | |
| Help and support | This page gives contact details for help and support | Will be present | Clinical, Business, Architect, FHIR, Developer |
Design Rules for NHS Digital IGs: Creation and Maintenance
Scope
The scope of this document is all Implementation guides hosted on the NHS Digital Organization Simplifier account regardless of who produces them. It does not apply to any IG hosted on the HL7 organization Simplifier account.
Overview
This document details the rules that SHALL be followed when producing NHS Digital FHIR Implementation Guides (IGs). The purpose is to drive consistency and quality across the IGs produced by either IOPs or other NHS Digital teams.
Rationale for Document
NHS Digital has stated it is a “centre of excellence” and as such we use and follow accepted standard processes and best standards for our programmes. The current FHIR IG approach although not perfect, is a mature process which works and ensures conformance with the FHIR standard and the HL7 UK community process which is something NHS Digital must support as a key part of our standards delivery.
What is a FHIR IG
A FHIR IG (Implementation Guide) is the accepted way of documenting implementation guidance for FHIR which is used by all the major FHIR implementing countries and is defined in the FHIR standard as:
“An implementation guide (IG) is a set of rules about how FHIR resources are used (or should be used) to solve a particular problem, with associated documentation to support and clarify the usage”.
It is based on the FHIR ImplementationGuide resource:
“The ImplementationGuide resource is a single resource that defines the logical content of the IG, along with the important entry pages into the publication, so that the logical package that the IG represents, so that the contents are computable.”
“In particular, validators are able to use the ImplementationGuide resource to validate content against the implementation guide as a whole. The significant conformance expectation introduced by the ImplementationGuide resource is the idea of Default Profiles. Implementations may conform to multiple implementation guides at once.”
FHIR IGs are usually published as a set of HTML pages and associated FHIR assets.
The use of IGs is recommended by the HL7 and HL7 UK Community process.
Why use FHIR IGs
FHIR IGs are the accepted way that FHIR specifications are published. Some of the major vendors will be implementing FHIR in more than one province / country. For example, they will be implementing US Core which is an IG and therefore the UK Core follows the same accepted format i.e., is an IG. NHS Digital must also follow this accepted way of publication for its FHIR specifications to align with the rest of the world and to avoid deviation from the standard or “reinventing the wheel”.
FHIR Specification Audience
The audience of a FHIR IG is large and varied some of typical consumers (in no particular order) are listed below:
- FHIR experts
- Developers
- Clinicians
- Solution Architects
- Technical Architects
- Clinical Informaticians
- Business Analysts
- Project Managers
- Interoperability Managers
Each of these may have a preferred view of the FHIR specification and therefore it is acceptable and probably desirable to publish different views of the same IG content for a specific audience, however it is important to have only one version of the source content which SHALL be the FHIR IG with other views created or generated from that source.
Use of Simplifier
IOPS and HL7 UK use the Simplifier platform for some of the following reasons:
- Enables FHIR compliant IGs to be produced.
- Allows validation of IGs against the FHIR standard.
- Allows the creation and maintenance of NPM Packages with full version control.
- Supports publication of packages to the FHIR Package Registry (https://registry.fhir.org/), which is highly desirable to share the packages with the FHIR community locally and internationally.
- Enables derived IGs to be created and validated with full dependency tracking.
- Supports version control for all FHIR assets including rendering of multiple versions of a given asset for a given IG version.
- Supports custom templates and stylesheets.
Use of packages
The accepted FHIR approach for implementation of FHIR and validation of implementations is the use of NPM packages. This approach is endorsed by all the major UK vendors for FHIR implementations. All NHS Digital IGs SHALL use NPM packages.
HL7 Packages
Excerpt from the FHIR standard below: “One use of Packages is to bundle together all the FHIR artefacts in an Implementation Guide to make them easier to locate and download. More specifically, a package will contain the FHIR resources for a specific version of an Implementation Guide - indeed, it was the complexity of versioning Implementation Guides and FHIR resources that led to the adoption of packages. It will not, however, contain the other components of an Implementation Guide such as the documentation or the IG layout (menus, images, summary pages etc). So, a package is stable, versioned collection of resources - often those from an Implementation Guide.”
Conformance Statement
It is a FHIR requirement to use a CapabilityStatement to define an implementations capability. All NHS Digital IGs SHALL include a CapabilityStatement and associated guidance.
HL7 UK Community Process
All NHS Digital IGs SHALL comply with the HL7 UK community process
IG Design Rules
This section details the design rules that SHALL be followed by any creator of an IG hosted in the NHS Digital Simplifier Organization account.
Use of Stylesheets and Templates:
- All IGs SHALL only use an approved version of the IG stylesheet.
- The latest version of the stylesheet SHOULD be adopted wherever possible.
- Custom stylesheets SHALL NOT be used by any IG creator.
- New IGs SHALL conform to the latest approved template.
- Pre-existing IGs SHALL conform to an approved template.
- Pre-existing IGs SHOULD conform to the latest approved template.
- Changes to stylesheets SHALL be requested and approved before implementing in any Simplifier project.
Requesting Stylesheet Changes
All changes for a change to the IG stylesheet SHALL be requested via Simplifier issue tracking. This SHALL be done on the Current Template project.
Approval of Stylesheet Changes
All requests for change
Simplifier Projects
There SHALL be two projects for IG templates and stylesheets:
- Current Template
- Development Template
Current Template Project
This will contain the current stylesheet and template that SHALL be used as the basis for creation of all IGs. These SHALL be clearly marked with version numbers to indicate they are the latest versions.
Development Template Project
This will contain any stylesheets and templates that are in development and SHALL NOT be used as the basis for creation of any IGs. These SHALL be clearly marked with version numbers to indicate they are new versions.
Updating Approved Template/Stylesheet
The development stylesheet and/or template SHALL be approved by the IOPS Design Authority before it is released to the current template project. The development stylesheet and/or template SHALL NOT be used for development or creation of any IG except for testing and review in the development template project. Release of and development or the stylesheet will usually be done in maintenance sprints but there may be a requirement to do bug fixes etc.
Stylesheet Versioning
- All stylesheets used SHALL be versioned.
- Any change to the stylesheet SHALL increment the version of the stylesheet.
NHS Digital IG Style Guide
- All IGs SHALL comply with the NHS Digital style guide.
Review of IGs
This section gives the overview rules for preparing for a review:
- All IGs SHALL be reviewed prior to sharing or releasing to an external audience.
- Creators of IGs SHALL NOT submit IGs for review that do not conform to the rules.
- Reviewers of IGs SHALL discontinue the review immediately if the IG is found to not conform to the rules.
FHIR IGs SHALL conform to certain rules see below: All NHS Digital IGs SHALL comply with the following:
All NHS Digital IGs SHOULD comply with the following:
There is also guidance on how to review an IG.