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

The output from the IG Publishing tool conforms to the FHIR Implementation Guide Publishing Requirements

Implementation Guide Resource Documentation

Each Implementation guide is generated from an [Implementation Guide resources]. Irrespective of the version of the FHIR Implementation guide, the IG publisher uses the current build version of the implementation guide - authors are required to use the current version (this is the only resource for which this is true).

This section documents the use of the implementation guide resource by the IG Publishing tool

Identification

• id (prohibited): do not provide an id. The IG publisher will generate it
• url (required): specify the canonical URL for the IG. This will not change over the lifetime of the IG
• version (required): this is the business version of the IG, managed by the author of the IG
• date (optional): the IG publisher will overwrite whatever you have in here
• fhirVersion (required): the FHIR version of the IG. The only valid values are: 1.0.2, 1.4.0, 3.0.1 and 3.4.0

Dependencies

Many Igs depend on other FHIR IGs. The dependencies must be listed in the IG resource.

• uri (required): the canonical URL of the IG that this IG depends on
• version (optional): the version of the IG to use. If missing, the publisher will use whatever is found at the canonical URL

Note: the IG publisher uses NPM packages to manage dependencies - see below for managing dependency resolution.

Packages

Authors are free to define packages or not in their implementation guides. The only impact of packages relates to the construction of content / table of contents etc as specified by the templates. Consult the selected template for additional information about the use of packages.

Resources

List all resources used by the implementation guide

• reference (required): the resource to include. See below for information about how the IG publisher resolves references to literal locations
• name (optional): a name to describe the resource - used when generating references to the resource throughout the content. if not provided, the IG publisher will generate a name (fall back is the id if the IG publisher doesn't know how to get a better name for resource)
• description (optional): not used by the IG publisher
• example (optional): if boolean, then used when generating indexes. If a canonical is provided, the example will be validated against the identified profile while publishing, and the example will be indexed against the profile (if the template specifies). if not present, the resource will not be treated as an example (conformance resources only)
• package (optional): used by the templates

Note that you can ask the IG publisher to load resources without listing them all - see extensions below

Pages

Lists all the pages included in the IG

• name[x] (required): use URI, which is treated as the location of the page. relative URIs recommended
• title (optional): stated title for the page. If not provided, the IG publisher will attempt to extract the page title from the content, or fall back to the name of the page
• generation (optional): how the page will treated when generating content. defaults to html. Use generated for pages that have no actual source, but will go in the ToC

Note that you can ask the IG publisher to process additional pages without listing them all - see extensions below. Unlisted pages will not be generated into the ToC

Parameters

The following additional documentation applies to the IG parameters section:

• template (required): the URL of the template to use when generating the file (for additional information about templates, see FHIR IG publisher templates)
• license (required): see below
• npm-name (required): node Package Name - see below
• npm-template (optional) : npm package template file - see below
• rule-broken-links (required): will be followed as specified
• apply-business-version (optional): will be enforced if specified
• apply-jurisdiction (optional): will be enforced if specified
• path-cache (optional): see "managing the cache" below
• expansion-profile (optional): a reference to an expansion profile that will be used when generating expansions/validating resources while publishing the IG. Though this is labelled optional, it is mandatory if the IG contains any SNOMED CT Content. See below for information about how the IG publisher resolves references to literal locations
• generate-xml (optional): will be followed as specified. default is true
• generate-json (optional): will be followed as specified. default is true
• generate-turtle (optional): will be followed as specified. default is true (except for v1.0.2 where turtle is not supported)
• logging (optional): see below
• extension-domain (optional): An extension domain for which extensions are not validated (when validating resources - typically http://example.org/fhir etc)

Still to do:

• warnings for aggregation, must-support
• logical model management

Extensions

The IG publisher defines the following extensions for the ImplementationGuide.definition section:

• scan (http://fhir.org/ig-publisher/StructureDefinition/scan-folder) - look through this nominated location (a relative URL) for resources and auto-load them as well (will be treated as if they were contained in the definitions)
• pages (http://fhir.org/ig-publisher/StructureDefinition/page-content) - process any content in this folder (a relative URL) when scanning pages. Note that pages found this way are not registered in the definitions, and won't appear in generated table of contents.
• spreadsheet (http://fhir.org/ig-publisher/StructureDefinition/spreadsheet) - load profiles from the nominated spreadsheet (literal relative location)
• unpack (http://fhir.org/ig-publisher/StructureDefinition/unpack) - Used on a resource (ImplementationGuide.definition.resource) to indicate that the resource is a bundle, and the IG publisher should unpack it bundle and treat each resource independently