How to Publish a FHIR Implementation Guide
1.0.0 - release
This page is part of the How to Publish a FHIR Implementation Guide (v1.0.0: Release) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version. For a full list of available versions, see the Directory of published versions
Official URL: http://argentixinfo.com/ig/howtopub/ImplementationGuide/ca.argentixinfo.howtopub | Version: 1.0.0 | |||
Active as of 2024-11-09 | Computable Name: HowToPubIG |
Many implementation guide (IG) authors are familiar with using HL7’s IG Publisher to author and build an implementation guide. However the process of actually “publishing” an authored IG is less familiar to many. To make an IG available to the public (or at least to a larger audience than the author), it should be on an accessible website. Further, various FHIR tooling depends being able to find an IG and its packages listed in the central registries. This IG documents the process of publishing an IG to a website using IG Publisher. It also discusses the differences between “publishing” a FHIR IG by simply uploading the IG build output to your web server; and, by uploading the results of the IG Publisher -go-publish
functionality.
This IG is not a tutorial on IG authoring; on general IG Publisher usage; or, on related tooling, such as SUSHI.
Once an IG has been authored using IG Publisher, there are several ways to make it available to the public:
-go-publish
function to stage an IG publication, then upload it to a website.Alternatively, the IG could be authored and published through Firely’s Simplifier product.
Let’s briefly consider each of these approaches.
IG Publisher users who store their projects on Github can make use of the IG auto-build to “publish” their IG to the FHIR continuous integration site under build.fhir.org
. This is a convenient way to allow others to see your implementation guide.
However, there are some drawbacks:
“Canonical redirect” is the resolution of the canonical URLs which identify the IG as well as IG profiles, CodeSystem, ValueSet, and so on, to the appropriate content. For example, the url http://example.com/ig/myig/StructureDefinition/MyPatient
is expected to return an HTML descriptive page, or JSON- or XML-formatted StructureDefinition resource representation depending on the web request. This capability depends on both the IG being published at the location that the canonical URL references, and having appropriate website configuration or redirect scripts.
The fact that the CI build content changes any time an update is made to your repository makes using the auto-build unsuitable for long-term availability of milestone releases. Further, CI build content for your IG’s non-main branch may be purged to save space; the main branch content has also occasionally been purged. The CI auto-build is not a good approach to long-term publishing.
On the other hand, the auto-build is a decent way to make your continuous integration builds, or other temporary IG versions, available for a limited time, such as sharing your in-progress work with your collaborators.
Note that the IG Publisher publication process described in this IG can reference auto-built IGs as part of the history of published versions, and in the registry feeds.
Another option to make your content available, is to upload the contents of the IG Publisher-generated output
directory directly to a web server, or to copy it to Github Pages. (Setting up automated builds and copying to Github Pages is covered in the author’s blog.)
This is essentially the same as using the auto-build, except that the output ends up on your website, rather than on build.fhir.org. And, this approach has many of the same issues as the CI auto-build.
Although uploading to your own web server won’t be subject to unplanned removal of IG versions, it offers few other benefits compared to use of the auto-build.
Note that the IG Publisher publication process described in this IG can reference continuous integration builds uploaded to your website as part of the history of published versions, and in the registry feeds.
One of key and early decisions in authoring an IG is whether to use HL7’s IG publisher or Firely’s Simplifier. Factors to consider between the two include:
However, for the purposes of this IG, the biggest difference is that a Simplifier license includes a website to publish the IG to. IG Publisher requires you to have a website to host your publication.
Publishing on your own website provides an additional level of control, and sense of ownership, that many prefer. Note though, that it is possible to download and self-host a Simplifier IG.
If you use the Simplifier development tooling, the publication considerations discussed in this document don’t apply. As pointed out above, though, publication considerations should be only one part of the decision. Both the IG publisher and Simplifier continue to evolve, and the comparative features and differentiators will change.
-go-publish
FunctionThe HL7 IG Publisher can be used to build an IG from source resources and narrative content. The output of an IG Publisher build may be uploaded to a website or made available through the CI auto-build, as described above. Using the IG Publisher’s -go-publish
functionality, it can also be used to prepare the generated content for publication, addressing several deficiencies in the basic output:
Once built using IG publisher, the IG can be uploaded to a website for wider availability.
Using this -go-publish
functionality is the subject of this IG.
The remainder of this implementation guide discusses the one-time process needed to set up an environment for publication, and the process needed to publish each release of each publication.
As a pre-requisite for the processes described in this guide, you should have write access to a website that you control, and be familiar with the process for uploading content to it. This guide assumes your publication website aligns with the canonical URLs for your IGs. (Alignment of canonicals is not strictly necessary; however, this is the most common approach, and some functionality won’t work unless the canonicals align.) You should also be familiar with basic use of the IG Publisher, use of the git
source control tool, and have access to the Github website. Github access is needed to obtain or modify certain HL7 resources. The guide describes use of Github to manage your IG as well, however you may use other (or no) content management tools for your IG and publication.
References to background material are included, as is a trivial profile of a resource which can be used to observe canonical resolution behaviour.
The HL7 IG Publisher and publishing ecosystem (templates, terminology servers, registries, etc.) are under continual improvement. The content of this IG is believed to correctly describe the processes as it exists at the time of publication. If the process changes, or an inaccuracy is found, please provide let the IG author know. The sources listed on the references page may be more up-to-date, however, they may also lag.