Publishing and validating your work

Introduction

In this module you will learn more about validating your work, publishing it, and creating Implementation Guides. We will use Simplifier, the leading HL7® FHIR® registry, to publish the profiles we build and its IG-editor to create Implementation Guides. You can sign up for a free Simplifier account. We will use Forge, the official HL7® FHIR® profile editor, to edit profiles. You can download Forge for free.

The topics covered in this module are:

Publishing your work on Simplifier
Publishing profiles from Forge
Scope, format and content of Implementation Guides
General requirements for writing Implementation Guides
Tools for writing Implementation Guides
Validating your work in Forge and Simplifier using the .NET API

Reading material

1. Publishing your work

After completing your FHIR profiles, the next step will probably be to make them available to the world. Publishing your profiles will enable, for instance, app developers to build on your work. Simplifier is a registry for all FHIR resources. It facilitates you in using FHIR more efficiently because of its ability to search and use previous work. Moreover, Simplifier can be used as a platform to work on your profiles with multiple developers and provide feedback on each other's profiles. To learn more about Simplifier, follow the Simplifier module.

1.1 Uploading profiles from Forge

Assuming you have used Forge to author your profiles it will be very easy to publish your work thanks to the integration of Forge with Simplifier. Besides Simplifier, Forge is able to publish to any FHIR server with the click of a button.

After finishing your profile in Forge go to File at the top menu and click Publish to Simplifier.net (or press Ctrl + U instead). In the following screen you will be asked to give your Simplifier.net credentials. Register for a free Simplifier account in case you did not do so earlier. Create a Simplifier project by going to your personal portal, opening the tab Your projects and clicking on the button Create a new project. You can of course also use one of your existing Simplifier projects. Go back to Forge, and after you provided your credentials in Forge, click Connect and wait a second until the Status says Passed. Now, you can select the Simplifier project in which you want to publish your profile. Click the save button to finish the upload. Forge returns to its editor screen and your profile is now online at Simplifier.

1.2 Publishing profiles on Simplifier

If your profile is truly ready for the world you can mark it as Active on Simplifier. By default the profiles published from Forge will be marked as draft. The next step will be to find your newly uploaded profile in your project at Simplifier. Go to your personal portal on Simplifier and select the project under Your Projects. Click on your uploaded profile which can be found under the tab Resources. In your profile page, click the Status button in the top right of the page and select Active. Your profile is online and marked as Active at Simplifier.

2. Creating an Implementation Guide

The next step in publishing and sharing your work is to create an Implementation Guide (IG). An 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. An IG provides documentation about the package and the individual profiles targeting FHIR implementers and system integrators. You can find some examples on the HL7 FHIR website. More information can be found in the HL7 FHIR specification and in our blog posts: FHIR profiles and implementation guides and FHIR profiles and implementation guides (2)

2.1 Know your audience

When you start writing your IG you should keep in mind the audience you are writing it for. IGs are mostly written for developers, who can use it to implement your solution. Use language that developers understand, add examples to clarify what is expected from them and add information about how they can validate their implementation. Also consider if you want to write the IG in your native language, a common language like English or even in multiple languages. As most developers in the world will understand English, using English can make it easier to share and implement your solution across the boundaries of your country.

2.2 Scope and format

Next thing is to define the scope and format of your IG. IGs can be either written as documents (e.g. PDF) or webpages (e.g. a wiki page, a page on Simplifier or your own webpage). Given how convenient the FHIR specification is to read and link to, prefer webpages to documents when publishing.

The scope of your IG depends on the scope of your project. In general, we define the following scopes for IG’s:

Scope	Description	Example(s)
Strategy	A nationally scoped guide that provides a general overview and the strategic choices that are made. For example it describes the national infrastructure, security and privacy requirements. This guide will often reference more specific guides.	MedMij afsprakenstelsel, INTEROPen Care Connect API
Guiding principles	A guide that describes overarching guiding principles, such as regulations and basic components. This guide often serves as a foundation for future IGs.	US core IG, DE Core LeitfadenBasisDE
Subject	A guide that describes one subject. This guide describes multiple use cases and scenarios that are all related to this subject. For example, the subject could be medication or the IHE technical framework.	Lab results Norway
Use case	A guide describing a single use case and its interactions, data structures, vocabulary and testing. Examples of use cases are prescription or the IHE integration guide.	ZorgDomein FHIR interface

