FHIR IG Publishing tool

Introduction

The FHIR team provides an tool used for publishing FHIR Implementation Guides. The tool takes the input of the implementation guide (resources, narrative, template) and converts it to a set of different types of files:

• generated HTML pages
• resources (+ canonical redirections)
• some zip files
• qa.html which contains information about the errors/issues found in the build process

The "FHIR IG" is the set of files produced by the IG publishing tool. These files can be posted to a web server.

Using the IG Publisher

Installing

1. Get the publisher itself: this is a java jar called org.hl7.fhir.igpublisher.jar. You can get it from the build.fhir.org downloads (e.g. http://build.fhir.org/downloads.html) for the version of FHIR you are using (or, if you build locally, from your own publish directory). The jar includes everything from the spec that is required to generate the implementation guide.
2. Get the publishers helper: you need to install Jekyll in order to publish the said implementation guide. See Windows and Linux instructions.

Always use the current version of the IG Publisher from the build site - no other version is supported. You use this version irrespective of the FHIR version of the IG you are publishing. The publisher can be run as a GUI application, or run from the command line. Alternatively, you can use the IG Publisher in web server mode. If you do this, you don't need any installed software - if you want to host it, talk to Grahame Grieve.

Running in command line mode

To run in command line mode, run the IG Publisher like this:

 java -jar org.hl7.fhir.igpublisher.jar -ig [source] (-tx [url]) (-watch)

parameters:

• -ig: a path or a url where the implementation guide is found
• -tx: (optional) address to use for terminology server (default is http://tx.fhir.org/r4, which is currently the only supported option)
• -watch (optional): if this is present, the publisher will not terminate; instead, it will stay running, and watch for changes to the IG or its contents and re-run when it sees changes. Note that changes the spec or to dependent implementation guides (see below) are not picked up during watch mode

Advanced parameters:

• -resetTx - clear out the txCache (see comments below about managing the freshness of the txCache)
• -resetTxErrors - delete any errors from the tcCache, but leave successful operations in the cache

Windows example:

Open the command prompt, then paste the following, with the paths adjusted for your computer:

 java -jar "C:\Users\VadimPeretokin\Desktop\fhir-publisher\org.hl7.fhir.igpublisher.jar" -ig "C:\Users\VadimPeretokin\Desktop\fhir-git\tests\ig\test-ig.json" -watch

Linux: Open the terminal (usually Ctrl+Alt+T), then paste the following, with the paths adjusted for your computer:

 java -jar '/home/vadi/Programs/fhir-publisher/org.hl7.fhir.igpublisher.jar' -ig '/home/vadi/Programs/fhir-git/tests/ig/test-ig.json' -watch

Running in GUI mode

Windows: double-click on org.hl7.fhir.igpublisher.jar or right-click and select 'Open'.

Linux: double-click on org.hl7.fhir.igpublisher.jar or right-click and select 'Open With Oracle Java 8 Runtime'.

You can also run it the command line:

 java -jar org.hl7.fhir.igpublisher.jar

Note that this doesn't work in OpenJDK - if you are using openJDK, your only option is to run it from the command prompt, as described below.

This is the IG builder:

To use it, 'Choose' an implementation guide control JSON file, and click 'Execute'. The implementation guide will be built, and then the IG publisher will watch for changes until and do incremental rebuilds until you click 'Stop'.

Using the IG Publisher Web Server

The IG publisher lives at [[1]]. From there, you can upload a ip file containing the contents of the IG. After processing, you can download the output.

Note that it's a little inconvenient to flip between modes (running locally vs using the web publisher) because the standard folder structures include /qa, /temp, and /output - you don't want to upload these - they can be very large (though the IG server will ignore them if you do). Also, the web publisher maintains it's own terminology server cache, and may give different results for expansions etc than if you are using your own txCache in the folder and not keeping it up to date.

You can also use the API to the IG web publisher directly. To do this, POST a zip containing the IG content to http://hapi.fhir.org/igweb/process (Content-Tyepe: application/zip), and after a period of seconds, a zip file containing the generated output will be returned.

Publishing IGs

Operation of the IG Publisher

The implementation guide follows this general process:

• reads the Implementation guide
• loads all the resources in the IG, and processes any spreadsheets, and bundles referred to in it
• processes code systems, value sets, structure definitions, structure maps
• processes the logical models
• validates the all resources and produces an HTML QA file with any errors encountered
• fetches the template for the IG
• for each resource in the IG, as specified by the template, generates a set of files - renderings of the artifact for possible inclusion in the published IG, plus the outputs defined above
• generates summary output
• use Jekyll to generate the final output. The Jekyll source is in /pages by default
• checks for well formed html, broken links, and security risks in the generated pages