Guidance on writing Profiles of FHIR

Current guidance to IHE profile writers when they profile FHIR. Comments and questions to JohnMoehrke@gmail.com

UPDATED for FHIR Release 4

• previous use of period '.' can NOT be used in name/id/etc. This guidance has been updated to show the use of underscore '_' in the place where previous we recommended period.
• to enable use of the FHIR IG build tools, we now put the type of conformance resource at the beginning of the filename
  • "structuredefinition-IHE_PDQm_Patient"
• FHIR Release 4 specifics
  • url to the formal spec is http://hl7.org/fhir/R4
  • version to the formal spec is "4.0.0"

checklist for when converting a FHIR STU3 to R4

From the experience with the priority set of profiles:

• Convert all mentions of STU3 to R4. This requires careful editing in word, as just changing the visible text does not change the URL under.
  • When the target FHIR specification page is a Normative page (e.g. Patient Resource is normative), then the URL used could be non-version -- e.g. http://hl7.org/fhir/Patient
• Confirm that the Resource elements are correct
  • Often element names change from STU3
  • Often elements position change from STU3
  • Often element cardinality or datatype change from STU3
  • Confirm proper use of Reference elements (at STU3 Reference datatype became complex to include url, id, and description. )
• any canonical URI should NOT be marked in word as a hyperlink, use the style for xmlName to highlight it is a canonical URI and not a clickable link
• Confirm that query parameter names and types are correct
• Check Open Issues to determine if they can now be closed
  • Often where a change to the FHIR specification was needed a gForge ticket would have been registered. Check that these are resolved and adjust
• Check any IHE Change Proposals for the profile being worked on.
  • Often times a change proposal can be resolved along with the revision
  • When a change proposal is resolved, indicate this with a Closed Item mentioning it, and update the Change Proposal tracking
  • Sometimes when a change proposal can not be fully resolved it may still be best to include the issue as an Open Issue, and update the Change Proposal tracking.
• Update any conformance resources to R4
  • Conformance resources are required starting with FHIR R4, but are informative.
  • Conformance resources are managed on GitHub

Current Guidance on 'use' of FHIR

FHIR is an emerging standard from HL7. It is currently at "Standard for Trial Use" (STU). This is an acceptable stage for IHE Profile use, but would be less stable than a Normative standard. Sometimes IHE will Profile a STU standard because it is the best fit. See Standards Selection Process

An IHE Profile that is using a STU standard must stay at "Trial Implementation" until the underlying standard progresses to Normative status. See IHE Profile Phases of Development. See Final Text Process

