Skip to content

Getting Started

Jump to bottom
John Moehrke edited this page Feb 22, 2023 · 15 revisions

Getting Started

This article explains how to use the IG builder to publish IHE Profiles (supplements). Organization of this article:

  • General Overall Organization that simply explains IHE supplement and technical framework layout and how those concepts map into an IG published implementation guide.
  • Step by step instructions to authors.
  • External references for authors.
  • There is an open help meeting every other Monday at 10am central. The invite is sent to all committees, so you should have it. If not, let John know.

This is a collaborative process, so if you see ways to make any part of the process better, please submit an issue, pull-request, or email [email protected].

This IG is self documenting and is available on the continuous build site as http://build.fhir.org/ig/IHE/supplement-template/branches/master/index.html. Note that a copy of the normal word DOCX supplement template is available here as suppl_template.md.

Overall organization

Volume 1: Use-Case Analysis

This section contains the Use-Case Analysis and breakdown into Actors, Transactions, Options, and Groupings

Volume 2: Transactions

When a Supplement defines transactions they will be defined in Volume 2. A Transaction is given a unique identifier with the form '-'. Where this is assigned by the domain committee. The unique number does not need to appear anywhere in the network transaction, but sometimes it is useful.

Transactions are made up of 1 or more messages. Each Message is made up of a Trigger, Message Encoding, and Expected Actions.

The Transaction might define vocabulary, security-considerations, or other transaction specific artifacts.

For FHIR, the Message Encoding is usually defined by one or more StructureDefinition profiles

Volume 3: Content

When a Supplement defines transaction independent content it will be defined in Volume 3. For example CDA Documents, FHIR Documents, XDW Workflows, etc.

The content binding to transactions might require definitions of things like Document Sharing Metadata.

The XDS Metadata model and encoding into eb-Reg and into FHIR are an example.

Volume 4: National Extensions

When a region defines constraints for use within that region they will be defined in Volume 4. Volume 4 tends to be legacy, as a nested Implementation Guide fulfills this use-case in a more general way. Thus Volume 4 is discouraged with preference to nested Implementation Guides.

Artifacts

When computable constraint definitions (e.g., StructureDefinition, CapabilityStatement, etc) are defined, they will appear in Volume 5. This Volume is automatically created by the Implementation Guide publisher.

References to these artifacts is encouraged in the other portions of the Implementation Guide.

Other

Test Plan

The Test Plan should be defined for all Implementation Guides. It must minimally define the overall intended plan for testing. This plan may define scenarios using ExampleScenario or Cucumber. This plan should be broken down into unit tests (usually leveraging StructureDefinition validation), and Integration tests (which test a set of steps among multiple actors).

Changes to Other IHE Specifications

This section indicates modificationns to other IHE specifications or to the General Introduction Appendices (e.g., Actors and/or Transactions).

Download and Analysis

This section provides information on how to download the entire IG.

Mapping structure to IG

TODO fill in mapping of the above concepts to the supplement template recommended menu and file structure

Step by step

This repository holds the IHE supplement template equivilant for use with the IG publisher.

  1. Create a dedicated GitHub Repo
  • Ask John to create the Repo within https://github.com/IHE
  • John will make your repo based on this template
  • John will set this public and assign the domain committee team to manage this repo
  • John will NOT hook that version into the auto-builder; but will do that as soon as you customize the identifiers (See Step 2)
  • The result is that every time you checkin updates to github the Implementation Guide build will be started on the hl7 build machine.
  • To track the success of these builds you must follow the FHIR chat committers-notification stream https://chat.fhir.org/#narrow/stream/179297-committers.2Fnotification
  1. customize the critical identifiers to your actual domain and profile. Minimally:
  • sushi-config.yaml -- id, canonical, version, name, title, description, publisher, and contact
  • ig.ini -- id path needs to represent your project id (change ihe.domain.profile)
  • canonical -- must start with https://profiles.ihe.net --- yes it must be https, and yes it must be profiles.ihe.net. After that the domain folder and your profile folder
  • should also do these
    • input/data/features.yml -- to point at your repo rather than supplement-template
  • if you have any doubt, contact John
  1. Once you have customized the identifiers and committed that to your repo. Contact John again
  • John will setup the webhook to auto-build when you push updates with payload URL = https://us-central1-fhir-org-starter-project.cloudfunctions.net/ig-commit-trigger, and json content-type encoding.
  1. For guidance on the FHIR Conformance resources pattern for IHE
  • somewhat dated advice see https://wiki.ihe.net/index.php/Guidance_on_writing_Profiles_of_FHIR
  • RECOMMEND to use FSH. FSH might be easier but has limitations
  • much of the guidance is built into this supplement, so will be there to start with.
  • when a constraint is applied to an element, review the short, definition, and comment to assure that the existing values are appropriate, or override them in your profile.
  1. narrative are recommended to be in markdown format but may be in xhtml
  • markdown may be easier for authors
  • see below for details on how to convert a WORD based supplement
  1. any graphic renderings should have their source archived images-source folder in the github repository too.
  • the IG builder supports .plantuml (see example in this project)
  1. Header Numbering -- IHE has historically managed the numbering of sections, as all sections would eventually fit within a Volume, and thus need pre-coordinated header numbering. The default for this supplement-template is to use a template that suppresses automatic section numbering, thus expecting the author to follow the long standing header numbering process.
  • There are times when managed header section numbering is not desireable. This might be for a product that is not going to be integrated into a Volume based technical framework, like a whitepaper or handbook. This might also be Domain specific, as some domains are newer and don't have a legacy of use of the Volume mechanism.
  • To use automatic header numbering, simply change the ig.ini file to use "ihe.fhir.template"
  1. size of any one html (markdown) is up to the author to control. Too big is considered by some to be a bad thing, but the definition of too big is not clear.
  • Volume-1 -- The supplement-template starts with all of Volume-1 in one markdown file. This has seemed to be the best-practice. Breaking up into many is up to the author.
  • Volume-2, and Volume-3 -- These tend to be best to break up by Transaction or Content definition
  1. Keep an eye on your build error/warning/info/broken numbers. These need to be at zero for publications.
  • the details can be found in the publication output, in the footer is a "QA Report" link.
  • Errors must be resolved
  • Warnings and Info should be resolved. They are indications of quality concerns.
  • Warnings and Info can be suppressed using the input/ignoreWarnings.txt. suppressing should only be done once you have confirmed that you intend that Warning or Info.
  1. When approaching a publication request, the publication-request.json would need to be updated. See HL7 instructions on publication-request.json format

