Skip to content

Getting Started

Jump to bottom
Mary Jungers edited this page Aug 19, 2026 · 23 revisions

Getting started

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

This is a collaborative process, so if you see ways to improve any part of it, please submit an issue or pull request.

This IG is self-documenting and is available on the continuous build site. 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 are defined in Volume 2. A Transaction is given a unique identifier in the form domain acronym-number. The domains assign their transaction numbers. The unique number does not need to appear anywhere in the network Transaction, but sometimes it is useful.

Transactions are made up of one 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 examples.

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 a separate page. This page is automatically created by the Implementation Guide publisher.

Reference 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. Minimally, it must 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 modifications 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.

Step by step for IG authors

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

Create a dedicated GitHub Repo

  • Ask Mary to create the Repo within https://github.com/IHE. Please provide
    • GitHub user names of those who need access (the Technical Co-chairs will be added as maintainers)
  • Repo name is {domain}.{acronym}, generally
  • Your repo will be based on the IHE supplement template
  • Your repo will be set to public
  • Your repo will have write access to the given domain committee team to manage this repo
  • Your repo will NOT be hooked into the auto-builder; but will do that as soon as you customize the identifiers (see Step 2)

Customize the critical identifiers to your actual domain and profile. Minimally:

  • sushi-config.yaml -- id, canonical, version, name, title, description, publisher, and contact

    • 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

  • ig.ini -- id path needs to represent your project id (change ihe.domain.profile)

  • input/data/features.yml -- to point at your repo rather than supplement-template

Set up Webhooks

Once you have customized the identifiers and committed them to your repo, contact Mary again

  • Mary will set up 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
  • The result is that every time you check in updates to GitHub, the Implementation Guide build will be started on the HL7 build machine
  • Note that branches will build as their own CI build
  • 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

For guidance on the FHIR Conformance resources pattern for IHE

  • RECOMMENDED to use FSH -- FHIR Shorthand
  • 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 ensure that the existing values are appropriate, or override them in your profile

Narrative are recommended to be in markdown format

Any graphic renderings should have their source archived images-source folder

  • the IG builder supports .plantuml (see example in this project)
  • PowerPoint (pptx) is considered an acceptable editable source

Header Numbering

IHE has historically managed section numbering, 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, expecting the author to follow the long-standing header numbering scheme.

  • There are times when managed header section numbering is not desirable. This might be for a product that is not going to be integrated into a volume-based technical framework, like a white paper or handbook. This might also be domain-specific, as some domains are newer and don't have legacy use of the Volume mechanism.
  • To use automatic header numbering, simply change the ig.ini file to use "ihe.fhir.template".

Reasonable page sizes

The 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 broken up by Transaction or Content definition

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.

Open Issues

It is common in IHE to have Open-Issues, especially during public comment. A good approach is to create a GitHub issue for each public comment and have your publication point to the GitHub issues. This way, a commenter can add their comment to the GitHub issue.

All other GitHub issues should be resolved and closed. Any GitHub issues other than those indicated as formal "Open-Issues" will prevent the publication.

Publication Request

Communicate with Mary when your committee has approved the IG for publication

  • A GitHub issue will be created (by you or Mary) on the publications repo.

  • What version will be published? (We are tending to use semver, and using -comment for public comments.)

  • Public Comment, Trial Implementation, or Final Text?

  • Your GitHub repo must have either master or main branch ONLY. Other branches need to be resolved either by merging or closing. All past branches should be deleted.

  • Your build must build with no errors, warnings, info, or broken links.

  • Fill out the publication-request.json would need to be updated. See HL7 instructions on publication-request.json format.

    • Important to give good details here as they are using in the publication announcements.

  • All issues, other than Open Issues must be resolved and closed.

Mary will review and improve the technical writing, including spelling, punctuation, sentence structure, etc. These changes will be committed back to your domain committee repository with a pull-request. The co-chairs of that domain committee will be requested to approve.

You must still create a wiki profiles page

See Profiles page on the IHE Wiki.

This page can be mostly the template with a changed title, short description, and a link to the formal publication. Any replication here will need to be kept in sync, so keep it minimal. Make sure you select the right categories, and add your profile to the profiles page.

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

Public Comment

Before public comment, the GitHub repo will be open to updates from any of your domain members (GitHub team). After public comment, the update github rules will require Pull-Requests, and a committee member's approval. This change reflects the governance on change management. For more on Public Comment Phase.

WORD to IG

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

  1. Follow the startup above
  2. Convert your word document to markdown (Mary 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 conversion for you (ask Mary)
  • 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 a 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 website 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 managed in the markdown as a markdown table. 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 mandatory
  • 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 a 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 advantage 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 are found elsewhere
  1. The chat stream will give you the URL to where the build can be viewed. This will be maintained for a few weeks, so it is useful for committee review, but it 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. See ITI PDQm and ITI MHD

External guidance to authors

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

Clone this wiki locally