ImplementationGuide Guidance

Introduction

Over the past year, the FHIR community has started writing Implementation Guides, much like the CDA community has been doing for the past decade. Although the requirements for CDA users and FHIR users differ (mostly because of the different underlying technologies), we have tried to compile a representative and comprehensive list of the kinds of information we encountered looking at a fair number of guides, both the newer FHIR guides and existing (international) CDA guides.

Kinds of Implementation Guides

What is an implementation guide? You have a set of usecases and the guide describes how you go about implementing these using FHIR/v3/v2. It includes data definitions, but also actors, interactions, strategy, testing, usecases.

Implementation Guides vary widely in scope. We have tried to categorize them based on scale of information as follows:

• Strategy A nationally scope guide, providing overview, strategic choices and is referencing more specific guides. (i.e. national telematic infrastructre, security and privacy requirements)
• Principles A guide describing overarching principles (i.e. “basiscomponentengids”) – “Regulations”
• Subject A guide describing a subject (i.e. medication processes) which describes mutliple usecases and scenarios - “IHE technical framework”
• Usecase A guide describing a single usecase and its interactions, datastructures, vocab, testing (vb: prescription) – “integration profile” IHE

The kind of Implementation Guide you are writing largely determines which sections and information are relevant.

Note that the logical hierarchy described here is not always the order in which the guides are created. Often, a few specific guides are written first for certain early or pilot scenario's after which a normalization process is adopted to write more global overall guides and make sure more specific guides are aligned across communication contexts, organizations and nations.

List of content found

Below is the list of content we found, categorized under headings we feel are likely candidates for suggested section headers in an Implementation Guide. Exactly which information is relevant is dependent on the scale of the guide (from national to product oriented), the intended audience and the background of the organization producing the guide (SDO’s, hospital IT departments), so the list below can never be more than a list of “reminders”, a “check list” that authors can use to see if they have forgotten obvious information.

Title of the Guide

• language (per section?),
• identifier

Table of Contents

• Generated headers + links to sections

Document information

Information about the implementation guide as a “piece of paper”, publication metadata, “colophon”.

