Difference between revisions of "IHE FHIR Profile Publication/Creating new Profiles"

From IHE Wiki
Jump to navigation Jump to search
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Creating and publishing an ImplementationGuide =
+
== Getting Started – Using the default content ==
<blockquote style="
 
background-color: lightblue;
 
border: solid thin grey;
 
padding-top: 10px;
 
padding-right: 30px;
 
padding-bottom: 10px;
 
padding-left: 30px;">
 
This short documentation is meant to help editors or designers get started with FHIR Profile Publishing, and will progress towards an official IHE FHIR Profile Publishing mechanism.
 
'''This is a wiki page - it is intended to change rapidly.'''
 
  
This page contains MUCH MORE details than will typically be needed. The IHE and HL7 communities, the IHE FHIR Workgroup and IHE Documentation Workgroup are looking at providing solutions so that editors do not need to understand all these details but can focus on editing content, leaving most of complexity behind. These details are here while IHE works towards those solutions.
+
These are the steps to create another implementation guide from the base profile. To provide an example, we describe how to change the profile “base” to a new profile called “mmm”. Of course you can use an name as long as the file names match the references.
</blockquote>
 
  
 +
# Copying / renaming implementation guide
 +
# Adding pages
 +
# Adding resources
  
 +
The details:
  
== Concepts ==
 
  
To publish a profile, we need:
+
== Copying / renaming implementation guide ==
  
# The definition or source of the profile – what it is, what is the content.
+
=== Rename (or copy) the “base” folder to “mmm” ===
# The ImplementationGuide Publisher or IG Publisher, maintained by HL7®.
 
# The IHE IG template, which tells the IG Publisher how to generate and render the content. With this template, IHE defines:
 
## A standard look-and-feel
 
## Mandatory content
 
## Naming conventions
 
# A toolset to enable or accelerate preparing or editing the content
 
  
To enable the IHE editor community, IHE will also provide:
+
=== Rename the file “base.xml” to “mmm.xml”. Compared to the “base” profile, we end up with this: ===
  
* '''Publication space or platform''' – currently http://ihe.net/fhir/baseprofile
 
* '''Ownership and governance''' – starting with a folder structure for different profiles
 
* '''Collaboration and version management''' for the profile content – e.g. github or bitbucket. This will require defining branching policy, etc.
 
  
== Source of the profile ==
+
[[File:media/image1.png|222x164px]]
  
The profile is defined by:
+
=== Edit the mmm.xml and change the id, url, and optionally name as appropriate: ===
  
* The '''FHIR® resources''' that will contain the computable part of the specification, and will be published in a standard, consistent way across all profiles:
+
Original:
** '''ImplementationGuide''' – the “binding” resource that points to the remainder of the content
 
** '''CapabilityStatement''' – A computable definition of the features of an IHE actor
 
** '''StructureDefinition''' – Representing a set of constraints on specific FHIR® resources.
 
** '''ValueSet''' – an official value set or glossary.
 
** '''PlanDefinition''' – A formal definition of a workflow profile – including steps and constraints.
 
** '''ExampleScenario''' – An implementation of the profile in one concrete case with real values.
 
** '''Any resource''' can be used as part of an example
 
** '''TestScenario''' – test content that implementers may use in a first validation of their implementations.
 
* Rich text '''pages''', for any other content.
 
  
We describe the basics of manual editing the content, but we aim at editing solutions. Existing solutions for editing the resources:
+
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-16&quot;?&gt;
 +
&lt;ImplementationGuide xmlns=&quot;http://hl7.org/fhir&quot;&gt;
 +
  &lt;id value=&quot;base&quot; /&gt;
 +
   &lt;url value=&quot;http://ihe.net/fhir/base&quot; /&gt;
 +
    &lt;name value=&quot;ImplementationGuide5&quot; /&gt;
 +
    &lt;status value=&quot;draft&quot; /&gt;
  
* FHIR® Toolkit.
+
...
* Firely Forge®
 
  
=== ImplementationGuide  ===
+
Updated:
  
An ImplementationGuide resource has the following structure:
+
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-16&quot;?&gt;
 +
&lt;ImplementationGuide xmlns=&quot;http://hl7.org/fhir&quot;&gt;
 +
  &lt;id value=&quot;'''mmm'''&quot; /&gt;
 +
  &lt;url value=&quot;http://ihe.net/fhir/mmm&quot; /&gt;
 +
  &lt;name value=&quot;'''Mobile Medication Management'''&quot; /&gt;
 +
  &lt;status value=&quot;draft&quot; /&gt;
  