2.3 Content

The content of your IG depends on the scale and scope of the guide (from national to product), its intended audience and the background of your organization (e.g. are you part of a vendor or a standardization organization). In general, an IG should contain information about the use case, its actors and interactions, data definitions (e.g. your profiles) and a set of examples. You can find a template for an IG here: http://implementationguidetemplate.azurewebsites.net.

The following sections are relevant to include in your IG:

Section	Content
About the IG	A general introduction
Use case(s)	Description of the use case(s): Overview systems and architecture (System) actors overview Scenarios Triggers/reasons (interaction diagrams, sequence diagrams etc.) Pre and post conditions Datasets and data elements (could be a link to elsewhere) Business rules, policy (technology independent), for example: There has to be a diabetic control document every 3 months Systems must have a consent on file for the patient to be allowed to exchange patient data
Technical implementation guidance	Section of the IG containing technical details: Per use case/transaction Introduction and scope Boundaries and relationships (used by, uses) Actors involved Sender and receiver responsibilities (functional requirements), for example: Upon POST new resource, sender SHALL return body with newly stored resource List of invocations (message semantics, interactions, operations, search parameters) List of profiles Terminology (ValueSets, ConceptMaps) Namingsystems Mappings Examples (instances) – crucial to understanding what is expected
Profiles	Description of all profiles: Introduction & scope Usage (explanation on how to use this profile) Canonical URL (to identify profile) Must support (more detailed explanation of the meaning of the mustSupport flag for this profile, as this element is not very specific in the StructureDefinition) Data structure itself (you can render it in one or more formats, such as table, tree, XML or JSON)
Registry	Description of other FHIR artifacts that are used: Summary tables of all conformance resources Capabilitystatements Structuredefinitions + extensions Terminology, valuesets, codesystems
Security	Details on security
Appendix	One or more appendices
Help	General guidance
Contact information	Relevant contact information

2.4 General requirements for writing implementation guides

General requirements for an implementation guide are:

Provide some general documentation about the conformance package
Provide detailed documentation for each of the individual resource profiles
Include documentation from external sources, e.g. if our package has external references to (third-party) profiles published elsewhere.
Include dynamically generated content, e.g. UML diagrams, hyperlinks to related documentation etc.
Support identifying distributed content on different servers (conforming to the FHIR REST principles)
Provide different sets of documentation targeting relevant different audiences
- Architectural overview for the architects, clinical overview for the clinicians, and implementation content for developers
Reuse common content in multiple implementation guides
Separate content from design/styling

2.5 Tools for writing IGs

You can write Implementation Guides using Simplifier, the HL7 FHIR IG Publisher, and other tools.

For writing IGs using Simplifier - see our blog post on creating IGs using Simplifier, or watch our IG-editor feature movie.

You can also use the HL7 FHIR IG Publisher - download it from the HL7 FHIR site. The FHIR IG Framework defines a standardized framework around the IG Publisher that simplifies and compartmentalizes the work of IG publication.

The IG Publisher is driven by the 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. Forge has a feature for building the ImplementationGuide resource as well.

3. Validating your work

Both Forge and Simplifier are linked to the .NET API. In Forge, your work is automatically validated against the API while you're editing. After uploading your profile to Simplifier, you can validate it using the Validate button in the top right menu of the Resource page. You may also validate your examples against your profile using the same Validate button, or just against the core specification. Another place were you can validate your XML or JSON code is the Validate tool: https://simplifier.net/validate.

The .NET GUI validator enables validation of FHIR XML or JSON against the specification (this includes custom profiles), supports terminology validation and serves both as a specification and a terminology server.

Here below are links to videos explaining how to use Simplifier and the .NET GUI validator for validation:

Real-life examples

