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.

• • • Important note*** this documentation describes a version of the IG publisher tool that is yet to be written ***

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 in the [spec]
• apply-business-version (optional): will be enforced if specified in the [spec]
• apply-jurisdiction (optional): will be enforced if specified (as in the [spec])
• 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 (as in the [spec]). default is true
• generate-json (optional): will be followed as specified (as in the [spec]). default is true
• generate-turtle (optional): will be followed as specified (as in the [spec]). 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)
• history-page (optional): a relative URI that identifies a page that will be provided later that is the history of published versions. The only signficance of this parameter is that references to this page are not counted as broken links.

Still to do:

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

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
• canonical-exception (http://fhir.org/ig-publisher/StructureDefinition/canonical-exception) - see below

Managing the Cache

todo

Resolving Dependencies

todo

Resolving References

todo

License Information

The license parameter is required and is either:

• An identifier from the SPDX License List
• or literal string "Not Open Source"

For example

This FHIR Specification is licensed under Creative Commons "No Rights Reserved" for which the identifier is CC0-1.0.

"license": "CC0-1.0",

The specified license should appear in the published IG on every page (this should be done by the template)

NPM Package Information

The publisher will produce an NPM package for ease of distribution if the property "npm-name" has a value. This name is assigned by the FHIR product Director - see FHIR IG NPM Profile for details. This is required for all Implementation Guides published by HL7.

The IG publisher fills out a few mandatory elements in the package file from the information it has available. Authors can provide additional details beyond those generated by the IG publisher by providing a template which is loaded before the IG publisher writes out the details. The property "npm-template" is relative to the folder containing the configuration file

Logging Control

The IG publisher performs 3 sorts of logging:

• basic progress logging to stdout (what you see)
• A full log to [tmp]/fhir-ig-publishing-tmp.log
• in case of build failure, a debugging report to fhir-ig-publishing.log

You can change to amount of logging that goes to stdout using this logging parameter in the IG:

 "logging" : "option"

where the options are any of these words:

• init: log extra details about the IG publisher initialization sequence
• progress: log extra details about the sequence of actions taken by the IG publisher
• context: log each time a resource is added to the context (e.g. support validation)
• html: log HTML link checking details
• tx: detailed messages from the terminology sub-system

This is particularly useful when debugging the auto-build when all you get is the stdout. The logging parameter may appear multiple times.

Special Canonical URLS

For MetadataResources - CodeSystem, ValueSet, etc (anything with a canonical URL) - the IG publisher expects that their Canonical URL is equal to [canonical]/[type]/[id] where [canonical is the IG canonical URL. The IG publisher will ensure that the IG itself is an valid FHIR implementation guide and responds correctly to requests for the resources by their canonical URL.

However in some cases, it's not possible or appropriate for a metadata resource to use the same canonical URL as where the IG is publishing it. In these cases, the resources that are exempt from this rules need to be identified explicitly using the canonical-exception extension documented above.

Notes:

• Resources have to be explicitly identified because it's too easy for an author to make a mistake and get the canonical URL wrong
• one case for using this facility is where the IG includes a resource that is also published elsewhere. Author's should think hard before doing this - referring to a resource by it's canonical URL rather than copying into the IG is generally a much better approach in terms of ongoing maintenance.

Troubleshooting

Notes about troubleshooting:

1. before doing any trouble shooting, make sure you are running the latest IG publisher for the version of FHIR you are using
2. Jekyll may not run if you have spaces your file path. Move to root directory, or eliminate spaces.
3. if the Jekyll part of the build fails, it fails completely, and the old output is left in place
4. if the build completes, and there's problems in the output, first, work through all the errors in the validation output before you ask for help
5. Jekyll error "Permission denied @unlink_internal" - you have a file locked in the temp or output directory. Close any files in editors, and ensure you are only running one publisher
6. If you're going to ask Grahame for help send the file fhir-ig-publishing.log in your temp directory to grahame@hl7.org along with a detailed description of what the problem is. (Alternatively, run the GUI version click, wait for the end ofthe run, and the click on the 'Debug Summary' button which puts the log on the clipboard so you can send pate it into your email)

Before you ask about any terminology or dependency related issues, delete the content of your txCache directory, and run the IG publisher again

IG Language Support

Note: this section is draft - the functionality described here is not yet implemented.

By default, the IG publisher is semi-language agnostic. Content from resources or pages is published in whatever language is expressed in the resources and the pages, but text injected by the IG publisher itself (some sprinkled text scattered through the include files) is in English. The intent of this mode is to support English language publishing.

It's possible to publish Implementation Guides in other languages, or to publish them in multiple languages. Note, though, that there is always a single master language that the IG Publisher uses when publishing.

Specifying an Alternate Master Language

To change the language from English, specify a language using the "language" property in the json control file:

 "language" : "es-AR"

(The language tag is a standard xml:lang .e.g. BCP 47 tag. It must have a language, and may have a country (as shown above). Other sub-tags are not allowed)

When an alternative language is specified, the IG publisher changes how it works in the following ways:

• When reading any text from a resource definition, the IG publisher will first look at any [translation extensions] on the element for a matching language tag (full match including country first, then partial match). If there's no matching extension, it will just use the element value. This applies to any elements of type 'string' or 'markdown'
• When looking up codes on the terminology server, the IG publisher will ask for the specified language. tx.fhir.org uses the same approach as immediately above in this case. Note: to get code system displays in additional languages defined on tx.fhir.org, talk to Grahame Grieve
• Any text that is used by the IG publisher that is not in the specified language will be pass to an internal translation module that can translate the text to the target language. This is driven by a configuration file that has a list of mappings from language to language. The input file to configure this is languages.json in the same directory as the config file. There will be a file produced in the qa directory, also called languages.txt, which is the same file with any untranslated texts added (to help editors build the language file)
• Any content in the pages is left untouched.

Using multiple languages

In addition, the IG publisher can produce fragments in multiple languages. To do this, specify additional languages using the language property;

 "languages" : [ "du", "es", "ru"]

Note that you must specify a primary language if you specify additional languages.

When you specify additional languages, for each output file that the IG publisher creates, it will also create additional fragments with same base file name, with -[lang] appended, in the specified language. This way, authors can build IGs in multiple languages. In this case, the language file will contain additional langauge codes but work as otherwise described above.

Sharing Language Translations Across IGs

Todo. Not sure about this yet