* '''ImplementationGuide''' – definitions of the ImplementationGuide itself, such as title, authors,...
+
...
** '''Global''' (Not supported) – a pointer to global content reused in this profile
 
** '''DependsOn''' (Not supported) – a pointer to a profile that this profile builds upon
 
** '''Definition''' – a placeholder for the profile-specific content
 
*** '''Package'''(s) – a Package is a “grouping” element. For now, see it as “tag”.
 
*** '''Resource'''(s) – the FHIR Resources that are defined in this profile.
 
*** '''Page''' – The index page of the profile (the Table of Contents)
 
**** '''Page'''(s) – A profile will have a tree-like structure of pages, nested under each other.
 
  
The attributes in the ImplementationGuide resource are:
+
At this moment you can rebuild to make sure things still work ok.
  
* '''ImplementationGuide'''
+
== Adding pages ==
** id: Mandatory, should be the IHE profile acronym
 
** name: A human-readable name
 
** url: the authoritative url where this profile is going to be accessible.
 
** status: the status (draft, active, retired, unknown)
 
** experimental: true or false. For now, true.
 
** date - the date of the last official editing of the profile.
 
** jurisdiction - For now, due to template constraints, it must be US. This will change.
 
** packageId - npm package name in the form ihe.fhir.dmn.prfl, wher dmn is the domain acronym and prfl is the profile acronym. Example: '''ihe.fhir.pharm.mma'''
 
** '''Definition'''
 
*** Package
 
*** Resource - The resource file name must be:
 
*** Template
 
  
The implementationGuide shall be saved in the root folder for the ig.
+
You can add pages under the top page, which is the Table of Contents.
  
Example: if the profile is called “base”, the root folder should be called “base” and in it there shall be a file “base.xml”.
+
It is recommended to keep page named “index” – you can change the existing index.xml page if you want.
  
=== Pages ===
+
=== Add the x(ht)ml file in the content\pagecontent folder, for example a “welcome” page. ===
  
Pages contain free content that users can add. Note that there will be fixed, mandatory pages for all IHE profiles. They will be provided with the base profile and IHE template.
+
<blockquote>[[File:media/image2.png|237x181px]]
 +
</blockquote>
 +
=== Add an entry in the implementationGuide (mmm.xml) to point to the file you added. ===
  
A page will consist of:
 
  
* an html file per page (saved with .xml extension). All pages will be saved in the folder '''&lt;root&gt;/content/pagecontent'''
+
&lt;page&gt;
* the images or other media in the page will be saved in the folder '''&lt;root&gt;/content/images'''
+
  &lt;nameUrl value=&quot;toc.html&quot; /&gt;
 +
    &lt;title value=&quot;Table of Contents&quot; /&gt;
 +
    &lt;generation value=&quot;html&quot; /&gt;
 +
  &lt;page&gt;
 +
    &lt;nameUrl value=&quot;index.html&quot; /&gt;
 +
    &lt;title value=&quot;Main Page&quot; /&gt;
 +
     &lt;generation value=&quot;html&quot; /&gt;
 +
   &lt;/page&gt;
 +
  &lt;page&gt;
 +
    &lt;nameUrl value=&quot;welcome.html&quot; /&gt;
 +
     &lt;title value=&quot;Welcome Page&quot; /&gt;
 +
   &lt;generation value=&quot;html&quot; /&gt;
 +
   &lt;/page&gt;
 +
  &lt;page&gt;
 +
    &lt;nameUrl value=&quot;artifacts.html&quot; /&gt;
 +
    &lt;title value=&quot;Artifacts&quot; /&gt;
 +
    &lt;generation value=&quot;html&quot; /&gt;
 +
  &lt;/page&gt;
 +
&lt;/page&gt;
  
e.g. if our “base” profile has 2 pages (toc and index) and index has one picture saved as “image1.jpeg”, the files in our “base” profile shall be:
+
== Adding resources ==
  
[[File:folderstruct.png|182x218px]]
+
place the resource as an XML file in the content\resources folder.  
  
=== CapabilityStatement  ===
+
The file must be named according to the convention
  
=== StructureDefinition  ===
+
capabilitystatement-ihe-acr-xxxxxxxx.xml
 +
 
 +
where acr is the profile acronym and xxxxxxxxx is the object - the transaction, the actor, etc.
 +
 
 +
<blockquote>[[File:media/image3.png|402x201px]]
 +
