Vanna Health IG
0.0.2 - ci-build

Vanna Health IG - Local Development build (v0.0.2) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Developers

Developer reference for working with this IG.

  • Please see fhir/README.md for instructions for using this repo
  • Debugging: The Docker container logs will contain the errors, warnings, and stacktraces for problems encountered while generating the IG

The intention is to document every piece of FHIR that is used at Vanna. For new fields, add the necessary FSH information and the publishing process will add the fields to the documentation. For existing fields, please mark them as “must support” (MS) and add a short description (^short) of where they are used.

Example:

* name MS
* name ^short = "Both official name and nicknames"

FHIR Shorthand (FSH)

Writing FSH can be tedious as the language is terse and esoteric. So far, the most successful approach has been to utilize the Language Reference in combination with the reverse engineering the SDOH CC IG source code.

The best training resource found to date is Deep Dive with FSH.

Other helpful links:

Creating FSH Examples

Sometimes the easiest path is to start with a json resource and convert it to FSH before editing it. To do so:

  1. Get a json blob from MedPlum’s UI, a FHIR example, or where ever and save it to a file
  2. Use GoFSH to generate FSH example
    1. npx gofsh <fhir-example.json>
  3. Copy it to the IG. Make sure to include supporting docs like aliases.

Editing the Implementation Guide

Creating an Implementation Guide is frustrating due to how poorly documented the process and technology are. Writing an IG uses a combination of tools that you may need to familiarize yourself with if you plan on altering the IG, as opposed to simply editing content (.md, .fsh). Understanding the IG publisher, SUSHI, and Jekyll is recommended.

The “official docs” are bad. The only half decent resources found so far:

Documentation Options

There are a few options for adding content to the IG:

  • Add markdown files to pagecontent and link to them in the menu bar or include them with jekyll
  • Add documentation directly to a generated page by creating files that adhere to the following naming convention: [ArtifactType]-[id]-[suffix].md where:
    • ArtifactType is the artifact type such as StructureDefinition, ValueSet, etc.
    • id is the resource name from the FSH declaration like Profile: name
    • suffix is either intro for introduction before the table or notes for notes for after
    • Example: StructureDefinition-VannaPatient-notes.md will appear after the table on the Patient resource
  • Add a Description: to the top-level of the FSH resource which will appear above the Formal Views table

To add to the menu bar, edit the menu entry in sushi-config.yaml.

Directory Structure

Specifics on the IG directory structure:

Styling

A custom Jekyll template (ig/local-template) is used to customize the appearance of the IG. The ig.ini file is points the IG Publisher at the custom template, which is merged with the base template fhir.base.template#current. Instructions to set this up and to edit the colors are at Guidance for FHIR IG Creation > Customization.

Honestly, this is a time sink. Just don't if you don't have too. There's some evil dark magic deep in the IG Publisher jar that's doing god knows what. Take this dragon here - sure it's just a css class - but it's just tip of the magic, undocumented iceberg. The styling is good enough.

Examples

Often the only method of implementing a given pattern is to find an example in the wild and to copy the pattern from the source repo. Below are a few IGs that have been referenced to construct this one.

Sample IGs: