In this example, all source for the IG can be found in the input
folder. There are two folders of note:
input/fsh
: This folder contains any FHIR artifacts (CapabilityStatement, Profile StructureDefinitions, etc) included in the IG in FHIR Shorthand (FSH) format. The FSH format allows these artifacts to be authored in a much more concise and consumable fashion than working directly with FHIR JSON resources. For more information on FSH please refer to:
input/pagecontent
: Any user/business authored content to be included in the IG is authored in Markdown files in this folder.
SUSHI is a command-line interpreter/compiler for FSH that can be installed by following the instructions at SUSHI Installation. Once installed, it can be executed as follows:
sushi .
When invoked, SUSHI converts the FSH content in input/fsh
into FHIR artifacts, including an ImplementationGuide
resource, which can be found in the fsh-generated
folder. These artifacts are inputs into the FHIR IG Publication in the next step.
The FHIR team provides an IG publishing tool that takes the implementation guide content and converts it into a set of published HTML files - for more information please refer to the FHIR IG Publisher Documentation. Publishing an IG requires the following:
- Ensure all pre-requisite software is installed - refer to the IG Publisher Quick Start
- If the publisher has not yet been installed, execute
./_updatePublisher.sh
to download and install the publisher locally - Execute
./_genonce.bat
to generate the published IG.
The published IG content can be found in the output
folder and can be viewed by opening output/index.html
in a web browser.
Some of the Implementation Guide page content is also generated content - specifically the contents of input/pagecontent/capabilityStatement.xml
. These files can be re-generated as required with the following commands once SUSHI pre-processing is complete:
# Install dependencies - there is currently no package.json for these scripts
npm install remarkable
npm install markdown
# Generate content (these scripts have been copied and tweaked from the NHI IG Github repo)
./localscripts/makeCapabilityStatement.js
In addition to the IG Publisher, the FHIR team also provide a FHIR IG Auto-Builder that allows IGs in public GitHub repositories to be auto-published to the FHIR Continuous Integration build service at https://build.fhir.org. The appropriate webhook configuration has been set up for this project's GitHub repository and the auto-published IG can be viewed at the following URL: https://build.fhir.org/ig/tewhatuora/cinc-fhir-ig/
Build logs are available here https://build.fhir.org/ig/tewhatuora/cinc-fhir-ig/branches/master/build.log
Normally the master branch of this repo contains the CINC FHIR Implementation Guide which is the production API specification of HNZ's FHIR repository.
While a project is doing major revisions to the master IG this is best done on a branch off master. The branch can be published as a separate draft / experimental IG at the Url
https://build.fhir.org/ig/tewhatuora/cinc-fhir-ig/branches/feature/{{branch-name}}
This means the project can review or acceptance test the IG without the mainline production Implementation Guide being affected in anyway.
Say a draft IG is on the branch rheumatic-fever Configure a webhook for automatic publication using the following command
curl -X POST "https://us-central1-fhir-org-starter-project.cloudfunctions.net/ig-commit-trigger" \
-H "Content-type: application/json" \
--data '{"ref": "refs/heads/rheumatic-fever", "repository": {"full_name": "tewhatuora/cinc-fhir-ig"}}'
Note that branch names can only contain characters in the regex [A-Za-z0-9_-]
Authoring and publishing IGs using the Simplifier infrastructure follows a completely different paradigm to the process described above. In Simplifier, IGs are intended to be authored using the Simplifier IG Editor and rendered/published from within Simplifier itself.
Unlike the FHIR IG Publisher, which outputs a fully rendered IG with merged in FHIR artifacts and Markdown content, the Simplifier IG Editor just provides some shorthand notation for rendering FHIR artifacts. Apart from that, the entire IG, including the structure and layout, would need to be manually authored in the IG Editor. The FHIR artifacts output by SUSHI can be imported into Simplifier but all of the Markdown content and FHIR IG Publisher output would need to be manually created/re-created.
It's interesting to note that most other FHIR projects in the New Zealand health sector appear to be using the FHIR IG Publisher to produce their implementation guides, with Simplifier being used as a simple repository of FHIR artifacts rather than as an IG authoring/publishing tool. Using the NHI FHIR API as an example:
- Source Repository - The source of the NHI IG, set up to build using SUSHI and the FHIR IG Publisher and publish to AWS Amplify
- Published NHI FHIR IG - The published NHI FHIR IG on AWS Amplify
- NHI Simplifier Project - This project contains a couple of imported FHIR artifacts but no authored IG or published packages
- FHIR NZ Base Simplifier Project - Again, this project contains a bunch of imported resources but no authored IG or published packages
This pattern seems to be fairly common throughout the New Zealand FHIR Registry:
- NZ FHIR Implementation Guide Index - All of the IGs referenced in the Simplifier index are external IGs that have been published using the FHIR IG Publisher.
- NZ FHIR Registry IGs - This list of NZ FHIR Registry IGs that HAVE been authored in Simplifier shows that they are all experimental/draft in nature.