This page describes a process based on this page to publish a FHIR Implementation Guide that is not (necessarily) owned by HL7.
The release publication step prepares the content for being served on a website - the structure of the website can be either
- (webroot)/[org]/[code] - for example https://profiles.ihe.net/ITI/MHD
- (webroot)/[code] - for example https://fhir.openmrs.org/core
- (webroot)/[realm]/[code] (for HL7 IGs) for example http://hl7.org/fhir/uv/sdc/
The values of [org] and [code] are obtained from the package id. See publication patterns below.
The process works by locally building the IG, adding it to a (local) copy of the website, so that the updated website can be uploaded.
Summary:
- Setup your web folder locally and the necessary dependencies
- get or create web folder
- clone ig-registry and fhir-ig-history-template
- define or get use your institution's templates for the history page
- Ensure the IG is well configured and add the publication request
- Run the publication process
- Verify and upload the updated web folder
1. Setup the working folder and necessary dependencies
- Create a working folder for your implementation guide publication (all releases of the IG will be in added to that folder, and the folder can be updated to the web server).
- e.g.
Publication
- e.g.
- Download the publisher jar to this folder and `cd` into it
Clone the history template to a folder called fhir-ig-history-template in this folder (or add it as a submodule if you want)
git clone https://github.com/HL7/fhir-ig-history-template.git ig-history
You can use other history templates:
Add the registry (clone or submodule) submodule to a folder called ig-registry
git clone https://github.com/FHIR/ig-registry.git ig-registry
In the working folder, create a folder that will be your web root (typically the folder that you will publish to the web)
example: md webroot
Create a publish-setup.json in the webroot folder, like this:
{ "website" : { "style" : "fhir.layout", "url" : "http://hl7.org/fhir", "server" : "asp-new", "org" : "HL7, Inc", "search-template" : "searchform.template.html", "index-template" : "index.template" }, "feeds" : { "package" : "package-feed.xml", "publication" : "publication-feed.xml" }, "ig-dirs" : [ "smart-app-launch", "us", "uv" ], "indexes" : { "us" : { "title" : "HL7 US Realm Implementation Guides", "source" : "us/index.html" }, "uv" : { "title" : "HL7 International Realm Implementation Guides", "source" : "uv/index.html" } } }
If your IG is not issued by HL7 or FHIR, you may have an additional section for the layout. For example the OpenMRS website would be
"layout":{"id":"foo.fee.[category].[code]","canonical":"http://any.site.org/[category]/[code]"}
}
Where
foo.fee.[category].[code]
is the package id,
and
http://any.site.org/[category]/[code]
is the publication url format.
{category} is optional
{code} is mandatory
Note: the url must be same as the IG's canonical URL
- Create history template files in the templates folder - To Do
2. Setup the IG for publication
Change or retain these parameters from the ImplementationGuide:
{ig_id}: ImplementationGuide.id: e.g. my-ig
{ig_url}: ImplementationGuide.url: e.g. http://openhie.org/fhir/hiv-cr/ImplementationGuide/my-ig
{ig_version}: ImplementationGuide.version: e.g. 0.1.0
{ig_package_id}: ImplementationGuide.packageId: e.g. ohie.fhir.hivRun the publisher to make sure everything is ok:
java -jar ../publisher.jar -ig .
Create a file called publication.request.json in the webroot folder. see IG Publication Request Documentation
3. Add a new release (run this for every new release)
- Create a file called publication.request.json in the webroot folder. see IG Publication Request Documentation
Run the publisher with the go-publish option:
e.g.
java -jar publisher.jar -go-publish -source my-ig -web (full path to webroot) -registry (full path to fhir-ig-list.json) -history (full path to ig-history) -templates (full path to templates)Note that the file paths have to be absolute.
Create a file publication-request.json:
{
"package-id": "{ig_package_id}",
"version" = {ig_version},
"desc" = {rel-desc},
"descmd" = {rel-desc},
"first" = true
"mode" = "milestone"
"path" = {canonical}/{ig_version},
"status" = {rel-status}, ci-build|draft|qa-preview|ballot|trial-use|release|update|normative+trial-use
"sequence" = (sequence Group, e.g. DSTU, Main... )
"changes": (optional link to a page describing changes)
}- That should do it. you should now have in your www folder the ig content, and onside it one folder for each release (e.g. /0.1.0, /0.2.0). In the root folder you should also have the history folder which would look like this (besides the template, of course)
4. Update ig registry
Finally, to have the Implementation Guide accessible to tools, the fhir-ig-list.json that was just updated should be uploaded via a PR to the original repository.
2 Comments
John Moehrke
should step 1.4 be to create a fork of ig-registry, followed by the creation of a branch in that fork? In order to submit your changes (the ig-build process given does update this folder) back to the FHIR ig-registry, the changes need to be on a forked repo with a pull-request. The ig-registry is managed differently.
Then at the very bottom one must then commit the changes that the IG build process made to the ig-registry folder, push them to a named branch, and then create a pull-request.
Then you need to plea to the gods (aka Grahame Grieve) to accept your pull-request on the ig-registry.
Or is these steps wrong? Or are these steps only necessary for organizations that want their IG in the ig-registry?
Grahame Grieve
Well, everyone should want their IG in the ig registry, but I think Jose Costa-Teixeira thought of that as part of a different process. But yes, that's what should be done