• Structure of this guide (e.g. explanation of main chapters, place in the hierarchy of implementation guides)
• Imprint (bibliographic information, the publisher's name and address, date of publication on a title page)
• Primary contact party for this guide
• Client / customer (who ordered the creation of this guide)
• Governance Group (contact + name of the party responsible for the artifact’s lifecycle). “IHE PCD Technical Committee”
• Editors / Authors / Contributors (individuals) / Publisher
• Copyrights for this guide / License for this guide / IP for this guide
• Acknowledgements
• Ballot and harmonization (+type, status IG, i.e. DSTU and what does that mean, ballot so far)
• Revision list (versions, version dates)
• Disclaimer

Introduction to the Guide

• Rationale / purpose / context (why) – “Improve outcome for X, less errors in process Y, more efficient practice in prescribing”
• Objective (same as purpose?) – “New paradigm for prescribing X to patient group Y”
• Audience (for who) (for usecase oriented guides, there are mostly the developers, for other levels these might be architects, doctors, etc.)
• Scope and boundaries (what not) - “This guide does not describe control of device parameters”, “This guide describes observation reporting by devices”
• Relationships with other projects and guides, Preliminary work. “See the national security and architecture guidance available here”, “All models in this guide are based on the National Organization Registry implementation guide datamodels”
• Legal obligations. “This guide is part of the set of Austrian national infrastructure guides and implementing parties within this jurisdiction must conform to it”

Principles and background

• Prerequisites (most of this is boilerplate, standard content that can be put elsewhere and referenced. It’s standard (fhir,v3,v2) specific.)
  • Working with the standard (FHIR)
  • Working with identifiers and identifier systems
  • Working with vocabulary, coding systems and valuesets
  • “Profiling FHIR” (referencing parts of the standard, extra documentation)
  • Artifact versioning (reference)
  • Dealing with extended content (allow extensions, binding strength)
  • http://hl7.org/fhir/conformance-rules.html
  • Conformity / optional, required, mandatory, conditional
  • Conformance Verbs (Keywords) – not a reference, include Cardinality
  • Vocabulary Conformance
  • How to (use RESTful, query/response)
• Datatypes used in this guide
• Design conventions and principles (background on why stuff was designed the way it is in this IG)
• General implementation guidance
• Standards used (SNOMED-CT, HIPAA)
• Legenda (description of formalisms used, symbols, icons)

Note: much of the prerequisites are part of the core spec, or of separate guidance on the HL7 wiki.

Conformance clause

• will receive them by email from Rob

Functional requirements and high-level use cases

• Overview of systems and architecture
• (System)Actors overview
• Usecases
  • Scenarios
  • triggers/reasons (interaction diagrams, sequence diagram, etc)
  • pre- and post conditions
• Dataset and Data elements (business view about what is exchanged, could be a reference)
• Business rules, policy (exchange and technology independent) “There has to be a diabetes control document once every three months”. “Systems must have a consent on file for the patient to be allowed exchange patient data”

Specific conformance rules

• Technical business rules and conformance conventions specific to this implementation guide (e.g. use of dataabsent reason, “MustSupport means the system is able to display the patients address fully on a label”)

Package contents (one per interaction? Group of interactions?) 1..*

• Introduction
• Scope
• Boundaries & Relationships (used by, uses)
• Actors involved
• Sender and receiver responsibilities (functional requirements) – “Upon a POST of a new resource, the sender SHALL return a body with the newly stored resource”.
• List of structures, extension references (structures may be shared across interactions). Point to pages with StructureDefinitions etc. with some intro + notes
• List of invocations (interactions, operations, search parameters - in FHIR modelled as a Conformance resource)
• Terminology (valueset, conceptmaps)
• Naming Systems (identifying system oids, code system identifiers)
• Mappings (model to model, functional datamodel to terminology and technical model)
• Examples (instances, links to full examples)
• Implementation Guidance (both structural “representing no known medications”, and functional “how to query a patient by national identifier”)

Note: some of these items may cover definitions that are used across packages, in which case the item (or a subset) can be described one level up on Implementation Guide level.

Privacy and security Guidance

• privacy policy
• security architecture
• security implementation guidance

Appendix

• Acronyms and abbreviations
• Glossary
• Licenses (for the artifacts used, for the code systems, etc.)
• Integrated examples, links to instances
• Validation artifacts (xsd, schematrons)
• Links to platforms, binaries, software libraries
• Operational information (helpdesk, actual server endpoints for testing/production/validation)
• FAQ’s
• References / Literature

List of all artifacts used in this guide

• System OIDs / IDs
• Code systems
• StructureDefinitions + Extensions
• Value Sets
• Summary tables

Note: these lists are all generated from existing content

For discussion in the Oct 2015 WGM Atlanta

• How does one map the domain to packages. One package for each usecase? One for each scenario? One package for a “subject”?
• If the FHIR guide describes the use of a FHIR Document, should we reflect the CDA leveing in the guide? Using packages?
  • CDA Document Level Templates
  • CDA Header Level Templates
  • CDA Section Level Templates
  • CDA Entry Level Templates
• Which sections are most appropriate for which kinds/levels of Implementation Guides. Is this relevant/possible at this moment to formulate?
• Create guides for specific audiences? Is there are “one size fits all”?

TODO

• Better descriptions for each chapter/section/item + examples from actual implementation guides.

Examples (in progress)

I copied this stuff from an existing Implementation Guide to be sure we will find *a* place to put this.

D.0.3.1 Definitions, Interpretations and Requirements common to all DAF actors This section outlines important definitions used in the DAF FHIR IG including interpretations that need to be used in the context of DAF and conformance requirements common to all DAF actors. The conformance verbs used are defined in FHIR Conformance Rules. In the context of DAF profiles, Supported on any data element SHALL be interpreted as follows:

• DAF Responders SHALL be capable of including the data element as part of the query results as specified by the DAF conformance resources.
• DAF Requestors SHALL be capable of processing resource instances containing the data elements. In other words DAF Requestors SHOULD be capable of displaying the data elements for human use or storing it for other purposes.
• In situations where information on a particular data element is not present and the reason for absence is unknown, DAF Responders SHALL NOT include the data elements in the resource instance returned as part of the query results.
• When querying DAF Responders, DAF Requestors SHALL interpret missing data elements within resource instances as data not present in the DAF Responder's systems.
• In situations where information on a particular data element is missing and the DAF Responder knows the precise reason for the absence of data, DAF Responders SHALL send the reason for the missing information using values from the value set where they exist or using the dataAbsentReason extension.
• DAF Requestors SHALL be able to process resource instances containing data elements asserting missing information.
• NOTE: DAF Responders who do not have the capability to store or return a data element tagged as Supported in DAF profiles can still claim conformance to the DAF profiles using the DAF conformance resources.
• NOTE: The above definition of Supported is derived from HL7v2 concept "Required by may be empty - RE" described in HL7v2 V28_CH02B_Conformance.doc.

Conformance conventions used

• Conformant servers will at minimum support FHIR's read and search operations
• Servers SHALL supply the Must Support data elements whenever that data is available
• Quality improvement applications SHALL recognize and process all MustSupport elements in QICore
• Modifying attributes SHALL be treated as MustSupport, even if not explicitly declared
• The resources in "Any" references SHALL conform to QICore profiles if the base resource has a QICore profile
• Applications SHALL NOT process resource instances that include unknown modifying attributes
• Applications SHOULD using the preferred value sets)

Testing and certification

• test (test data, test scripts, testing endpoints) (but this may well be a reference to a separate test site or document, since the lifecycle of the guide and the test site may differ)
• certification procedure (certification body, application, requirements)