Below are examples of customers that we've helped to build their Implementation Guides.

HelseVest

HelseVest is one of four Norwegian health authorities, responsible for the western region of Norway. One of their projects is the Helsevest Prescription project, which aims to provide integrations for medication prescription.

The IG for this project was created using the IG-editor of Simplifier (see the example below). The scope of this IG is use case.

The home page of the IG contains a general introduction to the IG and a short description of the use case. The technical part of the IG is covered in the Package section. All profiles, extensions and value sets are listed in 3 separate sections of the IG. Each profile starts with a description of its metadata (canonical URL, publishing organization and status). A link to an example is also added here. Below is a description of the profile by using both tree and table rendering. Extensions and value sets are organized in a similar way. The examples section contains a link to the project on Simplifier, where examples can be found in the Resources tab. The Registry section lists all FHIR artefacts that are part of this project. Finally, the section on working with FHIR provides some help to those new to FHIR to get started.

Nictiz

Nictiz is the centre of expertise for standardization and eHealth in The Netherlands. HL7 Netherlands core and MedMij profiles are published on Simplifier. MedMij is a national project that aims to give Dutch citizens integrated access to all their health data in one personal health environment. FHIR is used as a standard to exchange health information between the involved parties. The profiles are based on standardized clinical building blocks called Health and Care Information Models (HCIM).

Nictiz uses wiki pages for creating IGs for this project. Below is an example of one of these IGs. The scope of this IG is guiding principles. The IG has several links to other IG's (e.g. the strategy scoped IG called 'Afsprakenstelsel' and subject or use case oriented IG's).

The IG starts with an 'About the IG' section explaining the scope, purpose, background of the project and intended audience. The functional design of the use cases is covered in a separate wiki page describing patient journeys, actors and activity diagrams. The technical part is organized in separate wiki pages per subject (e.g. Medication).

Each subject page describes the underlying use cases (e.g. 'Retrieve a medication overview'), actors, invocations, message content (containing links to the required profiles), interactions, operations and search parameters (including examples). Each Profile page provides general information of the profile (name, version, publication date, status and a short explanation), the concept it describes, its purpose and a description of its content. The content description provides a metadata table (formal URL, publisher, status and links to extension(s) and example(s)) followed by a tree rendering.

At the end of the page, there are contact details and links to the repository of MedMij FHIR artefacts at Simplifier, test tools and the FHIR specification.

Exercise

In this exercise you will publish your work on Simplifier and write an Implementation Guide. Here below are a couple of links that you may find useful during this exercise:

Case description

Steps to follow

1. Publishing and validating

Follow the steps of the first two exercises of the Simplifier module if you haven't completed this module yet. Both exercises are doable without going through the Reading Material first, but of course you may do so if you wish. You may skip step 6 of exercise 1.
Validate your resources using the Validate button in the top right corner of the Resource page.
Set the status of your resources to Active.

2. Creating an Implementation Guide

Go to the Guides tab of your project and create a new Implementation Guide.
Choose a meaningful title and click on Create.
The IG-editor opens. Go to the settings and choose your desired Style.
Add the required sections. Note you don't have to write out large amounts of text, just keep it simple. Adding (a couple of) sections will be sufficient for this exercise.
In the Profiles sections add your profiles. Play around with different kinds of rendering like XML code, table and tree structures. Hint: use the Help section in the bottom left corner.
Open the CSS editor and play around with additional styling options. For example, change the color of the header of your Implementation Guide.

Feedback

We are always looking for ways to improve our products. The Profiling Academy was built using our own IG-editor in Simplifier. If you have any feedback on this module or on our Profiling Academy in general, please leave a comment in the Issue Tracker of the project.

Get in touch

Start profiling

Most modules end with an exercise. Use Forge to start profiling yourself. Just contact us at simplifier@fire.ly if you need any help.

Learn more

Follow one of our predefined or tailor-made courses. We will make sure you know FHIR inside-out.

Need help or advice?

Let us assist you with your FHIR use case. Visit our company website to know more about our services or get into contact with Rien Wertheim right away.