If you have questions, need help with modeling, or can improve these instructions. Please reach out.

WORD to IG

If you have an IHE Profile in supplement form, use the following guidance to convert it to a IG.

  1. Follow the startup above
  2. convert your word document to markdown (John would be happy to do the conversion)
  • you should find a directory "narrative-source" in your new repo (if not, see step 1)
  • copy your supplement (docx) into the narrative-source directory (must be docx format. If not, then use word to covert to docx)
  • use pandoc to export to markdown http://pandoc.org
  • you will need to install pandoc, or find someone who can do the one-time coversion for you (ask John)
  • given a supplement filename of "your-supplement.docx"
  • pandoc -t gfm --extract-media . -o your-supplement.md your-supplement.docx
  • this your-supplement.md file will now be easy to copy-paste into the files needed for the IG build
  1. The converted markdown will extract out some diagrams, but likely not all of them
  • often we have used microsoft-draw or microsoft-powerpoint in the past. Edit the docx with word, find the diagram. Select the whole diagram and copy it. Then open powerpoint, select no style, select an empty slide as the only slide in the deck, paste the diagram into powerpoint. Save the powerpoint as powerpoint for future needs to edit in the images-source directory, naming it something useful. Export from word the PNG format, saving this in the images directory.
  1. For UML style diagrams it might be best to recreate the diagram using UML. the web site plantuml will allow you to create a uml script, and export as SVG or PNG. Save the UML script in the images-source. You will find some examples present, often editing these is the quickest. At this time there is not a tool in the IG build that will convert UML into PNG.
  1. Tables, should be manage in the markdown as a markdown tabe. This looks more like a table in the edited form. xhtml tables will work too, but may be harder to maintain.
  • Some tables will be converted to markdown tables when you export your docx to markdown, some might not. Often when the table is not exported in markdown tables, but rather xhtml, it is because the table you have in your word document has multiple header lines, merged cells, or other style. Often you can edit the word docx to simplify these and use pandoc again until you get all tables as markdown.
  • Having all tables as markdown is not manditory
  • markdown tables will not appear with the table grid showing by default. Add the following as a line of text on the text line following your table "{: .grid }" This works for IG build as the content is highly processed by the build tools.
  1. The supplement-template that you copied has placeholders and menu layout consistent with the IHE supplement template. You should be able to use a text editor and copy-paste the narrative from your supplement export markdown into these placeholder files. Add files as needed, for example if your supplement had an extra section, appendix, etc.
  2. conformance resources (capabilityStatement, StructureDefinition, ValueSet, etc) and examples can be authored in xml or FSH format.
  • to use the FSH format, one does need to change the layout of the directory structure. Instructions for how to do this can be found elsewhere
  1. build - you can install the IG build tools and do the build locally. This has the advantge of being a little quicker, but not much. If you can't install tools on your machine this is okay. When you push in github to the IHE repository, it will trigger a build in the cloud. You can see the results, error log, qa report, etc displayed in the zulip chat stream dedicated to the cloud build.
  1. At some point you need to commit your changes to your repository. First make sure you add any files that you created, including the source files. The source files are not important for the build, but they are important for provenance (document) and future editability (images)
  • instructions on how to use GitHub found elsewhere
  1. The chat stream will give you the URL to where the build can be viewed. This wil be maintained for a few weeks, so is useful for committee review, but can't be used for long term review or publication. That is done elsewhere with a process controlled by Mary

good existing IHE profiles

best practices tend to build over time, and not all of them get ported back to this supplement. So keep an eye on your peers publications.

external guidance to authors

HL7 also has guidance and a sample-ig that may be useful for readers.

Clone this wiki locally