</blockquote>
  
=== ValueSet  ===
+
=== place a reference in the implementation guide file (mmm.xml). ===
  
=== PlanDefinition  ===
+
Just add a section like this. Make sure you point to a package that exists in the mmm.xml file.
  
=== ExampleScenario ===
+
&lt;resource&gt;
 +
  &lt;reference&gt;
 +
  &lt;reference value=&quot;CapabilityStatement/ihe-mmm-requestplacer&quot; /&gt;
 +
  &lt;/reference&gt;
 +
  &lt;name value=&quot;IHE MMM Request placer&quot; /&gt;
 +
  &lt;description value=&quot;Request Placer Specifications&quot; /&gt;
 +
  &lt;package value=&quot;Package1&quot; /&gt;
 +
  &lt;/resource&gt;
  
=== Any resource  ===
+
The resulting file:
  
=== TestScenario ===
+
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-16&quot;?&gt;
 +
&lt;ImplementationGuide xmlns=&quot;http://hl7.org/fhir&quot;&gt;
 +
      &lt;id value=&quot;base&quot; /&gt;
 +
     &lt;url value=&quot;http://ihe.net/fhir/base&quot; /&gt;
 +
     &lt;name value=&quot;Base Profile&quot; /&gt;
 +
    &lt;version value=&quot;0.2.1&quot; /&gt;
 +
    &lt;status value=&quot;draft&quot; /&gt;
 +
    &lt;experimental value=&quot;false&quot; /&gt;
 +
    &lt;date value=&quot;2018-01-01T00:00:00.000+02:00&quot; /&gt;
 +
     &lt;jurisdiction&gt;
 +
        &lt;coding&gt;
 +
          &lt;system value=&quot;urn:iso:std:iso:3166&quot; /&gt;
 +
          &lt;code value=&quot;US&quot; /&gt;
 +
        &lt;/coding&gt;
 +
    &lt;/jurisdiction&gt;
 +
    &lt;packageId value=&quot;ihe.fhir.base&quot; /&gt;
 +
    &lt;license value=&quot;Apache-2.0&quot; /&gt;
 +
    &lt;fhirVersion value=&quot;3.5.0&quot; /&gt;
 +
    &lt;definition&gt;
 +
        &lt;package&gt;
 +
          &lt;name value=&quot;Package1&quot; /&gt;
 +
          &lt;description value=&quot;Package&quot; /&gt;
 +
        &lt;/package&gt;
 +
        &lt;resource&gt;
 +
          &lt;reference&gt;
 +
              &lt;reference value=&quot;CapabilityStatement/ihe-base-requestplacer&quot; /&gt;
 +
          &lt;/reference&gt;
 +
          &lt;name value=&quot;ihe-base-requestplacer&quot; /&gt;
 +
          &lt;description value=&quot;Request Placer Specifications&quot; /&gt;
 +
          &lt;package value=&quot;Package1&quot; /&gt;
 +
        &lt;/resource&gt;
 +
        &lt;resource&gt;
 +
          &lt;reference&gt;
 +
              &lt;reference value=&quot;StructureDefinition/medication-request&quot; /&gt;
 +
          &lt;/reference&gt;
 +
          &lt;name value=&quot;Medication Request&quot; /&gt;
 +
          &lt;description value=&quot;Medication Request Specifications&quot; /&gt;
 +
          &lt;exampleBoolean value=&quot;false&quot; /&gt;
 +
          &lt;package value=&quot;Package1&quot; /&gt;
 +
        &lt;/resource&gt;
 +
        &lt;page&gt;
 +
          &lt;nameUrl value=&quot;toc.html&quot; /&gt;
 +
          &lt;title value=&quot;Table of Contents&quot; /&gt;
 +
          &lt;generation value=&quot;html&quot; /&gt;
 +
          &lt;page&gt;
 +
              &lt;nameUrl value=&quot;index.html&quot; /&gt;
 +
              &lt;title value=&quot;Main Page&quot; /&gt;
 +
              &lt;generation value=&quot;html&quot; /&gt;
 +
          &lt;/page&gt;
 +
          &lt;page&gt;
 +
              &lt;nameUrl value=&quot;artifacts.html&quot; /&gt;
 +
              &lt;title value=&quot;Artifacts&quot; /&gt;
 +
              &lt;generation value=&quot;html&quot; /&gt;
 +
          &lt;/page&gt;
 +
        &lt;/page&gt;
 +
    &lt;/definition&gt;
 +
