FHIR IG Framework

This Framework makes use of the IG Publisher to produce implementation guides, but defines a standardized framework around the IG Publisher that simplifies and compartmentalizes the work of IG publication.

Pros

• The Framework ensures that source files are schema-validatable as much as possible
• The Framework isolates and ensures consistency around more complex aspects of HTML maintenance
• The Framework allows division of responsibility such that those responsible for creating artifacts, terminology and page content can work separately from those responsible for the overall look & feel of the IG
• The use of XHTML for page content rather than markdown maximizes control over the look & feel of the published IG

Cons

• The approach requires slight pre-processing of content by running 3 transforms using an Ant script. This pre-processing needs to be run any time the FHIR ImplementaitonGuide instance is changed.
• The ImplementationGuide instance requires a bit more content in order to have enough information to process all web pages in the IG and to properly expose artifacts defined in spreadsheets.
• The process relies on the use of the XML syntax for the ImplementationGuide and uses XHTML to define page content. It may not be attractive to editors who prefer to author resources using JSON or to author text content in markdown.

Approach

Rather than defining the IG configuration JSON file directly, implementers perform all of their definition using the FHIR ImplementationGuide instance as an XML file. This includes enumerating all resources, including those defined in spreadsheets, as well as defining the page hierarchy. HTML pages are not defined as Jekyll pages directly, but rather are defined as XHTML DIV instances that are directly valid against the XHTML schema. This simplifies editing. As well, source files are organized for more straight-forward maintenance. Table of contents, section numbers, an artifact index and breadcrumbs are automatically generated and inserted where appropriate.

Setup

