Stream: IG creation
Topic: Auto IG Builder - null error?
Matthew Koch (Dec 26 2018 at 19:57):
Trying out the auto IG builder - But getting an error that content is null. Any ideas? http://build.fhir.org/ig/mattkoch614/fhir-clinical-research/build.log
I'm not running this locally, but instead via the instructions on the public repo: https://github.com/hl7-fhir/auto-ig-builder
Lloyd McKenzie (Dec 26 2018 at 20:14):
Where's your source?
Matthew Koch (Dec 26 2018 at 23:14):
Where's your source?
Sorry, forgot to list here. https://github.com/mattkoch614/fhir-clinical-research
Lloyd McKenzie (Dec 26 2018 at 23:34):
I think you need a minimum of one resource in your IG
Matthew Koch (Dec 27 2018 at 13:33):
If that’s the case it seems easy to remedy. I’ll give that a try. Thanks!
Lloyd McKenzie (Dec 27 2018 at 15:23):
If that does fix the problem, can you submit a change request so we can either remove the limitation or at least spit out a better message when the rule is broken?
Matthew Koch (Dec 27 2018 at 19:41):
Is there a simple way to reference a profile in my IG? Honestly, I can't find a good example. I have a Patient profile .json file I can add to it. Where would it be referenced in ig.json? In the globals section? How do I reference the relative path, if the profile is in a "profiles" directory? Do I need to include the .json extension?
Lloyd McKenzie (Dec 27 2018 at 19:50):
The json configuration file needs to point to the directories to check for the profile and the profile filename needs to be aligned with the profile id (e.g. StructureDefinition-id.json)
Matthew Koch (Dec 28 2018 at 14:11):
@Josh Mandel @Lloyd McKenzie Is ig.json intended to be a valid Implementation Guide resource (https://hl7.org/fhir/2018May/implementationguide.html) or is it merely a configuration file for the build? I might be confusing myself here. Many of the examples listed on the ig-build topic have references to elements that don't appear in Implementation guides, such as "resources", "defaults", etc. Here's one such example: https://github.com/cqframework/qi-core/blob/master/ig.json
Matthew Koch (Dec 28 2018 at 14:24):
I did some more digging and think I may have answered my own question - is it the "control file" that this link describes? http://wiki.hl7.org/index.php?title=IG_Publisher_Documentation#Control_file
Lloyd McKenzie (Dec 28 2018 at 16:26):
Yes - ig.json is the config file. You're really best to start with one of the current IG frameworks than you are to try building your own environments from scratch. There's a huge amount of work that goes into getting things to publish correctly and to meet the HL7 publishing requirements. You can take a look at the structured data capture IG as an example.
Matthew Koch (Dec 28 2018 at 16:42):
@Lloyd McKenzie Thanks...I've been poking around other IG config files to see the structure. I am trying to copy what I can as I work my way though them. There seems to be tooling in place to help with IG creation (Trifolia, Forge/Simplifier, and this IG Publishing Tool) but all of these seem to require some technical chops and significant manual work. I'm not saying this is bad, but I am wondering if there are any initiatives in play around pulling these things together into something more cohesive?
Speaking of which...
@Grahame Grieve I've installed Jekyll on my machine and am attempting to run the FHIR IG publisher. I get as far as when it tries to launch Jekyll, but I always get an error saying it can't find the file. Jekyll is installed at the system level and not in my IG directory.
Error : Cannot run program "jekyll" (in directory "/Users/kochm/Code/fhir-clinical-research/temp"): error=2, No such file or directory
Lloyd McKenzie (Dec 28 2018 at 16:45):
Improving the IG publication process will be one of the major pushes for the new year . We'd hoped to make more progress in the last part of this year but getting R4 out the door consumed all available resources.
Lloyd McKenzie (Dec 28 2018 at 16:45):
What environment are you running the IGPublisher in?
Matthew Koch (Dec 28 2018 at 16:48):
I downloaded it on a Macbook.
Lloyd McKenzie (Dec 28 2018 at 17:05):
@Melva Peters, @Jean Duteau - do either of you know what the trick is to get the IGPublisher to find Jira on a Mac?
Jean Duteau (Dec 28 2018 at 19:05):
are you really asking how to find Jira or how to find Jekyll? When I installed jekyll, I put it in /usr/local/bin and that is a directory in my path, so it is auto-found. basically, you need to be able to run jekyll from the command line for the IGPublisher scripts to be able to run it.
Eric Haas (Dec 28 2018 at 19:07):
you mean Jekyll on a Mac? Its easier than on a PC.
- follow the Jekyll instructions for installing Ruby and Jekyll and confirm that Jekyll works.
- load the latest IG-Pub from here: http://build.fhir.org/downloads.html
- start the IG-PUB from the command line in the directory that contains the ig.json file using
java -jar [path to jar file]/org.hl7.fhir.igpublisher.jar-ig ig.json -watch
(a handy little bash script -assuming you are in the directory for that contains the ig.json file)
#!/bin/bash name="DEQM" path1=[path to jar file]/org.hl7.fhir.igpublisher.jar echo "=================================================================" echo === Publish $name IG!!! $(date -u) === echo see 'local workflow.md' file for how to use echo === create ig.json and ig.xml in $PWD and ../$SOURCE === echo "=================================================================" java -jar ${path1} -ig ig.json -watch
Matthew Koch (Dec 28 2018 at 19:09):
Jekyll works from my command line but not from the (GUI version) of the IG publisher tool. I haven't yet tried the commandline - I'll have to give that a whirl...
Eric Haas (Dec 28 2018 at 19:13):
there several sample ig to get started. I am fond of mine:
here: https://github.com/Healthedata1/IG-Template2
run the IG-PUB and when it gets to here:
es invalid xhtml (0%) (00:01:11.0790sec) ... 25214 links, 28 broken links (0%) (00:01:11.0790sec) Build final .zip (00:01:11.0790sec) Final .zip built (00:01:12.0423sec) Finished. 27.0695. Validation output in /Users/ehaas/Documents/FHIR/IG-Template2/docs/qa.html Errors: 26 Warnings: 28 Info: 0 (00:01:12.0779sec) Checking on package: the file /Users/ehaas/Documents/FHIR/IG-Template2/docs/package.tgz exists = true (00:01:12.0779sec) Watching for changes on a 5sec cycle create package file at /Users/ehaas/Documents/FHIR/IG-Template2/docs/package.tgz create package file at /Users/ehaas/Documents/FHIR/IG-Template2/docs/package.tgz create package file at /Users/ehaas/Documents/FHIR/IG-Template2/docs/package.tgz
open any html file in the output folder and voila....
Eric Haas (Dec 28 2018 at 19:14):
I never used the GUI.
Matthew Koch (Dec 28 2018 at 20:26):
@Eric Haas I will have to give this a try. I've been building up a config file from scratch. Your starter template looks promising! One question, I read in the IG publisher documentation that the "spreadsheet" method of defining profiles is deprecated, can I safely use .json StructureDefinition files for this?
Lloyd McKenzie (Dec 28 2018 at 20:43):
We're working to deprecate spreadsheets, but don't yet have a GUI editor that supports all profiling capabilities, so they're still permitted - you can see an example in the Structured Data Capture project. However, you can certainly use XML, JSON (or I think even RDF) StructureDefinitions if you want to hand-author them or if your profiles fit within the limitations of existing authoring tools.
Eric Haas (Dec 29 2018 at 02:03):
I've used Forge which is a very nice tool and then I can hand edit too. I even generated profiles in json in Python. But I keep going back to the spreadsheet since a) they still work, b) and that is what I am used to.
Eric Haas (Dec 29 2018 at 02:04):
... and I can always ask Lloyd if I have questions.
Matthew Koch (Dec 31 2018 at 14:31):
... and I can always ask Lloyd if I have questions.
Agreed, what a great resource!
Matthew Koch (Dec 31 2018 at 16:23):
@Eric Haas - Thanks again for sharing your template. So far, it's the only one I can find with any sort of documentation I can follow. Do you know of any others out there in the wild? I'm looking for a really bare bones one I can pull down to start...
Matthew Koch (Dec 31 2018 at 16:30):
I also don't see a license, is it acceptable to clone your repo and modify as needed?
Lloyd McKenzie (Dec 31 2018 at 18:00):
Eric's template and my template are the two primary ones. We'll be working on a single standard template as we move to an IGPublisher version that supports templates.
Eric Haas (Dec 31 2018 at 18:32):
yes you can use it and here is a truly barebones IG. https://github.com/Healthedata1/barebones-fhir-ig that works in the latest version of FHIR.
Eric Haas (Dec 31 2018 at 18:35):
to make it pretty you need to look at the Jekyll, and Liquid doco. For adding FHIR artifacts the documentation on the FHIR WIKI: http://wiki.hl7.org/index.php?title=IG_Publisher_Documentation
Melva Peters (Dec 31 2018 at 18:41):
(deleted)
Matthew Koch (Dec 31 2018 at 20:03):
A few more questions now that I've been experimenting with this all day.
1. Is it assumed that a CSS framework is in play such as Bootstrap? Is this customizable? In other words, how opinionated is it when it comes to page generation?
2. Does the Auto IG Publisher tool run Jekyll build/serve commands behind the scenes?
Matthew Koch (Dec 31 2018 at 20:06):
@Lloyd McKenzie What/where is your template?
Lloyd McKenzie (Dec 31 2018 at 20:16):
I don't have an independently published template - but you can see it in use in genomics-reporting, SDC and a few other places. You can leave the "framework" folder totally alone and just change what's in the src folder.
Lloyd McKenzie (Dec 31 2018 at 20:17):
You'll need some sort of CSS to get the fragments to render properly and yes, the IGPublisher runs Jekyll
Matthew Koch (Dec 31 2018 at 20:22):
Thanks all for getting back to me so quickly. I'd be lying if I said I wasn't banging my head against the wall trying to compartmentalize what these tools are doing on my behalf all day - e.g. Jekyll and the IG publisher, coupled with the folder architecture that is necessary.
Matthew Koch (Dec 31 2018 at 20:23):
In terms of CSS, I am seeing a modified Bootstrap theme in use in both yours( @Lloyd McKenzie ) and @Eric Haas templates. Is this what is generally in use or recommended?
Lloyd McKenzie (Dec 31 2018 at 21:20):
There are many different ways to answer that. I've worked with some IGs that have a very different CSS framework that are beautiful and elegant (and cost a fair bit of money to design). However, they're also signficantly different from the FHIR spec and thus less intuitive to navigate. Our intention is to have a standard set of templates used for all HL7 International-published IGs so that they have a consistent look-and-feel and also integrate nicely with the core specification. That said, there's almost certainly room to improve the rendering of the core specification itself. (There's always room to improve almost anything - resources, expertise and time to do the improving are another matter entirely...)
If your intention is to produce an IG for ballot, I'd stick closely to either Eric's templates or mine as it will be simplest to migrate from those to the "official" template once such a beast exists. If you're looking at producing an IG for other purposes, you might still find it expedient to start with one of ours and then expirement and diverge as you become more familiar with how everything is stitched together. It will certainly be possible to migrate anything you might come up with into your own "template" that will separate the complexity of how things are rendered from the management of the resource and page source files.
Eric Haas (Dec 31 2018 at 22:49):
That was inherited from the base specification and is generally what is in use. I went with what was already there
Matthew Koch (Jan 01 2019 at 01:06):
OK all, thanks again. That's it for the day. Happy new year from the USA (NY)
Jose Costa Teixeira (Jan 01 2019 at 16:27):
there is a stripped-down version of one of Lloyd's templates, kind of IG boilerplate, split in 2 parts:
1. the template and publishing stuff needed
2. the base content - the ig.xml and a couple of pages, which then get rendered with the template
Jose Costa Teixeira (Jan 01 2019 at 16:27):
not sure it would help much, since it is broken now with moving to r4.
Jose Costa Teixeira (Jan 01 2019 at 16:29):
i am now getting an error
Unable to parse XML for C:\.....\publish\src-generated\resources\base
(anyone know what would be the reason?)
Jose Costa Teixeira (Jan 01 2019 at 16:29):
Draft documentation is being made for IHE users (i.e. people that should not need to know all about jekyll , they just want to unzip, edit their files and click. We are looking at making a robust template for that purpose
Lloyd McKenzie (Jan 01 2019 at 17:16):
Can you share a bit more from the console?
Jose Costa Teixeira (Jan 01 2019 at 18:19):
[java] Initialization complete (19.0244sec) [java] Load Content (19.0244sec) [java] Publishing Content Failed: Unable to parse C:\HL7\baseIGTemplate\publish\src-generated\resources\base: Unable to parse XML for C:\HL7\baseIGTemplate\publish\src-generated\resources\base (19.0568sec) [java] java.lang.Exception: Unable to parse C:\HL7\baseIGTemplate\publish\src-generated\resources\base: Unable to parse XML for C:\HL7\baseIGTemplate\publish\src-generated\resources\base [java] at org.hl7.fhir.igtools.publisher.Publisher.loadAsElementModel(Publisher.java:2324) [java] at org.hl7.fhir.igtools.publisher.Publisher.load(Publisher.java:1743) [java] (19.0568sec) at org.hl7.fhir.igtools.publisher.Publisher.createIg(Publisher.java:582) [java] Use -? to get command line help (19.0568sec) [java] [java] at org.hl7.fhir.igtools.publisher.Publisher.execute(Publisher.java:526) [java] (19.0568sec) [java] Stack Dump (for debugging): (19.0568sec) [java] at org.hl7.fhir.igtools.publisher.Publisher.main(Publisher.java:4925) [java] Caused by: java.lang.Exception: Unable to parse XML for C:\HL7\baseIGTemplate\publish\src-generated\resources\base [java] at org.hl7.fhir.igtools.publisher.Publisher.loadFromXml(Publisher.java:2405) [java] at org.hl7.fhir.igtools.publisher.Publisher.loadAsElementModel(Publisher.java:2320) [java] ... 4 more [java] Exception in thread "main" java.lang.NullPointerException [java] at org.hl7.fhir.igtools.publisher.Publisher.main(Publisher.java:4935) [java] Picked up JAVA_TOOL_OPTIONS: -Dfile.encoding=UTF-8 -DupdatePublisher=N
Jose Costa Teixeira (Jan 01 2019 at 18:19):
and Happy New Year!
Lloyd McKenzie (Jan 01 2019 at 18:48):
Is it checked in anywhere? (Happy New Year to you as well :))
Jose Costa Teixeira (Jan 01 2019 at 19:16):
just uploaded it
Jose Costa Teixeira (Jan 01 2019 at 19:16):
https://github.com/costateixeira/IGBaseTemplate
Lloyd McKenzie (Jan 01 2019 at 19:53):
Checked it out and ran _genUpdatePublisher and it ran to completion... Perhaps wipe your src-generated folder?
Jose Costa Teixeira (Jan 02 2019 at 05:58):
still same issue. Trying to see what is wrong on my end
Matthew Koch (Jan 02 2019 at 15:17):
@Eric Haas Thanks for that barebones template. It's been helpful - I got it to generate output! Quick question - there's some liquid templating that isn't populated - for example:
© Test IG. FHIR STU3 Candidate (v{{site.data.fhir.versionfull}}) generated on {{site.data.fhir.gendate}}.
in pages/_includes/footer.html doesn't appear to have any data once generated. Where is this variable set?
Matthew Koch (Jan 02 2019 at 15:31):
@Lloyd McKenzie is the https://github.com/HL7/genomics-reporting freely fork-able, modifiable as needed?
Matthew Koch (Jan 02 2019 at 15:44):
[removed]
Eric Haas (Jan 02 2019 at 17:16):
if you look at the narrative in my IG Sampler home pages and profile pages you will see all these parameters defined. This IG is a bit stale and FHIR STU3 but these same parameters are defined for all builds. Additionally there are pages parameters that are defined using the `ig.xml' - I use them to create breadcrumbs an - but they are a bit tricky to implmement using liquid. I can show some liquid that I use to create markdown text....
Lloyd McKenzie (Jan 02 2019 at 17:44):
Yes. It's licensed under cc0, same as all HL7-international-published FHIR IGs. That said, I wouldn't change much in the "framework" folder if you'd like to move to the new integrated template later this spring.
Matthew Koch (Jan 02 2019 at 18:12):
@Eric Haas Thanks. This is helpful. I think this particular topic has been overloaded a bit (my fault) with questions about the IG creation process as a whole, so I will start a new one if I have other specific questions in the future.
Matthew Koch (Jan 02 2019 at 18:17):
Yes. It's licensed under cc0, same as all HL7-international-published FHIR IGs. That said, I wouldn't change much in the "framework" folder if you'd like to move to the new integrated template later this spring.
Thanks. For our purposes, I just removed a lot of the genomics related stuff, created a barebones implementation guide resource with a sample patient profile, and beefed up the README so that I can refer to it later.
Voila!
https://github.com/mattkoch614/fhir-ig-build-template
Last updated: Apr 12 2022 at 19:14 UTC