&lt;/ImplementationGuide&gt;

Latest revision as of 13:26, 12 December 2018

Getting Started – Using the default content

These are the steps to create another implementation guide from the base profile. To provide an example, we describe how to change the profile “base” to a new profile called “mmm”. Of course you can use an name as long as the file names match the references.

  1. Copying / renaming implementation guide
  2. Adding pages
  3. Adding resources

The details:


Copying / renaming implementation guide

Rename (or copy) the “base” folder to “mmm”

Rename the file “base.xml” to “mmm.xml”. Compared to the “base” profile, we end up with this:

222x164px

Edit the mmm.xml and change the id, url, and optionally name as appropriate:

Original:

<?xml version="1.0" encoding="utf-16"?>
<ImplementationGuide xmlns="http://hl7.org/fhir%22>
  <id value="base" />
  <url value="http://ihe.net/fhir/base%22 />
   <name value="ImplementationGuide5" />
   <status value="draft" />

...

Updated:

<?xml version="1.0" encoding="utf-16"?>
<ImplementationGuide xmlns="http://hl7.org/fhir%22>
  <id value="mmm" />
  <url value="http://ihe.net/fhir/mmm%22 />
  <name value="Mobile Medication Management" />
  <status value="draft" />

...

At this moment you can rebuild to make sure things still work ok.

Adding pages

You can add pages under the top page, which is the Table of Contents.

It is recommended to keep page named “index” – you can change the existing index.xml page if you want.

Add the x(ht)ml file in the content\pagecontent folder, for example a “welcome” page.

237x181px

Add an entry in the implementationGuide (mmm.xml) to point to the file you added.

<page>
  <nameUrl value="toc.html" />
    <title value="Table of Contents" />
    <generation value="html" />
  <page>
    <nameUrl value="index.html" />
    <title value="Main Page" />
    <generation value="html" />
  </page>
  <page>
    <nameUrl value="welcome.html" />
    <title value="Welcome Page" />
   <generation value="html" />
  </page>
  <page>
    <nameUrl value="artifacts.html" />
    <title value="Artifacts" />
    <generation value="html" />
  </page>
</page>

Adding resources

place the resource as an XML file in the content\resources folder.

The file must be named according to the convention

capabilitystatement-ihe-acr-xxxxxxxx.xml

where acr is the profile acronym and xxxxxxxxx is the object - the transaction, the actor, etc.

402x201px

place a reference in the implementation guide file (mmm.xml).

Just add a section like this. Make sure you point to a package that exists in the mmm.xml file.

<resource>
  <reference>
  <reference value="CapabilityStatement/ihe-mmm-requestplacer" />
  </reference>
  <name value="IHE MMM Request placer" />
  <description value="Request Placer Specifications" />
  <package value="Package1" />
</resource>

The resulting file:

<?xml version="1.0" encoding="utf-16"?>
<ImplementationGuide xmlns="http://hl7.org/fhir%22>
    <id value="base" />
    <url value="http://ihe.net/fhir/base%22 />
    <name value="Base Profile" />
    <version value="0.2.1" />
    <status value="draft" />
    <experimental value="false" />
    <date value="2018-01-01T00:00:00.000+02:00" />
    <jurisdiction>
       <coding>
          <system value="urn:iso:std:iso:3166%22 />
          <code value="US" />
       </coding>
   </jurisdiction>
   <packageId value="ihe.fhir.base" />
   <license value="Apache-2.0" />
   <fhirVersion value="3.5.0" />
   <definition>
       <package>
          <name value="Package1" />
          <description value="Package" />
       </package>
       <resource>
          <reference>
              <reference value="CapabilityStatement/ihe-base-requestplacer" />
          </reference>
          <name value="ihe-base-requestplacer" />
          <description value="Request Placer Specifications" />
          <package value="Package1" />
       </resource>
       <resource>
          <reference>
              <reference value="StructureDefinition/medication-request" />
          </reference>
          <name value="Medication Request" />
          <description value="Medication Request Specifications" />
          <exampleBoolean value="false" />
          <package value="Package1" />
       </resource>
       <page>
          <nameUrl value="toc.html" />
          <title value="Table of Contents" />
          <generation value="html" />
          <page>
              <nameUrl value="index.html" />
              <title value="Main Page" />
              <generation value="html" />
          </page>
          <page>
              <nameUrl value="artifacts.html" />
              <title value="Artifacts" />
              <generation value="html" />
          </page>
       </page>
   </definition>
</ImplementationGuide>