This wiki has undergone a migration to Confluence found Here
Difference between revisions of "FHIR IG Publishing tool"
Jump to navigation
Jump to search
| (2 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | = Introduction = | + | =Introduction= |
The FHIR team provides an tool used for publishing [[FHIR Implementation Guides]]. The tool takes the input of the implementation guide (resources, narrative, template) and converts it to a set of different types of files: | The FHIR team provides an tool used for publishing [[FHIR Implementation Guides]]. The tool takes the input of the implementation guide (resources, narrative, template) and converts it to a set of different types of files: | ||
| − | * generated HTML pages | + | |
| − | * resources (+ canonical redirections) | + | *generated HTML pages |
| − | * some zip files | + | *resources (+ canonical redirections) |
| − | * qa.html which contains information about the errors/issues found in the build process | + | *some zip files |
| + | *qa.html which contains information about the errors/issues found in the build process | ||
The "FHIR IG" is the set of files produced by the IG publishing tool. These files can be posted to a web server. | The "FHIR IG" is the set of files produced by the IG publishing tool. These files can be posted to a web server. | ||
| Line 12: | Line 13: | ||
---- | ---- | ||
| − | '''Important note this documentation describes a version of the IG publisher tool that is yet to be written''' | + | '''Important note: this documentation describes a version of the IG publisher tool that is yet to be written''' |
---- | ---- | ||
| − | = Using the IG Publisher = | + | =Using the IG Publisher= |
| − | == Installing == | + | ==Installing== |
| − | # Get the publisher itself: this is a java jar called <code>org.hl7.fhir.igpublisher.jar</code>. You can get it from the build.fhir.org downloads (e.g. | + | #Get the publisher itself: this is a java jar called <code>org.hl7.fhir.igpublisher.jar</code>. You can get it from the build.fhir.org downloads (e.g. http://build.fhir.org/downloads.html) for the version of FHIR you are using (or, if you build locally, from your own publish directory). The jar includes everything from the spec that is required to generate the implementation guide. |
| − | # Get the publishers helper: you need to install Jekyll in order to publish the said implementation guide. See [http://jekyll-windows.juthilo.com/1-ruby-and-devkit/ Windows] and [http://jekyll.tips/jekyll-casts/install-jekyll-on-linux/ Linux] instructions. | + | #Get the publishers helper: you need to install Jekyll in order to publish the said implementation guide. See [http://jekyll-windows.juthilo.com/1-ruby-and-devkit/ Windows] and [http://jekyll.tips/jekyll-casts/install-jekyll-on-linux/ Linux] instructions. |
| − | Always use the current version of the IG Publisher from the | + | Always use the current version of the IG Publisher from the release site ([https://fhir.github.io/latest-ig-publisher/org.hl7.fhir.publisher.jar https://fhir.github.io/latest-ig-publisher/]) - no other version is supported. You use this version irrespective of the FHIR version of the IG you are publishing. |
The publisher can be run as a GUI application, or run from the command line. Alternatively, you can use the IG Publisher in web server mode. If you do this, you don't need any installed software - if you want to host it, talk to Grahame Grieve. | The publisher can be run as a GUI application, or run from the command line. Alternatively, you can use the IG Publisher in web server mode. If you do this, you don't need any installed software - if you want to host it, talk to Grahame Grieve. | ||
| − | == Running in command line mode == | + | ==Running in command line mode== |
To run in command line mode, run the IG Publisher like this: | To run in command line mode, run the IG Publisher like this: | ||
| Line 34: | Line 35: | ||
parameters: | parameters: | ||
| − | * -ig: a path or a url where the implementation guide is found | + | |
| − | * -tx: (optional) address to use for terminology server (default is http://tx.fhir.org/r4, which is currently the only supported option) | + | *-ig: a path or a url where the implementation guide is found |
| − | * -watch (optional): if this is present, the publisher will not terminate; instead, it will stay running, and watch for changes to the IG or its contents and re-run when it sees changes. Note that changes the spec or to dependent implementation guides (see below) are not picked up during watch mode | + | *-tx: (optional) address to use for terminology server (default is http://tx.fhir.org/r4, which is currently the only supported option) |
| + | *-watch (optional): if this is present, the publisher will not terminate; instead, it will stay running, and watch for changes to the IG or its contents and re-run when it sees changes. Note that changes the spec or to dependent implementation guides (see below) are not picked up during watch mode | ||
Advanced parameters: | Advanced parameters: | ||
| − | * -resetTx - clear out the txCache (see comments below about managing the freshness of the txCache) | + | |
| − | * -resetTxErrors - delete any errors from the tcCache, but leave successful operations in the cache | + | *-resetTx - clear out the txCache (see comments below about managing the freshness of the txCache) |
| + | *-resetTxErrors - delete any errors from the tcCache, but leave successful operations in the cache | ||
Windows example: | Windows example: | ||
| Line 51: | Line 54: | ||
java -jar '/home/vadi/Programs/fhir-publisher/org.hl7.fhir.igpublisher.jar' -ig '/home/vadi/Programs/fhir-git/tests/ig/test-ig.json' -watch | java -jar '/home/vadi/Programs/fhir-publisher/org.hl7.fhir.igpublisher.jar' -ig '/home/vadi/Programs/fhir-git/tests/ig/test-ig.json' -watch | ||
| − | == Running in GUI mode == | + | ==Running in GUI mode== |
'''Windows''': double-click on org.hl7.fhir.igpublisher.jar or right-click and select 'Open'. | '''Windows''': double-click on org.hl7.fhir.igpublisher.jar or right-click and select 'Open'. | ||
| Line 70: | Line 73: | ||
| − | == Using the IG Publisher Web Server == | + | ==Using the IG Publisher Web Server== |
The IG publisher lives at [[http://hapi.fhir.org/igweb]]. From there, you can upload a ip file containing the contents of the IG. After processing, you can download the output. | The IG publisher lives at [[http://hapi.fhir.org/igweb]]. From there, you can upload a ip file containing the contents of the IG. After processing, you can download the output. | ||
| Line 78: | Line 81: | ||
You can also use the API to the IG web publisher directly. To do this, POST a zip containing the IG content to http://hapi.fhir.org/igweb/process (Content-Tyepe: application/zip), and after a period of seconds, a zip file containing the generated output will be returned. | You can also use the API to the IG web publisher directly. To do this, POST a zip containing the IG content to http://hapi.fhir.org/igweb/process (Content-Tyepe: application/zip), and after a period of seconds, a zip file containing the generated output will be returned. | ||
| − | = Publishing IGs = | + | =Publishing IGs= |
| − | == Operation of the IG Publisher == | + | ==Operation of the IG Publisher== |
The implementation guide follows this general process: | The implementation guide follows this general process: | ||
| − | * reads the Implementation guide | + | |
| − | * loads all the resources in the IG, and processes any spreadsheets, and bundles referred to in it | + | *reads the Implementation guide |
| − | * processes code systems, value sets, structure definitions, structure maps | + | *loads all the resources in the IG, and processes any spreadsheets, and bundles referred to in it |
| − | * processes the logical models | + | *processes code systems, value sets, structure definitions, structure maps |
| − | * validates the all resources and produces an HTML QA file with any errors encountered | + | *processes the logical models |
| − | * fetches the template for the IG | + | *validates the all resources and produces an HTML QA file with any errors encountered |
| − | * for each resource in the IG, as specified by the template, generates a set of files - renderings of the artifact for possible inclusion in the published IG, plus the outputs defined above | + | *fetches the template for the IG |
| − | * generates summary output | + | *for each resource in the IG, as specified by the template, generates a set of files - renderings of the artifact for possible inclusion in the published IG, plus the outputs defined above |
| − | * use Jekyll to generate the final output. The Jekyll source is in /pages by default | + | *generates summary output |
| − | * checks for well formed html, broken links, and security risks in the generated pages | + | *use Jekyll to generate the final output. The Jekyll source is in /pages by default |
| + | *checks for well formed html, broken links, and security risks in the generated pages | ||
The output from the IG Publishing tool conforms to the [[FHIR Implementation Guide Publishing Requirements]] | The output from the IG Publishing tool conforms to the [[FHIR Implementation Guide Publishing Requirements]] | ||
| − | == Implementation Guide Resource Documentation == | + | ==Implementation Guide Resource Documentation== |
Each Implementation guide is generated from an [[http://build.fhir.org/implementationguide.html Implementation Guide resources]]. Irrespective of the version of the FHIR Implementation guide, the IG publisher uses the current build version of the implementation guide - authors are required to use the current version (this is the only resource for which this is true). | Each Implementation guide is generated from an [[http://build.fhir.org/implementationguide.html Implementation Guide resources]]. Irrespective of the version of the FHIR Implementation guide, the IG publisher uses the current build version of the implementation guide - authors are required to use the current version (this is the only resource for which this is true). | ||
| Line 102: | Line 106: | ||
This section documents the use of the implementation guide resource by the IG Publishing tool | This section documents the use of the implementation guide resource by the IG Publishing tool | ||
| − | === Identification === | + | ===Identification=== |
| − | * id (prohibited): do not provide an id. The IG publisher will generate it | + | *id (prohibited): do not provide an id. The IG publisher will generate it |
| − | * url (required): specify the canonical URL for the IG. This will not change over the lifetime of the IG | + | *url (required): specify the canonical URL for the IG. This will not change over the lifetime of the IG |
| − | * version (required): this is the business version of the IG, managed by the author of the IG | + | *version (required): this is the business version of the IG, managed by the author of the IG |
| − | * date (optional): the IG publisher will overwrite whatever you have in here | + | *date (optional): the IG publisher will overwrite whatever you have in here |
| − | * fhirVersion (required): the FHIR version of the IG. The only valid values are: 1.0.2, 1.4.0, 3.0.1 and 3.4.0 | + | *fhirVersion (required): the FHIR version of the IG. The only valid values are: 1.0.2, 1.4.0, 3.0.1 and 3.4.0 |
| − | === Dependencies === | + | ===Dependencies=== |
Many Igs depend on other FHIR IGs. The dependencies must be listed in the IG resource. | Many Igs depend on other FHIR IGs. The dependencies must be listed in the IG resource. | ||
| − | * uri (required): the canonical URL of the IG that this IG depends on | + | *uri (required): the canonical URL of the IG that this IG depends on |
| − | * version (optional): the version of the IG to use. If missing, the publisher will use whatever is found at the canonical URL | + | *version (optional): the version of the IG to use. If missing, the publisher will use whatever is found at the canonical URL |
Note: the IG publisher uses NPM packages to manage dependencies - see below for managing dependency resolution. | Note: the IG publisher uses NPM packages to manage dependencies - see below for managing dependency resolution. | ||
| − | === Packages === | + | ===Packages=== |
Authors are free to define packages or not in their implementation guides. The only impact of packages relates to the construction of content / table of contents etc as specified by the templates. Consult the selected template for additional information about the use of packages. | Authors are free to define packages or not in their implementation guides. The only impact of packages relates to the construction of content / table of contents etc as specified by the templates. Consult the selected template for additional information about the use of packages. | ||
| − | === Resources === | + | ===Resources=== |
List all resources used by the implementation guide | List all resources used by the implementation guide | ||
| − | * reference (required): the resource to include. See below for information about how the IG publisher resolves references to literal locations | + | *reference (required): the resource to include. See below for information about how the IG publisher resolves references to literal locations |
| − | * name (optional): a name to describe the resource - used when generating references to the resource throughout the content. if not provided, the IG publisher will generate a name (fall back is the id if the IG publisher doesn't know how to get a better name for resource) | + | *name (optional): a name to describe the resource - used when generating references to the resource throughout the content. if not provided, the IG publisher will generate a name (fall back is the id if the IG publisher doesn't know how to get a better name for resource) |
| − | * description (optional): not used by the IG publisher | + | *description (optional): not used by the IG publisher |
| − | * example (optional): if boolean, then used when generating indexes. If a canonical is provided, the example will be validated against the identified profile while publishing, and the example will be indexed against the profile (if the template specifies). if not present, the resource will not be treated as an example (conformance resources only) | + | *example (optional): if boolean, then used when generating indexes. If a canonical is provided, the example will be validated against the identified profile while publishing, and the example will be indexed against the profile (if the template specifies). if not present, the resource will not be treated as an example (conformance resources only) |
| − | * package (optional): used by the templates | + | *package (optional): used by the templates |
Note that you can ask the IG publisher to load resources without listing them all - see extensions below | Note that you can ask the IG publisher to load resources without listing them all - see extensions below | ||
| − | === Pages === | + | ===Pages=== |
Lists all the pages included in the IG | Lists all the pages included in the IG | ||
| − | * name[x] (required): use URI, which is treated as the location of the page. relative URIs recommended | + | *name[x] (required): use URI, which is treated as the location of the page. relative URIs recommended |
| − | * title (optional): stated title for the page. If not provided, the IG publisher will attempt to extract the page title from the content, or fall back to the name of the page | + | *title (optional): stated title for the page. If not provided, the IG publisher will attempt to extract the page title from the content, or fall back to the name of the page |
| − | * generation (optional): how the page will treated when generating content. defaults to html. Use generated for pages that have no actual source, but will go in the ToC | + | *generation (optional): how the page will treated when generating content. defaults to html. Use generated for pages that have no actual source, but will go in the ToC |
Note that you can ask the IG publisher to process additional pages without listing them all - see extensions below. Unlisted pages will not be generated into the ToC | Note that you can ask the IG publisher to process additional pages without listing them all - see extensions below. Unlisted pages will not be generated into the ToC | ||
| − | === Parameters === | + | ===Parameters=== |
The following additional documentation applies to the IG parameters section: | The following additional documentation applies to the IG parameters section: | ||
| − | * template (required): the URL of the template to use when generating the file (for additional information about templates, see [[FHIR IG publisher templates]]) | + | *template (required): the URL of the template to use when generating the file (for additional information about templates, see [[FHIR IG publisher templates]]) |
| − | * license (required): see below | + | *license (required): see below |
| − | * npm-name (required): node Package Name - see below | + | *npm-name (required): node Package Name - see below |
| − | * npm-template (optional) : npm package template file - see below | + | *npm-template (optional) : npm package template file - see below |
| − | * rule-broken-links (required): will be followed as specified in the [[http://build.fhir.org spec]] | + | *rule-broken-links (required): will be followed as specified in the [[http://build.fhir.org spec]] |
| − | * apply-business-version (optional): will be enforced if specified in the [[http://build.fhir.org spec]] | + | *apply-business-version (optional): will be enforced if specified in the [[http://build.fhir.org spec]] |
| − | * apply-jurisdiction (optional): will be enforced if specified (as in the [[http://build.fhir.org spec]]) | + | *apply-jurisdiction (optional): will be enforced if specified (as in the [[http://build.fhir.org spec]]) |
| − | * path-cache (optional): see "managing the cache" below | + | *path-cache (optional): see "managing the cache" below |
| − | * expansion-profile (optional): a reference to an expansion profile that will be used when generating expansions/validating resources while publishing the IG. Though this is labelled optional, it is mandatory if the IG contains any SNOMED CT Content. See below for information about how the IG publisher resolves references to literal locations | + | *expansion-profile (optional): a reference to an expansion profile that will be used when generating expansions/validating resources while publishing the IG. Though this is labelled optional, it is mandatory if the IG contains any SNOMED CT Content. See below for information about how the IG publisher resolves references to literal locations |
| − | * generate-xml (optional): will be followed as specified (as in the [[http://build.fhir.org spec]]). default is true | + | *generate-xml (optional): will be followed as specified (as in the [[http://build.fhir.org spec]]). default is true |
| − | * generate-json (optional): will be followed as specified (as in the [[http://build.fhir.org spec]]). default is true | + | *generate-json (optional): will be followed as specified (as in the [[http://build.fhir.org spec]]). default is true |
| − | * generate-turtle (optional): will be followed as specified (as in the [[http://build.fhir.org spec]]). default is true (except for v1.0.2 where turtle is not supported) | + | *generate-turtle (optional): will be followed as specified (as in the [[http://build.fhir.org spec]]). default is true (except for v1.0.2 where turtle is not supported) |
| − | * logging (optional): see below | + | *logging (optional): see below |
| − | * extension-domain (optional): An extension domain for which extensions are not validated (when validating resources - typically http://example.org/fhir etc) | + | *extension-domain (optional): An extension domain for which extensions are not validated (when validating resources - typically http://example.org/fhir etc) |
| − | * history-page (optional): a relative URI that identifies a page that will be provided later that is the history of published versions. The only signficance of this parameter is that references to this page are not counted as broken links. | + | *history-page (optional): a relative URI that identifies a page that will be provided later that is the history of published versions. The only signficance of this parameter is that references to this page are not counted as broken links. |
Still to do: | Still to do: | ||
| − | |||
| − | |||
| − | |||
| − | === Extensions === | + | *warnings for aggregation, must-support |
| + | *logical model management | ||
| + | *multi-language support | ||
| + | |||
| + | ===Extensions=== | ||
The IG publisher defines the following extensions for the ImplementationGuide.definition section: | The IG publisher defines the following extensions for the ImplementationGuide.definition section: | ||
| − | * scan (<code>http://fhir.org/ig-publisher/StructureDefinition/scan-folder</code>) - look through this nominated location (a relative URL) for resources and auto-load them as well (will be treated as if they were contained in the definitions) | + | *scan (<code>http://fhir.org/ig-publisher/StructureDefinition/scan-folder</code>) - look through this nominated location (a relative URL) for resources and auto-load them as well (will be treated as if they were contained in the definitions) |
| − | * pages (<code>http://fhir.org/ig-publisher/StructureDefinition/page-content</code>) - process any content in this folder (a relative URL) when scanning pages. Note that pages found this way are ''not'' registered in the definitions, and won't appear in generated table of contents. | + | *pages (<code>http://fhir.org/ig-publisher/StructureDefinition/page-content</code>) - process any content in this folder (a relative URL) when scanning pages. Note that pages found this way are ''not'' registered in the definitions, and won't appear in generated table of contents. |
| − | * spreadsheet (<code>http://fhir.org/ig-publisher/StructureDefinition/spreadsheet</code>) - load profiles from the nominated spreadsheet (literal relative location) | + | *spreadsheet (<code>http://fhir.org/ig-publisher/StructureDefinition/spreadsheet</code>) - load profiles from the nominated spreadsheet (literal relative location) |
| − | * unpack (<code>http://fhir.org/ig-publisher/StructureDefinition/unpack</code>) - Used on a resource (ImplementationGuide.definition.resource) to indicate that the resource is a bundle, and the IG publisher should unpack it bundle and treat each resource independently | + | *unpack (<code>http://fhir.org/ig-publisher/StructureDefinition/unpack</code>) - Used on a resource (ImplementationGuide.definition.resource) to indicate that the resource is a bundle, and the IG publisher should unpack it bundle and treat each resource independently |
| − | * canonical-exception (<code>http://fhir.org/ig-publisher/StructureDefinition/canonical-exception</code>) - see below | + | *canonical-exception (<code>http://fhir.org/ig-publisher/StructureDefinition/canonical-exception</code>) - see below |
| − | == Managing the Cache == | + | ==Managing the Cache== |
todo | todo | ||
| − | == Resolving Dependencies == | + | ==Resolving Dependencies== |
todo | todo | ||
| − | == Resolving References == | + | ==Resolving References== |
todo | todo | ||
| − | == License Information == | + | ==License Information== |
The license parameter is required and is either: | The license parameter is required and is either: | ||
| − | * An identifier from the [https://spdx.org/licenses/ SPDX License List] | + | *An identifier from the [https://spdx.org/licenses/ SPDX License List] |
| − | * or literal string "Not Open Source" | + | *or literal string "Not Open Source" |
For example | For example | ||
| Line 207: | Line 212: | ||
The specified license should appear in the published IG on every page (this should be done by the template) | The specified license should appear in the published IG on every page (this should be done by the template) | ||
| − | == NPM Package Information == | + | ==NPM Package Information== |
The publisher will produce an NPM package for ease of distribution if the property "npm-name" has a value. This name is assigned by the FHIR product Director - see [[FHIR IG NPM Profile]] for details. This is required for all Implementation Guides published by HL7. | The publisher will produce an NPM package for ease of distribution if the property "npm-name" has a value. This name is assigned by the FHIR product Director - see [[FHIR IG NPM Profile]] for details. This is required for all Implementation Guides published by HL7. | ||
| Line 214: | Line 219: | ||
| − | == Logging Control == | + | ==Logging Control== |
The IG publisher performs 3 sorts of logging: | The IG publisher performs 3 sorts of logging: | ||
| − | * basic progress logging to stdout (what you see) | + | *basic progress logging to stdout (what you see) |
| − | * A full log to [tmp]/fhir-ig-publishing-tmp.log | + | *A full log to [tmp]/fhir-ig-publishing-tmp.log |
| − | * in case of build failure, a debugging report to fhir-ig-publishing.log | + | *in case of build failure, a debugging report to fhir-ig-publishing.log |
You can change to amount of logging that goes to stdout using this logging parameter in the IG: | You can change to amount of logging that goes to stdout using this logging parameter in the IG: | ||
| Line 229: | Line 234: | ||
where the options are any of these words: | where the options are any of these words: | ||
| − | * '''init''': log extra details about the IG publisher initialization sequence | + | *'''init''': log extra details about the IG publisher initialization sequence |
| − | * '''progress''': log extra details about the sequence of actions taken by the IG publisher | + | *'''progress''': log extra details about the sequence of actions taken by the IG publisher |
| − | * '''context''': log each time a resource is added to the context (e.g. support validation) | + | *'''context''': log each time a resource is added to the context (e.g. support validation) |
| − | * '''html''': log HTML link checking details | + | *'''html''': log HTML link checking details |
| − | * '''tx''': detailed messages from the terminology sub-system | + | *'''tx''': detailed messages from the terminology sub-system |
This is particularly useful when debugging the auto-build when all you get is the stdout. The logging parameter may appear multiple times. | This is particularly useful when debugging the auto-build when all you get is the stdout. The logging parameter may appear multiple times. | ||
| − | == Special Canonical URLS == | + | ==Special Canonical URLS== |
| Line 246: | Line 251: | ||
Notes: | Notes: | ||
| − | * Resources have to be explicitly identified because it's too easy for an author to make a mistake and get the canonical URL wrong | + | *Resources have to be explicitly identified because it's too easy for an author to make a mistake and get the canonical URL wrong |
| − | * one case for using this facility is where the IG includes a resource that is also published elsewhere. Author's should think hard before doing this - referring to a resource by it's canonical URL rather than copying into the IG is generally a much better approach in terms of ongoing maintenance. | + | *one case for using this facility is where the IG includes a resource that is also published elsewhere. Author's should think hard before doing this - referring to a resource by it's canonical URL rather than copying into the IG is generally a much better approach in terms of ongoing maintenance. |
| + | |||
| + | =Template Variables available in narrative files == | ||
| + | |||
| + | Narrative content will be processed by Jekyll when the IG is published. The following variables will be available in Jekyll (in addition to the standard Jekyll variables): | ||
| + | |||
| + | todo | ||
| − | = Troubleshooting = | + | =Troubleshooting= |
Notes about troubleshooting: | Notes about troubleshooting: | ||
| − | # before doing any trouble shooting, make sure you are running the latest IG publisher for the version of FHIR you are using | + | #before doing any trouble shooting, make sure you are running the latest IG publisher for the version of FHIR you are using |
| − | # Jekyll may not run if you have spaces your file path. Move to root directory, or eliminate spaces. | + | #Jekyll may not run if you have spaces your file path. Move to root directory, or eliminate spaces. |
| − | # if the Jekyll part of the build fails, it fails completely, and the old output is left in place | + | #if the Jekyll part of the build fails, it fails completely, and the old output is left in place |
| − | # if the build completes, and there's problems in the output, first, work through all the errors in the validation output before you ask for help | + | #if the build completes, and there's problems in the output, first, work through all the errors in the validation output before you ask for help |
| − | # Jekyll error "Permission denied @unlink_internal" - you have a file locked in the temp or output directory. Close any files in editors, and ensure you are only running one publisher | + | #Jekyll error "Permission denied @unlink_internal" - you have a file locked in the temp or output directory. Close any files in editors, and ensure you are only running one publisher |
| − | # If you're going to ask Grahame for help send the file fhir-ig-publishing.log in your temp directory to grahame@hl7.org along with a detailed description of what the problem is. (Alternatively, run the GUI version click, wait for the end ofthe run, and the click on the 'Debug Summary' button which puts the log on the clipboard so you can send pate it into your email) | + | #If you're going to ask Grahame for help send the file fhir-ig-publishing.log in your temp directory to grahame@hl7.org along with a detailed description of what the problem is. (Alternatively, run the GUI version click, wait for the end ofthe run, and the click on the 'Debug Summary' button which puts the log on the clipboard so you can send pate it into your email) |
Before you ask about any terminology or dependency related issues, delete the content of your txCache directory, and run the IG publisher again | Before you ask about any terminology or dependency related issues, delete the content of your txCache directory, and run the IG publisher again | ||
| − | = IG Language Support = | + | =IG Language Support= |
'''Note: this section is draft - the functionality described here is not yet implemented.''' | '''Note: this section is draft - the functionality described here is not yet implemented.''' | ||
| Line 272: | Line 283: | ||
It's possible to publish Implementation Guides in other languages, or to publish them in multiple languages. Note, though, that there is always a single master language that the IG Publisher uses when publishing. | It's possible to publish Implementation Guides in other languages, or to publish them in multiple languages. Note, though, that there is always a single master language that the IG Publisher uses when publishing. | ||
| − | == Specifying an Alternate Master Language == | + | ==Specifying an Alternate Master Language== |
To change the language from English, specify a language using the "language" property in the [[#Control file|json control]] file: | To change the language from English, specify a language using the "language" property in the [[#Control file|json control]] file: | ||
| Line 282: | Line 293: | ||
When an alternative language is specified, the IG publisher changes how it works in the following ways: | When an alternative language is specified, the IG publisher changes how it works in the following ways: | ||
| − | * When reading any text from a resource definition, the IG publisher will first look at any [[http://hl7.org/fhir/extension-translation.html translation extensions]] on the element for a matching language tag (full match including country first, then partial match). If there's no matching extension, it will just use the element value. This applies to any elements of type 'string' or 'markdown' | + | *When reading any text from a resource definition, the IG publisher will first look at any [[http://hl7.org/fhir/extension-translation.html translation extensions]] on the element for a matching language tag (full match including country first, then partial match). If there's no matching extension, it will just use the element value. This applies to any elements of type 'string' or 'markdown' |
| − | * When looking up codes on the terminology server, the IG publisher will ask for the specified language. tx.fhir.org uses the same approach as immediately above in this case. Note: to get code system displays in additional languages defined on tx.fhir.org, talk to Grahame Grieve | + | *When looking up codes on the terminology server, the IG publisher will ask for the specified language. tx.fhir.org uses the same approach as immediately above in this case. Note: to get code system displays in additional languages defined on tx.fhir.org, talk to Grahame Grieve |
| − | * Any text that is used by the IG publisher that is not in the specified language will be pass to an internal translation module that can translate the text to the target language. This is driven by a configuration file that has a list of mappings from language to language. The input file to configure this is languages.json in the same directory as the config file. There will be a file produced in the qa directory, also called languages.txt, which is the same file with any untranslated texts added (to help editors build the language file) | + | *Any text that is used by the IG publisher that is not in the specified language will be pass to an internal translation module that can translate the text to the target language. This is driven by a configuration file that has a list of mappings from language to language. The input file to configure this is languages.json in the same directory as the config file. There will be a file produced in the qa directory, also called languages.txt, which is the same file with any untranslated texts added (to help editors build the language file) |
| − | * Any content in the pages is left untouched. | + | *Any content in the pages is left untouched. |
| − | == Using multiple languages == | + | ==Using multiple languages== |
In addition, the IG publisher can produce fragments in multiple languages. To do this, specify additional languages using the language property; | In addition, the IG publisher can produce fragments in multiple languages. To do this, specify additional languages using the language property; | ||
| Line 297: | Line 308: | ||
When you specify additional languages, for each output file that the IG publisher creates, it will also create additional fragments with same base file name, with -[lang] appended, in the specified language. This way, authors can build IGs in multiple languages. In this case, the language file will contain additional langauge codes but work as otherwise described above. | When you specify additional languages, for each output file that the IG publisher creates, it will also create additional fragments with same base file name, with -[lang] appended, in the specified language. This way, authors can build IGs in multiple languages. In this case, the language file will contain additional langauge codes but work as otherwise described above. | ||
| − | == Sharing Language Translations Across IGs == | + | ==Sharing Language Translations Across IGs== |
Todo. Not sure about this yet | Todo. Not sure about this yet | ||
Latest revision as of 20:18, 9 March 2020
Contents
- 1 Introduction
- 2 Using the IG Publisher
- 3 Publishing IGs
- 4 Template Variables available in narrative files =
- 5 Troubleshooting
- 6 IG Language Support
Introduction
The FHIR team provides an tool used for publishing FHIR Implementation Guides. The tool takes the input of the implementation guide (resources, narrative, template) and converts it to a set of different types of files:
- generated HTML pages
- resources (+ canonical redirections)
- some zip files
- qa.html which contains information about the errors/issues found in the build process
The "FHIR IG" is the set of files produced by the IG publishing tool. These files can be posted to a web server.
Important note: this documentation describes a version of the IG publisher tool that is yet to be written
Using the IG Publisher
Installing
- Get the publisher itself: this is a java jar called
org.hl7.fhir.igpublisher.jar. You can get it from the build.fhir.org downloads (e.g. http://build.fhir.org/downloads.html) for the version of FHIR you are using (or, if you build locally, from your own publish directory). The jar includes everything from the spec that is required to generate the implementation guide. - Get the publishers helper: you need to install Jekyll in order to publish the said implementation guide. See Windows and Linux instructions.
Always use the current version of the IG Publisher from the release site (https://fhir.github.io/latest-ig-publisher/) - no other version is supported. You use this version irrespective of the FHIR version of the IG you are publishing. The publisher can be run as a GUI application, or run from the command line. Alternatively, you can use the IG Publisher in web server mode. If you do this, you don't need any installed software - if you want to host it, talk to Grahame Grieve.
Running in command line mode
To run in command line mode, run the IG Publisher like this:
java -jar org.hl7.fhir.igpublisher.jar -ig [source] (-tx [url]) (-watch)
parameters:
- -ig: a path or a url where the implementation guide is found
- -tx: (optional) address to use for terminology server (default is http://tx.fhir.org/r4, which is currently the only supported option)
- -watch (optional): if this is present, the publisher will not terminate; instead, it will stay running, and watch for changes to the IG or its contents and re-run when it sees changes. Note that changes the spec or to dependent implementation guides (see below) are not picked up during watch mode
Advanced parameters:
- -resetTx - clear out the txCache (see comments below about managing the freshness of the txCache)
- -resetTxErrors - delete any errors from the tcCache, but leave successful operations in the cache
Windows example:
Open the command prompt, then paste the following, with the paths adjusted for your computer:
java -jar "C:\Users\VadimPeretokin\Desktop\fhir-publisher\org.hl7.fhir.igpublisher.jar" -ig "C:\Users\VadimPeretokin\Desktop\fhir-git\tests\ig\test-ig.json" -watch
Linux: Open the terminal (usually Ctrl+Alt+T), then paste the following, with the paths adjusted for your computer:
java -jar '/home/vadi/Programs/fhir-publisher/org.hl7.fhir.igpublisher.jar' -ig '/home/vadi/Programs/fhir-git/tests/ig/test-ig.json' -watch
Running in GUI mode
Windows: double-click on org.hl7.fhir.igpublisher.jar or right-click and select 'Open'.
Linux: double-click on org.hl7.fhir.igpublisher.jar or right-click and select 'Open With Oracle Java 8 Runtime'.
You can also run it the command line:
java -jar org.hl7.fhir.igpublisher.jar
Note that this doesn't work in OpenJDK - if you are using openJDK, your only option is to run it from the command prompt, as described below.
This is the IG builder:
To use it, 'Choose' an implementation guide control JSON file, and click 'Execute'. The implementation guide will be built, and then the IG publisher will watch for changes until and do incremental rebuilds until you click 'Stop'.
Using the IG Publisher Web Server
The IG publisher lives at [[1]]. From there, you can upload a ip file containing the contents of the IG. After processing, you can download the output.
Note that it's a little inconvenient to flip between modes (running locally vs using the web publisher) because the standard folder structures include /qa, /temp, and /output - you don't want to upload these - they can be very large (though the IG server will ignore them if you do). Also, the web publisher maintains it's own terminology server cache, and may give different results for expansions etc than if you are using your own txCache in the folder and not keeping it up to date.
You can also use the API to the IG web publisher directly. To do this, POST a zip containing the IG content to http://hapi.fhir.org/igweb/process (Content-Tyepe: application/zip), and after a period of seconds, a zip file containing the generated output will be returned.
Publishing IGs
Operation of the IG Publisher
The implementation guide follows this general process:
- reads the Implementation guide
- loads all the resources in the IG, and processes any spreadsheets, and bundles referred to in it
- processes code systems, value sets, structure definitions, structure maps
- processes the logical models
- validates the all resources and produces an HTML QA file with any errors encountered
- fetches the template for the IG
- for each resource in the IG, as specified by the template, generates a set of files - renderings of the artifact for possible inclusion in the published IG, plus the outputs defined above
- generates summary output
- use Jekyll to generate the final output. The Jekyll source is in /pages by default
- checks for well formed html, broken links, and security risks in the generated pages
The output from the IG Publishing tool conforms to the FHIR Implementation Guide Publishing Requirements
Implementation Guide Resource Documentation
Each Implementation guide is generated from an [Implementation Guide resources]. Irrespective of the version of the FHIR Implementation guide, the IG publisher uses the current build version of the implementation guide - authors are required to use the current version (this is the only resource for which this is true).
This section documents the use of the implementation guide resource by the IG Publishing tool
Identification
- id (prohibited): do not provide an id. The IG publisher will generate it
- url (required): specify the canonical URL for the IG. This will not change over the lifetime of the IG
- version (required): this is the business version of the IG, managed by the author of the IG
- date (optional): the IG publisher will overwrite whatever you have in here
- fhirVersion (required): the FHIR version of the IG. The only valid values are: 1.0.2, 1.4.0, 3.0.1 and 3.4.0
Dependencies
Many Igs depend on other FHIR IGs. The dependencies must be listed in the IG resource.
- uri (required): the canonical URL of the IG that this IG depends on
- version (optional): the version of the IG to use. If missing, the publisher will use whatever is found at the canonical URL
Note: the IG publisher uses NPM packages to manage dependencies - see below for managing dependency resolution.
Packages
Authors are free to define packages or not in their implementation guides. The only impact of packages relates to the construction of content / table of contents etc as specified by the templates. Consult the selected template for additional information about the use of packages.
Resources
List all resources used by the implementation guide
- reference (required): the resource to include. See below for information about how the IG publisher resolves references to literal locations
- name (optional): a name to describe the resource - used when generating references to the resource throughout the content. if not provided, the IG publisher will generate a name (fall back is the id if the IG publisher doesn't know how to get a better name for resource)
- description (optional): not used by the IG publisher
- example (optional): if boolean, then used when generating indexes. If a canonical is provided, the example will be validated against the identified profile while publishing, and the example will be indexed against the profile (if the template specifies). if not present, the resource will not be treated as an example (conformance resources only)
- package (optional): used by the templates
Note that you can ask the IG publisher to load resources without listing them all - see extensions below
Pages
Lists all the pages included in the IG
- name[x] (required): use URI, which is treated as the location of the page. relative URIs recommended
- title (optional): stated title for the page. If not provided, the IG publisher will attempt to extract the page title from the content, or fall back to the name of the page
- generation (optional): how the page will treated when generating content. defaults to html. Use generated for pages that have no actual source, but will go in the ToC
Note that you can ask the IG publisher to process additional pages without listing them all - see extensions below. Unlisted pages will not be generated into the ToC
Parameters
The following additional documentation applies to the IG parameters section:
- template (required): the URL of the template to use when generating the file (for additional information about templates, see FHIR IG publisher templates)
- license (required): see below
- npm-name (required): node Package Name - see below
- npm-template (optional) : npm package template file - see below
- rule-broken-links (required): will be followed as specified in the [spec]
- apply-business-version (optional): will be enforced if specified in the [spec]
- apply-jurisdiction (optional): will be enforced if specified (as in the [spec])
- path-cache (optional): see "managing the cache" below
- expansion-profile (optional): a reference to an expansion profile that will be used when generating expansions/validating resources while publishing the IG. Though this is labelled optional, it is mandatory if the IG contains any SNOMED CT Content. See below for information about how the IG publisher resolves references to literal locations
- generate-xml (optional): will be followed as specified (as in the [spec]). default is true
- generate-json (optional): will be followed as specified (as in the [spec]). default is true
- generate-turtle (optional): will be followed as specified (as in the [spec]). default is true (except for v1.0.2 where turtle is not supported)
- logging (optional): see below
- extension-domain (optional): An extension domain for which extensions are not validated (when validating resources - typically http://example.org/fhir etc)
- history-page (optional): a relative URI that identifies a page that will be provided later that is the history of published versions. The only signficance of this parameter is that references to this page are not counted as broken links.
Still to do:
- warnings for aggregation, must-support
- logical model management
- multi-language support
Extensions
The IG publisher defines the following extensions for the ImplementationGuide.definition section:
- scan (
http://fhir.org/ig-publisher/StructureDefinition/scan-folder) - look through this nominated location (a relative URL) for resources and auto-load them as well (will be treated as if they were contained in the definitions) - pages (
http://fhir.org/ig-publisher/StructureDefinition/page-content) - process any content in this folder (a relative URL) when scanning pages. Note that pages found this way are not registered in the definitions, and won't appear in generated table of contents. - spreadsheet (
http://fhir.org/ig-publisher/StructureDefinition/spreadsheet) - load profiles from the nominated spreadsheet (literal relative location) - unpack (
http://fhir.org/ig-publisher/StructureDefinition/unpack) - Used on a resource (ImplementationGuide.definition.resource) to indicate that the resource is a bundle, and the IG publisher should unpack it bundle and treat each resource independently - canonical-exception (
http://fhir.org/ig-publisher/StructureDefinition/canonical-exception) - see below
Managing the Cache
todo
Resolving Dependencies
todo
Resolving References
todo
License Information
The license parameter is required and is either:
- An identifier from the SPDX License List
- or literal string "Not Open Source"
For example
This FHIR Specification is licensed under Creative Commons "No Rights Reserved" for which the identifier is CC0-1.0.
"license": "CC0-1.0",
The specified license should appear in the published IG on every page (this should be done by the template)
NPM Package Information
The publisher will produce an NPM package for ease of distribution if the property "npm-name" has a value. This name is assigned by the FHIR product Director - see FHIR IG NPM Profile for details. This is required for all Implementation Guides published by HL7.
The IG publisher fills out a few mandatory elements in the package file from the information it has available. Authors can provide additional details beyond those generated by the IG publisher by providing a template which is loaded before the IG publisher writes out the details. The property "npm-template" is relative to the folder containing the configuration file
Logging Control
The IG publisher performs 3 sorts of logging:
- basic progress logging to stdout (what you see)
- A full log to [tmp]/fhir-ig-publishing-tmp.log
- in case of build failure, a debugging report to fhir-ig-publishing.log
You can change to amount of logging that goes to stdout using this logging parameter in the IG:
"logging" : "option"
where the options are any of these words:
- init: log extra details about the IG publisher initialization sequence
- progress: log extra details about the sequence of actions taken by the IG publisher
- context: log each time a resource is added to the context (e.g. support validation)
- html: log HTML link checking details
- tx: detailed messages from the terminology sub-system
This is particularly useful when debugging the auto-build when all you get is the stdout. The logging parameter may appear multiple times.
Special Canonical URLS
For MetadataResources - CodeSystem, ValueSet, etc (anything with a canonical URL) - the IG publisher expects that their Canonical URL is equal to [canonical]/[type]/[id] where [canonical is the IG canonical URL. The IG publisher will ensure that the IG itself is an valid FHIR implementation guide and responds correctly to requests for the resources by their canonical URL.
However in some cases, it's not possible or appropriate for a metadata resource to use the same canonical URL as where the IG is publishing it. In these cases, the resources that are exempt from this rules need to be identified explicitly using the canonical-exception extension documented above.
Notes:
- Resources have to be explicitly identified because it's too easy for an author to make a mistake and get the canonical URL wrong
- one case for using this facility is where the IG includes a resource that is also published elsewhere. Author's should think hard before doing this - referring to a resource by it's canonical URL rather than copying into the IG is generally a much better approach in terms of ongoing maintenance.
Template Variables available in narrative files =
Narrative content will be processed by Jekyll when the IG is published. The following variables will be available in Jekyll (in addition to the standard Jekyll variables):
todo
Troubleshooting
Notes about troubleshooting:
- before doing any trouble shooting, make sure you are running the latest IG publisher for the version of FHIR you are using
- Jekyll may not run if you have spaces your file path. Move to root directory, or eliminate spaces.
- if the Jekyll part of the build fails, it fails completely, and the old output is left in place
- if the build completes, and there's problems in the output, first, work through all the errors in the validation output before you ask for help
- Jekyll error "Permission denied @unlink_internal" - you have a file locked in the temp or output directory. Close any files in editors, and ensure you are only running one publisher
- If you're going to ask Grahame for help send the file fhir-ig-publishing.log in your temp directory to grahame@hl7.org along with a detailed description of what the problem is. (Alternatively, run the GUI version click, wait for the end ofthe run, and the click on the 'Debug Summary' button which puts the log on the clipboard so you can send pate it into your email)
Before you ask about any terminology or dependency related issues, delete the content of your txCache directory, and run the IG publisher again
IG Language Support
Note: this section is draft - the functionality described here is not yet implemented.
By default, the IG publisher is semi-language agnostic. Content from resources or pages is published in whatever language is expressed in the resources and the pages, but text injected by the IG publisher itself (some sprinkled text scattered through the include files) is in English. The intent of this mode is to support English language publishing.
It's possible to publish Implementation Guides in other languages, or to publish them in multiple languages. Note, though, that there is always a single master language that the IG Publisher uses when publishing.
Specifying an Alternate Master Language
To change the language from English, specify a language using the "language" property in the json control file:
"language" : "es-AR"
(The language tag is a standard xml:lang .e.g. BCP 47 tag. It must have a language, and may have a country (as shown above). Other sub-tags are not allowed)
When an alternative language is specified, the IG publisher changes how it works in the following ways:
- When reading any text from a resource definition, the IG publisher will first look at any [translation extensions] on the element for a matching language tag (full match including country first, then partial match). If there's no matching extension, it will just use the element value. This applies to any elements of type 'string' or 'markdown'
- When looking up codes on the terminology server, the IG publisher will ask for the specified language. tx.fhir.org uses the same approach as immediately above in this case. Note: to get code system displays in additional languages defined on tx.fhir.org, talk to Grahame Grieve
- Any text that is used by the IG publisher that is not in the specified language will be pass to an internal translation module that can translate the text to the target language. This is driven by a configuration file that has a list of mappings from language to language. The input file to configure this is languages.json in the same directory as the config file. There will be a file produced in the qa directory, also called languages.txt, which is the same file with any untranslated texts added (to help editors build the language file)
- Any content in the pages is left untouched.
Using multiple languages
In addition, the IG publisher can produce fragments in multiple languages. To do this, specify additional languages using the language property;
"languages" : [ "du", "es", "ru"]
Note that you must specify a primary language if you specify additional languages.
When you specify additional languages, for each output file that the IG publisher creates, it will also create additional fragments with same base file name, with -[lang] appended, in the specified language. This way, authors can build IGs in multiple languages. In this case, the language file will contain additional langauge codes but work as otherwise described above.
Sharing Language Translations Across IGs
Todo. Not sure about this yet