Like any process that uses the IGPublisher, this process requires the use of a Java Virtual Machine (1.8 or higher) and the use of Ruby (which must be available on the machine's "path") and Jekyll - all of which are listed in the base IG Publisher documentation. For convenience, instructions to install are as follows:

JVM

• Start by seeing if you've already got an appropriate JVM installed
  • Open a command window
  • Type 'java -version' and see what happens. If you see "java version "1.8.x_xxx", (or possibly 1.9), then you're fine
• If not, go to the [1] website and follow the instructions to download and install java

Ruby

• For Windows:
  • Go to [2] and download Ruby 2.3.3 or higher - use the 64 bit version for 64 bit machines or the regular one otherwise
  • Run the installer

Jekyll

• Open a Ruby command window
• Type 'gem install jekyll' and hit enter
• Wait until it's done

For convenience, it is strongly recommended that the content of your implementation guide be managed through source control, either Subversion (SVN) or Git.

Using the Framework

The Framework can be retrieved from SVN TODO

Initial Setup

• After downloading the Framework, test to make sure everything works by running the
• Determine the 'id' for the implementation guide. Change the name of the 'src/ig.xml' file to 'src/{id}.xml' and edit the ImplementationGuide so that its 'id' element and 'url' element both reflect the new identifier. (While you're at it, update the IG's metadata to reflect the appropriate name, author, contact, description and other information.)
  • Note that the country code specified in jurisdiction will determine which SNOMED code set is used
• Edit the ig.json file in the root folder such that the redirect to 'src-generated/ig.json' becomes 'src-generated/{ig}.json'
• Edit the 'src/config.txt' file
  • Change the guidename parameter to reference your guide's id - i.e. 'guidename={id}'
  • Fill in the appropriate copyright year
  • Specify the text you want to appear in the business 'version' element of all of your conformance resources
  • Specify the URL for the FHIR specification that is the base for your IG (e.g. http://hl7.org/fhir/dstu2 or http://hl7.org/fhir/stu3)
  • If you want to restrict what formats are included, uncomment those formats you want to exclude

Running the Process

The publication process can be run in one of two ways:

• _genonce.bat will perform pre-processing transforms and will then run the IG Publisher process to produce the website. Once published, the process will stop.
• _gencontinuous.bat will perform the pre-processing transforms and will run the IG Publisher process an initial time. Thereafter it will continuously monitor the source files for changes and will automatically re-generate the website to reflect changes (the website will be updated to reflect changes 5-15 seconds after a change to one of the source or framework files).
  • NOTE: Because of the pre-processing steps, changes the Implementation Guide instance directly in the 'src' folder will *not* be reflected in the continuous update process. To see changes made to the Implementation Guide, the continuous generation must be stopped (just close the window) and then restarted.

Content Organization

Content in this framework is organized into 2 folders: 'framework' & 'src'. Three addtional folders are generated as part of the publication process: 'src-generated', 'temp' and either 'output' or 'website'. Each of these folders will be defined below. In addition, this folder contains the following additional files:

• _cleansrc.bat: This wipes the src-generated, temp and website folders, allowing a completely clean build
• _gencontinuous.bat: This runs the pre-processing step and then launches the IG Publisher in 'watch' mode so that it will continuously update the IG publication as changes are made to the src and framework files
• _genonce.bat: This runs the pre-processing step and runs the IG Publisher once to produce a new published IG. After publishing, the process terminates
• ig.json: This is a 'redirect' IG control file that points to the actual IG control file. It is needed for the HL7 continuous integration publication tool. It also minimizes the number of files to edit when setting up a new version of the framework with a new IG with a different id.

framework folder

Most users will have no need to change or even look at content in the 'framework' folder. Customization is only needed if there's a need to change the general look and feel of the implementation guide, for example changing logos, color schemes, fonts or, for the more adventurous, changing what pages are generated to display FHIR artifacts.

This folder contains content that drives the overall publication process and manages the "look and feel" of the publication. It includes the build.xml file which drives the overall execution process, including transforms used to generate the IG configuration file, produce the list of artifacts and removes 'extra' information from the implementation guide. It launches the IG Publisher jar in either the once-only or continuous mode.

ant folder

This contains a copy of the essential files to run Apache Ant which executes the pre-process transforms.

assets folder

This includes javascript libraries, stylesheets, icons, fonts and other images used to produce the publication. These are based on the FHIR publication, however they can be adjusted or supplemented by someone with familiarity with javascript and/or css to change the look and feel of the publication. All of this content is copied directly into the final website without transformation or adjustment.

assets-source folder

This provides uncompressed views of some of the stylesheets and javascript libraries used by the publication. These files are not copied across to the publication folder, but may be used as a starting point for editing the libraries found in the 'assets' folder.

includes folder

This defines several HTML fragments that are used by the publication process:

• fragment-pagebegin.html defines the 'start' content for each HTML file, including common header information, stylesheets and java script that are used by all HTML pages. It will appear at the top of every html page in the published IG
• fragment-pageend.html defines the 'end' content for each HTML page including the closing 'body' tag as well as additional javascript content. It will appear at the bottom of every html page in the published IG.
• template-page.html defines the template for all stand-alone web pages that contain only HTML content and are not driven by a FHIR artifact.

templates folder

This folder contains all of the templates for pages that are generated for FHIR artifacts. They are referenced by the transform that generates the IG Publisher configuration file. Default templates are included for extension definitions, profiles, value sets and instances (examples, conformance/capability statement files, operation definitions, etc.). Each of these templates controls the appearance of a single HTML page that will be generated for each artifact of the specified type. Many artifacts have additional pages. For example, profiles (StructureDefinitions) will have a page for definitions, examples, mappings, XML, JSON and Turtle representations. These templates all reference the fragment-pagebegin and fragment-pageend fragments defined in the includes folder

Note: Changes to templates will NOT trigger the continuous publication process - to reflect template changes, the publication process will need to be stopped and restarted.

xslt folder

This folder contains the various transforms used to generate content for the IG. They include:

• createArtifactSummary: This processes the IG artifact and produces the artifactSummary XHTML fragment which is used to populate the artifact summary page - a list of all of the FHIR artifacts used in the implementation guide, organized according to the packages defined in the implementation guide
• fixIg: This processes the IG artifact and produces a revised IG artifact that strips out a couple of non-official extensions and adds all of the page references for the artifacts defined within the IG (so that the appropriate pages are included in the table of contents, breadcrumbs, etc.)
• igToConfig.xslt: This processes the IG artifact and produces the IG Publisher control file, exposing all of the artifacts found in the IG. If changes are made to what files are included in 'framework/templates', this transform will likely need to be edited to reflect those changes. Detailed information on the format of the IG controlfile can be found here. This transform also makes use of parameters found in the 'src/properties.txt' file.
• processPages: This processes each of the pages found in 'src/pagecontent' and src/includes and strips off the schema declaration. For the pages, it also ensures that anchors are present for each heading and that all headings include appropriate section numbers and the 'link' icon.

src folder

This is where the content that is unique to each implementation guide is contained. It includes the artifacts (StructureDefinitions, ValueSets, etc.), stand-alone page content, image files, etc. as well as the Implementation Guide file itself. The content in this folder will be actively maintained and edited as the implementation guide evolves. This is where all work on the IG occurs once the initial set-up and configuration of look and feel is complete.

Content is organized into a number of sub-folders for ease of maintenance. Be careful to avoid duplicate filenames however. Even though there may be no collision in the IG source (by keeping the files in separate folders), when the IG is published, all of the resources, images, web pages, etc. will be placed into a single output folder and may collide there

{ig}.xml file

This is the implementation guide file that defines the content of the whole implementation guide. It defines the ig and URL for the ig, provides metadata about the IG and lists all of the artifacts - profile StructureDefinitions, extension StructureDefinitions, ValueSets, CodeSystems, CapabilityStatements, examples, etc. It also identifies any pages to be included in the implementation guide and defines the hierarchy of those pages for the purpose of the table of contents and breadcrumbs.

The implementation guide file determines what will appear in the implementation guide. Artifacts and pages placed in the source folders but not referenced in the ImplementationGuide will not appear in the published specification.

Several conventions must be followed with the implementation guide for the Framework to work correctly:

• The useContext (STU2) or jurisdiction (STU3+) must be filled in with a country or state/province/territory code with the system urn:iso:std:iso:3166. This is needed to determine the appropriate SNOMED CT codes
• Resources should be organized into packages reflecting how they should be exposed in the artifact summary. Typically this will mean grouping Conformance, Profiles, Extensions, ValueSets, etc. into distinct packages. However, authors are free to organize, name and describe packages as will be most useful and intuitive to the target implementers.
• All resources should be pointed to using sourceReference, not sourceUri.
• If referencing resources defined in spreadsheets, this must be done using the 'tools-profile-spreadsheet' extension in the package where the profiles or extensions are to appear. As well, all resources, profiles, value sets and (for STU 3+) code systems defined in the spreadsheets must also referenced as explicit 'resource' elements. All such resource elements must have the 'implementationguide-spreadsheet-profile' extension on them set to true to ensure they are stripped out as part of IG pre-processing. (They are included in the source IG for use in generating the list of artifact pages and the artifact summary.)
• The pages elements must be present to allow the correct population of the table of contents, breadcrumbs and artifactSummary
• The list of pages must NOT include the pages for the artifacts - these will automatically be added under the artifactSummary page. (This means there's no concern about artifacts not being present or not listed correctly in the table of contents.)
• Therefore all pages should have a kind of "page".
• The root page should have the source name "toc.html" so that the root will be the table of contents
• The first page beneath the root should be an introductory page named "index.html" so that there will be a default page displayed when users navigate to the website.
• The list of pages must also contain a page named "artifacts.html" which will be the parent to the list of artifacts in the spec. (If you wish to change this, you can adjust the 'framework/xslt/fixIg.xslt' to place the artifacts elsewhere.)

properties.txt file

This Ant properties file helps to configure the IG control file. It contains the following properties:

• guidename must be set to the id of the Implementation Guide
• copyrightyear must be set to the string to appear in the copyright footer indicating when the specification is copyrighted
• version must be set to the desired business version for the implementation guide and all artifacts within the implementation guide
• fhirspec must be set to the target URL for the FHIR specification the IG is based on. Note that this *must* end with a '/'. E.g. "http://build.fhir.org/"
• excludexml, excludejson, excludettl if set to Yes, this will cause the published IG to not include the specified syntax representation for profiles and examples.

data folder

This folder is used to convey additional "data" files that can be referenced within HTML files. Possible uses include paths to other IG publications, contact information or other variables that may be referenced many places but where it's desirable to change them in only one place. A sample file is provided as an example of how this structure can be used.

examples folder

This is where all of the example instances for the IG are maintained. Each example should be an XML file with a schema reference to 'src-generated/schemas/fhir-single.xsd' to allow validation as the examples are edited.

Note that examples will not be published unless they are declared as artifacts in the 'src/{ig}.xml' Implementation Guide artifact.

images folder

This folder is used to contain images and other binary content for inclusion in the published specification. Any content placed here is copied directly into the published IG with no modification.

images-original folder

This folder isn't used in the publication process, but is a handy place for storing PowerPoint, Visio and other source files used to generate the files present in the 'src/images' folder.

includes folder

This folder is used to contain 'framework' information that will need to be more commonly edited by regular users. By default, there's only one file here - 'menu.xml'. This file provides control over what elements should be included in the menu file for the IG.

pagecontent folder

This folder is used to contain XML files rooted in the XHTML 'div' element. All of these files should be tied to the 'src-generated/schemas-fhir-xhtml.xsd' file to allow strict schema validation.

There are three types of files that are contained here: intro files, notes files and page files.

• intro files define content to be inserted at the top of one of the generated artifact pages. For example, at the top of the page defining a particular structure, at the top of a value set page, etc. Note that the file name MUST be the same as the name of the target generated artifact file with "-intro.xml" on the end. So something like 'somestructuredefinitionid-mapping-intro.xml' to provide an introduction to the mappings page for the specified structure definition. The name must be correct for the content to appear.
• notes files are similar to intro files except they define content that is to appear at the bottom of a generated artifact page rather than at the top.
• page files are stand-alone HTML pages.

resources folder

This folder contains the FHIR profiles, extension definitions and other non-example/non-vocabulary resources. Profiles may be expressed as XML, JSON or Excel representations. The names of spreadsheets don't matter. The names of resources must be either the id of the resource or {resourcename}-{id} (e.g. 'capabilitystatement-someid.xml').

vocabulary folder

This folder contains ValueSet (and for STU3+ CodeSystem) resources

Generated files

The publication process creates 3 directories. None of the content in these files should be edited as any changes will be overwritten. However, the content is described here to aid in debugging or in customizing the framework.

src-generated folder

This folder contains information that doesn't *need* to be managed under source control as it can either be downloaded or is generated as part of the publishing process. However, it is all information that is typically advantageous to keep under source control, both to speed subsequent publications as well as to increase the ability of the process to run when not online. Some of these files also need to be checked in if using HL7's continuous integration build environment to maintain a web-hosted version of the specification.

There are two files generated/copied directly in this folder:

• org.hl7.fhir.igpublisher.jar: This is the 'current' version of the IG publisher tool from HL7's continuous integration website. The pre-processing step will automatically grab newer versions of the tool if they exist (which can take a decent amount of time if you're on a slow network). In some cases, new versions of the tool may have bugs, so it may be useful to have this file under source control so you can revert to an older version.
• {ig}.json: This is the IG control file that is generated from the 'src/{ig}.xml' file using the 'framework/xslt/igToConfig.xslt' transform. It controls how the IG publisher jar actually runs.

pages folder

This contains files that are generated from files in the source folder and are subsequently used by the Jekyll publication process. The specific files are as follows:

• pages/jquery.js - this is a javascript library copied from 'framework/assets'. It needs to be included in two places to make the website work properly
• pages/_data/info.json - this exposes some of the information from the 'src/properties.txt' file for use in the templates and include files
• pages/_includes/artifacts.xml - this is the artifact summary 'div' element generated from the 'src/{ig}.xml' and the 'framework/xslt/createArtifactSummary.xslt'

resources folder

This contains the 'converted' implementation guide that includes the supplementary pages and has unneeded resources and extensions trimmed

txcache folder

This contains cached files used when generating the spec

• txcache/*.json - these are cached versions of value set expansions used by the implementation guide. (If the underlying codes have changed, it may be helpful to wipe the cache, though it will take longer to run the IG publication until it regenerates the cache)
• txcache/validation-*.zip - This is the set of validation information associated with the version of the specification being used. (This file will not appear if being used against the 'current' spec)

schemas folder

This folder contains the schemas used for validating the source content for the implementation guide. These must be the schemas for whatever version of the FHIR specification is being used for the implementation guide (currently limited to one of DSTU2, STU 3 2016May and STU 3 final and R4 'current'). They allow local validation of content. If using R4 'current', they must be kept up-to-date as the underlying specification evolves.

Note that only the 'key' schemas are included: fhir-single, fhir-xhtml, xml and xmldsig-core-schemas. Together, these schemas support the validation of all FHIR and XHTML content.

temp folder

The 'pages' folder contains the final output of the IGPublisher process prior to running the Jekyll process. The 'qa' folder contains a published snapshot of the generated artifacts that is used in checking hyperlinks

output or website folder

This folder contains the output of the IG Publication process. It also contains the qa.html file that shows the results of the build process. A successful build should show no broken links or other errors in the QA report.