Because FHIR is seen as unstable by some, we agree the FMM of the used FHIR parts should be exposed prominently within the IHE Profile supplement. (see #Normative content in IHE Supplement)

The general process explained here is:

1. #Normative content in IHE Supplement
   • Start your #wiki Profiles page
2. #FHIR conformance resources with pointers back toward your #wiki Profiles page
   • #Publish your conformance resources
3. #Publish to global FHIR Registry
4. Update your #wiki Profiles page with pointers to your conformance resources
5. Get #Public Comment on your conformance resources in addition to your supplement
6. Publish #Examples of messages

Going beyond these guidance is welcome, but not yet described. See #Near Future and #Ultimate Future

Tools

The person's name I have listed is not the only one to give credit to, but is listed to help explain the linage (Provenance) of that tool.

• FHIR Chat http://chat.fhir.org (aka Zulip)
• FHIR Change Request https://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemAdd&tracker_id=677 (aka gForge)
• Grahame's FHIR Tools http://healthintersections.com.au/FhirServer/
• Grahame's Notepad++ plug-in http://healthintersections.com.au/FhirServer/
• Simplifier: https://simplifier.net/
• Forge: https://simplifier.net/Forge
• David's ClinFHIR http://clinfhir.com/
• Lloyd's Proiling tool http://wiki.hl7.org/index.php?title=Profile_Tooling
• HL7 FHIR top level tooling page http://wiki.hl7.org/index.php?title=FHIR
• Formal HL7 FHIR Registry https://registry.fhir.org/

Current Guidance on writing Profiles of FHIR

FHIR offers some new ways to publish what IHE calls a Profile. IHE must first continue to follow our governance and produce normative content in IHE Supplement format. Second priority is to leverage the new FHIR conformance Resources.

Normative content in IHE Supplement

The human readable text is what IHE publishes as the Normative content. Following the long standing Supplement format, governance, public-comment, and publication mechanisms that IHE uses for all Profiles.

• Yes this is a PDF publication mechanism, but it is what we have as approved Governance
  • For RESTful exchange, right now the recommendation is to treat this as a Transaction profile. The common http portion is very small and can be copied from PDQm. RESTful profiles will need to define various actor requirements as typical for a Transaction profile (Trigger events, Query parameters, expected actions, etc), in addition to the encoding (Profile of the FHIR Resource). Thus at this time the recommendation is to do RESTful exchanges as a normal Transaction Profile.
• Supplement should expose the FHIR Maturity Model (FMM) evaluation of the parts (e.g. Resources) used from FHIR. This helps expose to the reader of the supplement the level of maturity. A lower number means less stable FHIR specification.
  • Title page have text at 12 point (smaller than other text on the title page) "HL7® FHIR® STU 3",
  • and the range of FMM (this example is 1-5) -- "Using Resources at FMM Levels 1-5"
  • using "N" for resources that are normative
  • Note that when a resource is normative, the query parameters and extensions used are likely not. The recommendation so far is to just focus on the FMM of the resources, not each sub portion.
  • Introduction to the Supplement - should explain this FMM in more detail
  • See MHD as an example or the current supplement template here
• Volume 1 is very close to what is visualized for FHIR Implementation Guide. Defining Actors, Transactions, Options; and showing how they work together.
  • As with typical profiles, IHE will often require servers to support more capability than we require clients to use. Thus often the server actor will not need to have options, where as clients might need to have distinctions defined in options.
• Volume 2+ should be kept to minimum, but must include ALL normative requirements (SHALL) of the profile
  • When a FHIR resource is constrained in an IHE profile, the table documenting those constraints should contain the same column headings
    • FHIR Resource Element Name, IHE Constraint, Mapping, Notes
    • For rules (invariant) put a unique note number in the table, with the rules expressed in table end-notes
  • When documenting a constrained FHIR resource in an IHE profile the table should contain all elements in the resource, not just those constrained by IHE.
  • When a FHIR resource is extended in an IHE profile, the table documenting those constraints should contain the same column headings
  • ITI has a Volume 2 “Appendix Z on FHIR”. This is published now as a standalone supplement, and will be updated as needed. It is intended to be referenced by IHE FHIR-based profiles for ‘common’ stuff, eg error codes, cardinality definitions, security considerations. ITI expects the contents will grow over time, and other domains might suggest future expansions to the content by submitting a CP.
  • When a bug is found in FHIR, or where a new capability is needed in FHIR; the committee should submit a Change Request (CR) to FHIR, and include the resulting CR number as an "Open Issue" in their IHE Profile supplement. This aids with keeping track for future revisions and knowledge.
  • A link to submit a report is found at the bottom of all of HL7's FHIR pages. To do so requires a "gForge" account, which can be requested from the tracker logon page; account requests are usually approved within a day.
    • Contact John.Moehrke@gmail.com if you need help submitting tracker items, or tracking them
• Consider strongly the use of the .meta.profile element use as a method of tagging resources as compliant with your IHE Profile. This is a good constraint for IHE to add, it adds value.
  • On Query type transactions consider strongly the requirement to support the _profile query parameter. That is a server must support this query parameter, your profile will identify the canonical URI to be used. And the client of the query 'can' use this query parameter to constrain the results to the set of Resources that are complaint with your IHE Profile. This would limit the number of false-positive results, in an environment where the server is a multi-purpose FHIR server; this query parameter would likely do nothing in an environment where the FHIR server is dedicated to your IHE Profile. This works when the server support the query parameter, or is dedicated to your profile.

FHIR conformance resources

The second priority is to produce FHIR conformance resources. These are usually XML files as will be described here. The result of this is published conformance resources which are Informative at this time.

• Published on IHE site in the Implementation Material See #Publish your conformance resources below for more detail on site layout, filenames, and URL
• The profile specific wiki Profiles page should have a "FHIR Implementation Guide" section that
  • Link to the http://registry.fhir.org location where the profile specific conformance resources are published (which is likely a simplifier link)
  • Lists all of the FHIR conformance resources that are published on the IHE FTP site
  • List any examples that are on the IHE FTP site (in the domain specific directory)
  • List any TestScripts
  • List any reference implementations or other technical assistance.
  • See PDQm for example
• URIs for your conformance resources would be rooted at http://ihe.net/fhir/ while they are published in possibly different ways
  • see #Publish your conformance resources below for content type specific naming conventions
• StructureDefinition to hold constraints on each FHIR Resource
  • Cardinality constraints
  • vocabulary (valueset) constraints
  • mapping
  • see #StructureDefinition - content recommendation more below
• CapabilityStatement to show minimal conformance requirements per Actor
  • Query parameters that must be supported
  • Resources must be supported (or will be used)
  • see #CapabilityStatement - content recommendation more below
• ImplementationGuide resource -- don't confuse this with an Implementation Guide, which is human readable HTML. For the human readable we are using our PDF (by way of our wiki)
  • We are using ImplementationGuide resource only as a manifest of conformance resources we are publishing for our Profile
  • List each StructureDefinition, CapabilityStatement, and/or ValueSet
  • See #FHIR conformance Resource template below

Required if Known

In the context of IHE Profiles documented using the FHIR conformance resources, when the FHIR StructureDefintion - ElementDefinition - ".mustSupport" element is true is an indication that data element SHALL be interpreted as "Required if known". If the sending application has data for the element, it is required to populate the element with a non-empty value. If the value is not known, the element may be omitted. A receiving application may ignore the information conveyed by the element. A receiving application shall not raise an error solely due to the presence or absence of the element. This definition of Must Support is derived from IHE "Required if Known - R2 and "HL7v2 concept “Required but may be empty - RE” described in HL7v2 V28_CH02B_Conformance.doc.

Publish to global FHIR Registry

• FHIR.org has a global registry of conformance resources at https://registry.fhir.org
  • This is intended to be a thin Registry (only), where the conformance resources are published elsewhere, but discoverable on the FHIR Registry
• The registry can not pick up our conformance resources from the IHE FHIR directory, so we must publish them using Simplifier
• Simplifier is a FHIR conformance publication tool, that automatically 'registers' any updates with the global FHIR Registry.
• To use Simplifier, you will need to create you own free account. At this time we are looking at a more official and/or permanent solution.
• Once you have a login, and have logged in, you will notice that you automatically are logged in. Simplifier notices you returning, and knows who you are.
• On the very right-top of the Simplifier web site is a graphical silhouette of a person. Clicking on this gives you access to a menu. On this menu choose "Portal" to get to the project management portal.
• With a free account you can create ONE project. Care should be taken as this one project will be where you publish your resources from (Reminder we are looking to improve this officially)
• Once you create a Profile you can "upload" your conformance resources. This can NOT be done from the FTP site, you will need to upload them from your computer.
  • If you have many conformance resources to upload, putting them into a ZIP file on your computer makes it easier to batch upload.
• When updating a previously published resource, you will need to select that previous conformance resource and upload your updates. This will then be tracked as revision history. Else Simplifier will create multiple entries for each revision.
• Use the "Status' flag to deprecate mistakes.
• You might choose to use the 'Status' flag to mark your most recent as 'active'. Once marked 'active' Simplifier won't let you revise (upload an update). You can set the 'Status' flag back to draft, update, then set the new revision 'Status' flag to 'active'.

wiki Profiles page

• All active IHE Profiles should have a Profiles page, and have the FHIR icon indicated on the mention on the Profiles page
• The existence of a Profile page on the IHE wiki is very important for FHIR profiles as it will be the place where links to additional resources
  • later we might produce html directly from an automated ImplementationGuide build (see #future)
• the profile specific wiki profiles pages should be marked with the FHIR category (see the profiles template for how) so that they show up on the FHIR page
• New section on your page "FHIR Implementation Guide" should point at the FHIR conformance resources you have placed on the FTP site
  • For an example See PDQm#FHIR Implementation Guide
• Indicate your canonical URI for each resource. This is the identifier that your conformance resource is formally known as. It is not useful for a human browser access.
  • You can also provide the URL to where it is published on Simplifier. This is less formal, but more helpful to a human as is clickable to a display.

Public Comment

• Getting community input on your profile should leverage the FHIR chat system (zulip) http://chat.fhir.org
• There is an IHE stream for our use https://chat.fhir.org/#narrow/stream/ihe
  • posting outside this stream is okay. The stream is just there for our use, not as a constraint.
• You may find it useful to start a new thread for your profile

Examples

It is very useful to provide examples to your audience.

• For any Resource in your profile, there should be an example on the IHE FTP site at Implementation Material
• Any publicly available FHIR reference implementation server that you know supports your profile should also be mentioned in your Profiles wiki page "FHIR Implementation Guide" section

Experimentation

Profile editors are not forbidden from experimenting beyond this guidance. Please report your lessons learned to the IHE-FHIR workgroup

Publish your conformance resources

There is now a GIThub for managing the conformance resources. This GIThub is reflected onto the IHE ftp location, and will eventually be reflected on an http location.

Implementation Guide publication tooling

When a Profile is published using the HL7 Implementation Guide build tool, the conformance resources will be published as part of that publication.

GIThub conformance resources

location https://github.com/IHE/fhir

• This github repository is public readable.
• This github repository is for management, not formal publication
• Eventually everything here will be published on http://ihe.net/fhir
• Request to be added to the group so that you can submit your conformance resources
• Learning GIThub is not easy, we know this.. and likely will need to create training.

This is experimentation so please help improve this.

see layout below

FTP conformance resources

There are two different things we will publish in the Implementation Materials.

see layout below for conformance resources.

Please use GIThub for management if you can. If you can't, I can help reflect them into GIThub. However this will not be useful for tracking.

Example resources, messages, interactions

• These will use the layout specific to domain/profile
• for example Any examples published by ITI are published on the FTP in
  • for example PDQm examples would be found in ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/PDQm/

layout for GIThub and FTP conformance resource publication

FHIR conformance resources (StructureDefinition, CapabilityStatement, ValueSet, etc)

• These files will eventually be registered on the FHIR Registry, and that will be the primary way they will be discovered.
  • John does this registration, so let him know when you add something
• All of these, regardless of domain will need to exist in the same directory, following the FHIR URL convention.
• Note the naming conventions below for each type of conformance resource.
• The Implementation Materials has a 'fhir' directory for all of these
  • ImplementationGuide directory for all of the ImplementationGuide resource files (not html files)
  • StructureDefinition directory for all of the StructureDefinitions resource files
  • CapabilityStatement directory for all the CapabilityStatements resource files
  • ValueSet directory for all the ValueSets resource files
  • CodeSystem directory for all the CodeSystem resource files

FHIR conformance Resource templates

StructureDefinition - content recommendation

StructureDefinition is critical for developers. It is equivalent to the Volume 2 "Message Encoding", or Volume 3 content

Many tools are good at producing a StructureDefinition. I have found Forge to be good at StructureDefinition. If you use a tool, then all of this is just filling out text entries.

• name - "IHE_"+<Profile-acronym>+"_"+<Resource>+["_"+<option-name>]
  • e.g. "IHE_PDQm_Patient"
  • If you have options that change the structure, then also have StructureDefinition with them
    • e.g. "IHE_mCSD_Location_Distance"
• id - same as name
• url - follow the url pattern given
  • your filename for your StructureDefinition
    • your filename "structuredefinition-"+<name>+[".json"|".xml"])
  • your identifier (StructureDefinition.url) will be "http://ihe.net/fhir/StructureDefinition/"+name (without the prefix "structuredefinition-" or the trailing [".json"|".xml"])
    • example filename: structuredefinition-IHE_QEDm_Provenance.xml
    • example url "http://ihe.net/fhir/StructureDefinition/IHE_QEDm_Provenance
• title - full name of profile
• status - most likely "draft" for now. Once we have Final-Text we would use "active".(I think)
• date - update each time you edit and upload
• publisher - IHE (see below)
• description - simple string - describe this file and include url to wiki page. indicate that the conformance resource is Informative, the IHE profile text is Normative.
• text - same as description but can be xhtml including href
• purpose - describe in words what is constrained
• copyright - IHE (see below)
• fhirVersion - version of fhir needed
  • "4.0.0" is R4
• snapshot - not necessary, but may contain the R4 definition of the resource (I have left them empty)
• differential - your constraints (please use a tool like Forge)
• use .mustSupport to indicate Required if Known (RE or R2)

Example

This from PDQm structure definition -- NOT actually used in PDQm as PDQm didn't constrain Patient

<StructureDefinition xmlns="http://hl7.org/fhir">
   <id value="IHE_PDQm_Patient" /> 
   <text><status value="additional"/>< div xmlns="http://www.w3.org/1999/xhtml"> 
	StructureDefinition for Patient resource constraints in the IHE IT Infrastructure Technical Framework Supplement 
	<a href="http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm)">Patient Demographics Query or Mobile (PDQm)</a> 
	The IHE PDQm Profile text is Normative, this conformance resource is Informative. 

</text>

   <url value="http://ihe.net/fhir/StructureDefinition/IHE_PDQm_Patient" /> 
   <name value="IHE_PDQm_Patient" /> 
   <title value="IHE Patient Demographics Query for Mobile" /> 
 <status value="draft" />
   <date value="2017-11-18" /> 
 <publisher value="Integrating the Healthcare Enterprise (IHE)" />
 <contact>
   <name value="IHE" />
   <telecom>
     <system value="url" />
     <value value="http://ihe.net" />
   </telecom>
 </contact>
   <description value="StructureDefinition for Patient resource constraints in the IHE PDQm Profile http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm) . The IHE PDQm Profile text is Normative, this conformance resource is Informative. " /> 
   <purpose value="Lightweight RESTful query interface to a patient demographics supplier." /> 
 <copyright value="IHE http://www.ihe.net/Governance/#Intellectual_Property" />
 <fhirVersion value="4.0.0" />
 <kind value="resource" />
 <abstract value="false" />
 <type value="Patient" />
 <baseDefinition value="http://hl7.org/fhir/StructureDefinition/Patient" />
 <derivation value="constraint" />
 <differential>
   <element id="Patient.animal">
     <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-explicit-type-name">
       <valueString value="Animal" />
     </extension>
     <path value="Patient.animal" />
     <max value="0" />
   </element>
 </differential>
</StructureDefinition>

CapabilityStatement - content recommendation

CapabilityStatement is seen as informative for developers, but not critical. The CapabilityStatement has three different purposes. In this case we are defining what we WANT the Actor to support. Described in the FHIR specification as a "desired solution". It thus defines an Actor 'capability', so you will have one of these for each Actor. For simple client/server systems they are just mirrors.

Often times an IHE Profile Option will cause you to need to publish alternative CapabilityStatements.

No known tool helps at producing a CapabilityStatement. Simpifier does display them. If you use a tool, then all of this is just filling out text entries.

• name - "IHE_"+<Profile-acronym>+"_"+<actor-name>"[+"_"+<option-name>]
  • e.g. IHE_PDQm_supplier
  • if you profile has options that affect Actors, then add the option name
    • e.g. IHE_mCSD_CareServicesSelectiveConsumer_Location
• id - same as name
• url - follow the url pattern given
  • CapabilityStatement filename: "capabilitystatement-"+<name>+[".json"|".xml"]
  • your identifier (CapabilityStatement.url) will be "http://ihe.net/fhir/CapabilityStatement/"+<name>
    • e.g. "http://ihe.net/fhir/CapabilityStatement/IHE_PDQm_supplier"
• title - human readable full name of profile + Actor name
  • e.g. "IHE PDQm Supplier actor"
• date - update each time you edit and upload
• description - simple string - include url to wiki page. Explain that the IHE Profile text is Normative, and that the FHIR conformance resource is Informative.
• text - html markup - same as description
• purpose -- human readable explanation of why 'this' CapabilityStatement exists. This is more narrative than the title, but should not be too wordy. Expect reader will follow the url to the wiki page found in description
• kind == "requirements" to indicate that this is a requirements capabiltyStatement indicating desired requirements
• fhirVersion - indicate the FHIR version
  • Release 4 is "4.0.0"
• format -- indicate the mime types
  • "application/fhir+xml"
  • "application/fhir+json"
• profile - indicate your StructureDefinition
• rest - indicate your actions and query parameters required

Example

This from PDQm structure definition for the Supplier Actor

<CapabilityStatement xmlns="http://hl7.org/fhir">
 	<id value="IHE_PDQm_supplier" />  
	<text><status value="additional"/>< div xmlns="http://www.w3.org/1999/xhtml"> 
		CapabilityStatement for Consumer Actor in the IHE IT Infrastructure Technical Framework Supplement 
		<a href="http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm)">Patient Demographics Query or Mobile (PDQm)</a> 
		The IHE MHD Profile text is Normative, this conformance resource is Informative. 
	< /div></text> 
 	<url value="http://ihe.net/fhir/CapabilityStatement/IHE_PDQm_supplier" />  
 	<name value="IHE_PDQm_supplier" />  
 	<title value="IHE ITI Patient Demographics Query for Mobile (PDQm) - Supplier (server)" />  
	<status value="draft" />
	<experimental value="false" />
 	<date value="2017-11-01T09:37:21.358-05:00" />  
	<publisher value="Integrating the Healthcare Enterprise (IHE)" />
	<contact> 
		<name value="IHE"/> 
		<telecom> 
			<system value="url"/> 
			<value value="http://ihe.net"/> 
		</telecom> 
	</contact> 
   <description value="CapabilityStatement for Consumer Actor in the IHE IT Infrastructure Technical Framework Supplement IHE PDQm. See http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm). The IHE MHD Profile text is Normative, this conformance resource is Informative." />  
 	<copyright value="IHE http://www.ihe.net/Governance/#Intellectual_Property" /> 
	<kind value="requirements" />
	<fhirVersion value="4.0.0" />
	<format value="application/fhir+xml" />
	<format value="application/fhir+json" />
	<profile>
 		<reference value="http://ihe.net/fhir/StructureDefinition/IHE_PDQm_Patient" />  
	</profile>
 
	<rest>
		<mode value="server" />
		<documentation value="PDQm server provides capability to query for Patient resources matching a sub-set of the FHIR core Patient resource query parameters" />
		<security>
			<cors value="false" />
			<description value="Recommend IUA or SMART" />
		</security>
		<resource>

			<type value="Patient" />
			<profile>
				<reference value="http://ihe.net/fhir/StructureDefinition/IHE_PDQm_Patient" />
			</profile>
			<interaction>
				
			</interaction>
			<interaction>
				
			</interaction>
			<interaction>
				
			</interaction>
			<interaction>
				
			</interaction>
			<searchParam>
				<name value="_id" />
				<definition value="http://hl7.org/fhir/SearchParameter/Patient-_id" />
				<type value="token" />
				<documentation value="Logical id of this artifact" />
			</searchParam>
 ...


		</resource>
		<interaction>
			
		</interaction>
  
	</rest>
</CapabilityStatement>

Filed CR for future improvements

GF#14299: CapabilityStatement - of requirements kind - should be able to import (nesting) other CapabilityStatements of requirements kind

There is now a .import element that can import another CapabilityStatement into this CapabilityStatement. But it is restricted to importing non-overlapping capabilites. That is that this CapabillityStatement can't modify the constraints found in the CapabilityStatement that is being imported. This seems useful for Profiles of Profiles, but only where that larger concept is not adding value. This is not the intention of the CR, but is how it got resolved.

ValueSet - content recommendation

no guidance at this time. please experiment and help us with your lessons learned

Note that MHD has published the FormatCode ValueSet that might be used as an example

CodeSystem - content recommendation

no guidance at this time. please experiment and help us with your lessons learned

Note that MHD has published the IHE FormatCodes as a CodeSystem.

OperationDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

So far the lesson some have reported is that STU3 can't define an Operation.

Implementation Guide - Content recommendation

The ImplementationGuide resource is very unstable right now, it is a combination of information that the HL7 FHIR build tools use to automatically create an Implementation Guide HTML pages for human readable, and partially it is output of this build process itemizing the conformance resources specified in the Implementation Guide.

For now, IHE will use the ImplementationGuide resource only as a manifest of the conformance resources defined in the IHE Profile. There is future work to improve this, but not the current goal.

Note that when you publish your ImplementationGuide to Simplifier it will display as "The resource cannot be rendered". This is because Simplifier can only render an ImplementationGuide that is created using Simplifier, which is only available to paid users. This does not diminish the purpose we are looking for, but is rather evidence of how unstable the Implementation Guide publication process is today.

It is difficult to create an ImplementationGuide resource using tooling, as they are focused on a different goal than we are. So it is best to start with the following and just fill in the few specifics for your IHE Profile.

Update the bold lines.

• name - "IHE_"<Profile-acronym>
  • e.g. "IHE_PDQm"
• id - same as name
• url - follow the url pattern given
  • your filename for your ImplementationGuide will be "implementationguide-"+<name>+[".json"|".xml"]
  • example filename: implementationguide-IHE_PDQm.xml
  • example url: "http://ihe.net/fhir/ImplementationGuide/IHE_PDQm"
• date - update each time you edit and upload
• description - simple string -- short summary of THIS file include name of Profile and the url to wiki page. Explain Normative content is the IHE Profile text, not the conformance resource.
• text, additional - xhtml version of description.
• package.name - acronym
• package.description - longer description of your profile
• package.resource - include entry for each of your conformance resources (StructureDefinition, CapabilityStatement, ValueSet, etc)

Example

Example from PDQm

<?xml version="1.0" encoding="utf-8"?>
<ImplementationGuide xmlns="http://hl7.org/fhir">
   <id value="IHE_PDQm" />
   <text><status value="additional" />< div xmlns="http://www.w3.org/1999/xhtml">
  Implementation Guide for IHE PDQm profile.
 The <a href="http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm)">Patient Demographics Query or Mobile (PDQm)</a>
 Profile defines a lightweight RESTful interface to a patient demographics supplier leveraging technologies readily available
 to mobile applications and lightweight browser based applications.
 The IHE Profile text is Normative. This conformance resource is informative.
   </ div></text> 
   <url value="http://ihe.net/fhir/ImplementationGuide/IHE_PDQm" /> 
   <name value="IHE_PDQm" /> 
 <status value="draft" />
 <experimental value="false" />
   <date value="2017-12-18" /> 
 <publisher value="Integrating the Healthcare Enterprise (IHE)" />
 <contact>
   <name value="IHE" />
   <telecom>
     <system value="url" />
     <value value="http://ihe.net" />
   </telecom>
 </contact>
   <description value="This Implementation Guide conformance resource for IHE PDQm profile. See http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm)" />  
 <copyright value="IHE http://www.ihe.net/Governance/#Intellectual_Property" />
 <fhirVersion value="4.0.0" />
 <package>
     <name value="PDQm" /> 
     <description value="The Patient Demographics Query for Mobile (PDQm) Profile defines a lightweight RESTful interface to a patient demographics supplier leveraging technologies readily available to mobile applications and lightweight browser based applications." />  
   <resource>
     <example value="false" />
       <name value="Consumer Actor" /> 
       <description value="Initiates query for a Patient resource given query parameters" />  
       <sourceUri value="http://ihe.net/fhir/CapabilityStatement/IHE_PDQm_consumer" />  
   </resource>
   <resource>
     <example value="false" />
       <name value="Supplier Actor" /> 
       <description value="Responds to queries for Patient resource " /> 
       <sourceUri value="http://ihe.net/fhir/CapabilityStatement/IHE_PDQm_supplier" /> 
   </resource>
 </package>
</ImplementationGuide>

SearchParameter- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

MessageDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

CompartmentDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

TestScript -- content recommendation

Although TestScript is not considered by FHIR to be part of conformance resources, it is a critical Resource for documenting an ImplementationGuide.

no guidance at this time. please experiment and help us with your lessons learned

ElementDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

other conformance?

no guidance at this time. please experiment and help us with your lessons learned

Near Future

The following are some items the IHE-FHIR-wg is close to having a recommendation. These should be considered experimental, but likely to become guidance.

• Provide guidance to profile authors on how they should evaluate the need to create an IHE unique StructureDefinition.
  • This process would express the various places to look first for existing StructureDefinition that meet the new Profiling need, but are also well managed (meeting our standards selection criteria). This effort would express that one should look within the FHIR Core specification, as there are some already existing profiles there. There are likely other places to look, we should determine what this is.
  • Problem Definition: There is a proliferation of StructureDefinition (profiles) that all say the same thing. IHE should not add to this mess, IHE should be looked to as a excellence in governance.
• Similar guidance for Extensions. We should use extensions that exist from formal standards work over creating our own
• Provide guidance to get consistency on the way IHE profiles express constraints on the elements.
  • Eventually this will happen with automated publication. so this is a short term solution to fill the time before we have automated publication.
  • Today I just point at PDQm and MHD as models that might be useful. The PCC and QRPH workgroups asked that we define specific guidance on element constraints.
  • The guidance would not be mandatory. It is intended to drive consistency.
  • MHD Volume 3 is close to what people liked, however there is interest in better exposing original cardinality vs profiled.
• Provide guidance on how to link issues in the FHIR specification that prevent us from having an IHE Profile that is optimal. There are times when the specification has a gap, or constraint. We should register a Change Proposal with the FHIR specification, track that number in an open issue in your supplement, so that you can check on the status of that CP.
• Provide guidance on how to use Simplifier. This is missing today due to the voluntary status of Simplifier. However people are trying to publish IHE focused conformance resources and need help.
  • This is minimal steps needed to publish
    • You must today create a free account. You should create a free account for each IHE Profile you are working on, as the free accounts only offer one 'project'. The IHE Profile is most closely aligned with the Simplfier project concept
    • Easiest is to zip all your conformance resources, and upload the zip. Simplfier will create or update resources in your project. (critical that you use the IHE guidance so that this works well)
    • You should use Simplfier "Validate" to see if you have any syntax errors in your xml. It is better to correct these, however sometimes the error/warning may need to stay (e.g. mime-type vocabulary)
    • You should set your project to be published to the FHIR registry. This is under settings for your project
• How do we today send a public comment request on an IHE Profile on FHIR, where conformance resources are available, in a way that also directs the review to the conformance resources and asks for comments.
  • Now that conformance resources can be managed in GIThub, the public could provide comments using GIThub issues or pull-request
  • Use the wiki Profile page as the mechanism to itemize the conformance resources available for review.
  • wiki profile page is required at public comment, as that is the most friendly way to point at the conformance resources that we have today
  • Point out to the reviewer that they can review in XML, providing comment on line number in the XML
  • Point out to the reviewer that they can review using Simplifier (easier access than the IHE ftp site)
    • Simplifier does present the XML, and the JSON in a pretty format
    • Simplifier provides a presentation of the conformance, where providing comments might not be as easy to elaborate. The advantage of simplifier is that it presents the conformance resource in a more friendly presentation. We must be clear that our ballot is the conformance resource, not the presentation layer provided by simplifier.

• Publish the IHE profile on the FHIR.org (FHIR organization, not HL7) registry of Implementation Guides.
  • This likely should not be done until Public Comment version is available,
  • This should be done by the time Trial Implementation is available
  • This does NOT require any conformance (xml) resources to be available
  • This does require an authorized individual to use GITHUB to edit a JSON file
  • See https://github.com/FHIR/ig-registry
  • John added all current profiles November 22, 2018
• Use of the CapabilityStatement extension for conformance requirements - http://build.fhir.org/extension-capabilitystatement-expectation.html
  • This can be inserted at many levels of the CapabilityStatement to indicate if that element is Required, Recommended, Allowed, or Forbidden
• FHIR is working toward "Release 4", expected at the end of 2018.
  • Mechanism for updating, and thus publication of multiple conformance resource targeting the different FHIR versions (STU3, R4).

Ultimate Future

These are also potential items the IHE-FHIR-wg might further develop. These are less likely to become recommended, and a Profile author should be very cautious with these items.

• Implementation Guide publication is not mature enough to support IHE governance
  • Experience with FHIR ImplementationGuide resource and various tooling shows that it not ready for use
  • There are some IHE Profile authors (Jose) who are experimenting with the HL7 Implementation Guide publication system
  • We encourage experimentation, please engage with us so that we can improve as a whole.
  • Note that to use the HL7 Implementation Guide publication, you still MUST have done all of that which this guidance procedure asks of you. You must still have all the conformance resources, and you must go through full IHE profile authoring and governance.
• Use of GIT for publication rather than FTP
  • This might be more easy to automate with the FHIR Registry.
• Use of ClinFHIR as a tool to capture Volume 1 like material
  • See http://clinfhir.com/#
  • an article David Hay wrote on how to go about using ClinFHIR for this purpose https://fhirblog.com/2017/11/07/clinicians-on-fhir/
• Will Simplifier be usable as a IG platform?
• Will Art-Decor be a useful tool as an IG Platform?
  • There are experimentation for using this with CDA profiling
  • There are some roadmap on Art-Decor for their support of FHIR Document profiling
  • the PaLM domain used this for APSR (a CDA profile)
  • That pilot publishes the whole supplement, looking very much like a normal supplement, into HTML form on a prototype web site.
  • That pilot has methods of committing the whole thing to PDF so that existing governance can be used.
  • That team will join us in July to help us understand what they did, and where the tooling is going
• Will Trifolia workbench be a useful tool?
  • https://trifolia.lantanagroup.com/
• Will DaVInci be useful as an IG tool?
  • http://www.hl7.org/about/davinci/

Glossary

IHE and HL7 are using different words to cover similar areas.

IHE --> HL7/FHIR terms

• IHE Profile --> HL7 Implementation Guide
  • FHIR has an ImplementationGuide resource, which is a grouping resource of all conformance resources used in an Implementation Guide
  • FHIR has an Implementation Guide, which is a html publication that is laid out very similar to an IHE Profile with use-case, actors, transactions, and options
• IHE Actor --> HL7 Actor --> May be defined in a CapabilityStatement of "requirements" kind
  • CapabilityStatement is also used to describe a software system, or a network service endpoint
• IHE Transaction --> FHIR StructureDefinition -
  • specifically only the "message semantics" part of IHE volume 2, or a "content profile" in IHE Volume 3.
  • FHIR SructureDefinition can also be used to define core resources and other thngs.
• IHE Integration Statement --> HL7 CapabilityStatement of "instance" or "capability" kind
  • FHIR servers are expected to publish a CapabilityStatement (instance) that can be discovered by a client to determine if that server has the capability needed
  • The "capability" kind of CapabilityStatement is most similar to an IHE Integration Statement

HL7 -> IHE terms

• FHIR ImplementationGuide --> IHE Profile
• FHIR StructureDefinition --> IHE Message Encoding or Content Profile
• FHIR CapabilityStatement --> IHE Actor, and Query Parameters
• FHIR Profile --> likely FHIR StructureDefinitino --> IHE Message Semantics (e.g. Volume 2, message semantics; or Volume 3 content Profile)
  • See http://build.fhir.org/profiling.html