Stream: ihe
Topic: IHE IG needs
Jose Costa Teixeira (May 07 2018 at 10:59):
Looking at a way that IHE can use the IG publisher (independent of frontend for editing and output)
Jose Costa Teixeira (May 07 2018 at 11:05):
First thoughs - hoping to define what are our artefacts and structure for IG publishing.
Looking for input . @John Moehrke @Elliot Silver, others:
1. Each editor may have "local build"; each domain may have their "official build"; ihe HQ runs a main (/"trunk") build. This separation is covered by the fact that each of these actors has their build.
1.1 We'll need to (later) discuss how to synchronize content.
2. Framework should remain "hidden" from editors - as an editor, i don't need to maintain any templates or configs. These are managed centrally. IHE IG requirements
Grahame Grieve (May 07 2018 at 12:42):
ihe should define a single template (this is a new IG publishing thing I am introducing this week)
Jose Costa Teixeira (May 07 2018 at 12:44):
are there examples or specs of structure for the templates?
Jose Costa Teixeira (May 07 2018 at 12:44):
these links are not working :
http://wiki.hl7.org/index.php?title=FHIR_IG_publisher_templates
Jose Costa Teixeira (May 07 2018 at 12:45):
so far i have worked mostly with Lloyd's SDC2 template
Grahame Grieve (May 07 2018 at 13:09):
http://wiki.hl7.org/index.php?title=FHIR_IG_publisher_templates - oh that's the link - should be working
Grahame Grieve (May 07 2018 at 13:09):
Lloyd and I will be moving that to an actual template this week. There's no examples yet because I only wrote the doco a few hours ago - see
Grahame Grieve (May 07 2018 at 13:09):
but no examples, unless you count https://github.com/FHIR/test-template but that isn't working yet - work for me in the next couple of days (only a few hours a day while we travel)
Jose Costa Teixeira (May 07 2018 at 13:10):
Thank you. Absolutely no rush - just wanted to catch up.
John Moehrke (May 07 2018 at 13:11):
We do have a word template that we use for current text writing. It would be good to walk through that and define the IG publisher template equivilant.
Jose Costa Teixeira (May 07 2018 at 13:11):
Yes, @John Moehrke i am basing a structure of the pages in the current IHE template.
John Moehrke (May 07 2018 at 13:12):
see ftp://ftp.ihe.net/DocumentPublication/DocumentTemplates/Technical_Framework_Supplement_Template/
Jose Costa Teixeira (May 07 2018 at 13:13):
I believe the IG templates will be about the framework - which artefacts go where, which transformations are needed...
Jose Costa Teixeira (May 07 2018 at 13:18):
After we define the page structure (the ToC from the template seems a good starting point), we need to make further decisions:
These pages can be based on html templates or boilerplates - which are governed centrally. So when an editor wants to work, they need those templates to be there.
Jose Costa Teixeira (May 07 2018 at 13:19):
and what would be the folder structure for these? I am guessing as an editor I'd have a folder for templates and another for "my" content.
Jose Costa Teixeira (May 07 2018 at 13:20):
and in another folder, the editor will put the conformance resources (@John Moehrke you know what is needed there)
Jose Costa Teixeira (May 07 2018 at 13:20):
and possibly in another folder, the images.
Jose Costa Teixeira (May 07 2018 at 13:21):
(that is what I understand by "a template for the IG publisher")
Jose Costa Teixeira (May 07 2018 at 13:31):
IHE would possibly need templates for(a first guess):
- Actors
- Glossary (using valueset?)
- content profiling (using structureDefinition)
- Transactions
- workflow profiling (using planDefinition)
- use cases (using exampleScenario)
Grahame Grieve (May 07 2018 at 13:35):
the template will also define the overall look and feel and content layout - so very much what this is about
Jose Costa Teixeira (May 07 2018 at 13:38):
that is the css, the includes, all things jekyll, correct?
John Moehrke (May 07 2018 at 14:18):
yes, that is why I pointed at the current word template. as it holds not just the list of sections, but also critical instructions to the profile editor on what needs to be in that section.
Jose Costa Teixeira (May 07 2018 at 15:36):
Cool. I'm trying to get my IG back to life.
Jose Costa Teixeira (May 07 2018 at 15:36):
How about an IHE-focused discussion of this in Cologne? then we can see what is there, what do we need.
I can bring the (belgian) beers.
Michael van der Zel (May 09 2018 at 13:27):
N.B. There is a BoF about testing. Anyhow I would like to join the IHE IG discussion. When is it?
Elliot Silver (May 10 2018 at 03:59):
I'm not going to Germany to drink Belgian beer.
I'd like to avoid any need for a local environment -- it will be too complicated for most authors, and some are prohibited by corporate policy from installing unapproved software, which essentially means we are limited to word and a browser.
Jose Costa Teixeira (May 10 2018 at 06:34):
Hi @Elliot Silver Good requirement (i mean the one about local environment). Is it a hard requirement? If so, even a standalone simple tool like Forge is also out of our range, no?
Michel Rutten (May 10 2018 at 10:06):
Providing a profiling tool as a browser-based application would lower the barrier. However given the considerable amount of time and effort our company has invested into the development of Forge, funding a complete re-implementation would be a bit of a stretch... not too mention the development time.
To mitigate the pain, we try to make the installation as easy as possible, i.e. no admin permissions required. You can also run Forge on Linux/Mac using WINE. And our commercial customers also have access to stand-alone binaries, for in case company policy prevents the use of ClickOnce installers.
Jose Costa Teixeira (May 10 2018 at 10:08):
thanks @Michel Rutten Glad you are ahead of the curve.
I don't think the requirement is a hard one. But we may need to provide a workaround for those behind extreme constraints.
Michel Rutten (May 10 2018 at 10:17):
Indeed, I am aware of big enterprise constraints... ;p David Hay's ClinFhir tool provides a web-based alternative. David's tool is designed for a slightly different audience, but it supports the most frequently used profiling operations.
Jose Costa Teixeira (May 10 2018 at 10:19):
From an IHE perspective, I would not sacrifice the usability of Forge. So I would not say we have to avoid a local environment.
Possibly what @Elliot Silver was looking at is that the expression "local build" may still seem scary.
John Moehrke (May 10 2018 at 11:50):
The benefit of using standards is that both tools read/write the same content. Thus one editor can use a diffeent tool than another editor, and future fixes can use a future tool. Thus tool selection is less of a critical factor. Tool usability is still important.
Elliot Silver (May 10 2018 at 13:08):
Yes, probably not a hard requirement. InstallIng a single commercial product is probably ok. Installing a collection of open source tools is probably not.
My concern isn’t about what can be installed without admin rights, but what corporate policy allows. We had one author in the past who’s company had a whitelist of apps, and anything not on the list was essentIally forbIdden It just wasn’t worth the effort to get somethIng approved for one person, especIallty If they are a onw tIme author.
John Moehrke (May 10 2018 at 13:15):
and... open-source is not a free ticket. Some companies forbid even open-source tools.
Jose Costa Teixeira (May 10 2018 at 13:18):
as I expected.
Michel Rutten (May 10 2018 at 13:19):
Then fortunately, Forge is freeware, not open source ;p
Jose Costa Teixeira (May 10 2018 at 13:20):
I did not see any mention for installing open source.
But if that were ever a requirement, it's very easy to fix.
Jose Costa Teixeira (May 10 2018 at 13:25):
I don't think IHE should require an online tool.
John Moehrke (May 10 2018 at 13:26):
What it means is that any tool must be carefullly checked with the community. Trying to get a yes/no list is not possible.
Jose Costa Teixeira (May 10 2018 at 13:27):
the only tool I used for the example I sent is the IG Publisher.
Jose Costa Teixeira (May 10 2018 at 13:28):
(well, i hacked it a bit with other stuff, but that should not be an issue)
Jose Costa Teixeira (May 10 2018 at 13:28):
and at this moment, getting the IG to produce something does not require installation.
It's download, double-click.
Jose Costa Teixeira (May 10 2018 at 13:29):
if we want editing to be a collaborative effort, we will have a broader set of issues like access to shared content.
Jose Costa Teixeira (May 10 2018 at 16:20):
I don't think we should put much effort now for questions putting like some users not being able to use open source.
What I am next concerned about is how to split the template across:
1. Things that are owned by (IHE) HQ (the framework, UI templates)
2. Things that an editor changes for his/her profile
3. Things that are changed across profiles and an editor needs to incorporate (e.g. an actor needing to reuse actors, or glossary entries)
...?
Any other way we need to split this?
Jose Costa Teixeira (May 11 2018 at 06:26):
@Michael van der Zel we haven't scheduled it yet but I think a work session would be great.
Jose Costa Teixeira (May 11 2018 at 06:35):
Perhaps a lunch session? I think your input will allow us to advance a lot
Jose Costa Teixeira (May 25 2018 at 11:35):
If we want to publish only the conformance artefacts , which would make more sense to most people? Assuming that people already made the conformance resources, and that the display could be thus: http://zeora.net/blog/mma/artifacts.html
What is best approach?
1. For each profile we edit an excel where file we list the conformance artefacts that they want to publish, and in which section (profiles / conformance statements). We can define any sections ("profiles", "conformance statements", "smurf", anything). Publisher does the rest.
2. Just put the files in a folder and the publisher simply takes all the files in that folder and publishes them in a section that is determined by the resource.
Jose Costa Teixeira (May 28 2018 at 05:26):
We will discuss this on wednesday during the call. Meanwhile I can try to start with the spreadsheet so that we can see something working.
John Moehrke (May 29 2018 at 13:58):
We have a solution for publishing the conformance resources. We need something better. See http://wiki.ihe.net/index.php/Mobile_access_to_Health_Documents_(MHD)#FHIR_Implementation_Guide
Jose Costa Teixeira (May 29 2018 at 14:05):
My question is precisely about the 'something better's :) . I will start with the spreadsheet option
Oliver Egger (May 29 2018 at 21:03):
one step to go in the direction from something better would be to use IG templates (see http://wiki.hl7.org/index.php?title=FHIR_IG_publisher_templates). It is already mentioned "ihe" (todo): the standard template for IHE-published implementation guides. Did already anyone experiment with a template layout for IHE?
Jose Costa Teixeira (May 29 2018 at 21:03):
yes, that is exactly what i am experimenting with :)
Jose Costa Teixeira (May 29 2018 at 21:04):
starting with small steps
Jose Costa Teixeira (May 29 2018 at 21:04):
but walking towards an ihe template
Oliver Egger (May 29 2018 at 21:10):
@Jose Costa Teixeira why you wan't to control that through a spreadsheet?
Jose Costa Teixeira (May 29 2018 at 21:13):
ah, that.
Jose Costa Teixeira (May 29 2018 at 21:14):
Currently IHE has a few profiles that are simply lists of conformance resources. I want to start by taking those up and allowing those to be published.
Jose Costa Teixeira (May 29 2018 at 21:14):
so, easiest is to inject them in an IG.
Jose Costa Teixeira (May 29 2018 at 21:15):
and to do that, our users would either a) learn how to do the XML stuff. b) wait for a nice User-friendly tool (wait for it...) or c) use a spreadsheet.
Jose Costa Teixeira (May 29 2018 at 21:15):
so it is just a way to create a publication package that, in this very early step, just takes the currently available materials.
Jose Costa Teixeira (May 29 2018 at 21:16):
(hence the emphasis on "first step")
Oliver Egger (May 29 2018 at 21:28):
i actually made that first step for the ihe mhd conformance resources, but by hand :-) IG publisher has naming conventions for id/filenames so you will probably need to do some preprocessing of the input conformance resources, I will try to figure out if this can be done with the Active Scripts or if it is too late in the process
Jose Costa Teixeira (May 29 2018 at 21:29):
this preprocessing was my other option
Jose Costa Teixeira (May 29 2018 at 21:31):
I did point out the conflict between the ig convention and the naming convention that ihe adopted for the short term.
but we can always change that
Jose Costa Teixeira (May 29 2018 at 21:32):
active scripts - you mean the windows scripting thing?
Jose Costa Teixeira (May 29 2018 at 21:39):
for preprocessin gi would prefer the mechanisms in lloyd's template - provided he does not change those too much
Oliver Egger (May 29 2018 at 21:41):
No actually they are ant scripts (title of the section in http://wiki.hl7.org/index.php?title=FHIR_IG_publisher_templates is Active Scripts :-))
Jose Costa Teixeira (May 29 2018 at 21:41):
ah ant is what Lloyd's template uses
Oliver Egger (May 29 2018 at 21:42):
do you have a link to llyod's template?
Jose Costa Teixeira (May 29 2018 at 21:43):
ant is the thing i will play with.
idea is to convert XLS into an IG by using an XSLT.
Jose Costa Teixeira (May 29 2018 at 21:43):
afaik, Lloyd's template is still the one you get in the FHIR build, under guides\sdc2
Jose Costa Teixeira (May 29 2018 at 21:44):
(not really a template, but gets us going)
Jose Costa Teixeira (May 29 2018 at 22:23):
ah important point: that may not work with the new ig publisher.
Jose Costa Teixeira (May 29 2018 at 22:24):
tomorrow i will post a small ihe template that works with the new version, and is based on that template
Jose Costa Teixeira (May 29 2018 at 22:26):
i will use my current sandbox: https://github.com/costateixeira/fhir_ig_publishing
Jose Costa Teixeira (May 29 2018 at 22:30):
perhaps i should create another thing and get rid of the glossary and examplescenario for now
Jose Costa Teixeira (May 30 2018 at 18:36):
there:
Jose Costa Teixeira (May 30 2018 at 18:36):
https://github.com/costateixeira/IHE_FHIR_IG
Jose Costa Teixeira (May 30 2018 at 18:36):
this does not have glossary or exampleScenario
Jose Costa Teixeira (May 30 2018 at 18:36):
but does render a nice simple set of pages.
Jose Costa Teixeira (May 30 2018 at 18:36):
It can be used with the existing IHE conformance resources but some updates are needed (on those resources)
Jose Costa Teixeira (May 30 2018 at 22:33):
IHE boilerplate template is updated - (updated readme). Anyone interested: Have fun and let us know how it works and what we should work on next.
Jose Costa Teixeira (May 30 2018 at 22:34):
in a few sprints from now we should start publishing this somewhere (even if manually) so that we are one step closer to Continuous Delivery.
Jose Costa Teixeira (Jun 04 2018 at 22:14):
Suggestion for a requirement, taking IG Publisher as base:
It's normally good to use the latest IG Publisher. Using Lloyd's template does that automatically.
However, in IHE we may want to get only verified versions to avoid any regressions, right? So that when the IG Publisher gets an update, first IHE tests whether that still works with the rest of the template
John Moehrke (Jun 05 2018 at 13:54):
possibly true, but that is a bit of governance concern that is far downstream.
John Moehrke (Jun 05 2018 at 13:55):
What it brings to mind is that at some point IHE would need to have Validation criteria and automated test to those criteria. It is those criteria that are the critical point today
Jose Costa Teixeira (Jun 05 2018 at 14:07):
Not sure it's far downstream. I already had issues because of one version of the IG. Anyway, a backlog item is a backlog item. It is not to be resolved fully and immediately, but to be addressed.
Jose Costa Teixeira (Jun 05 2018 at 14:09):
By criteria, you mean past discussions that we should define what is considered a "valid" / "complete" profile?
I think we have suggested having a set of mandatory things without which the "IHE profile" would be complete or not.
Jose Costa Teixeira (Jun 05 2018 at 14:10):
i think one example was "if all glossary terms are valid"
John Moehrke (Jun 05 2018 at 15:38):
right... like all terms in the produced text that are found in the glossary are automatically linked to the glossary definition... there must be hundreds of these kind of requirements.
Jose Costa Teixeira (Jun 05 2018 at 15:40):
yep, let's build up those requirements. At this moment the only requirement that is completed is:
"there must be some conformance resources".
Jose Costa Teixeira (Jun 05 2018 at 15:44):
the glossary requirement was to link the local glossary to global glossary. example, if a IHE Pharmacy profile defines "prescription" and if that definition has not been harmonized with the way than IHE defined "prescription", this would show up.
John Moehrke (Jun 05 2018 at 16:20):
We do have a set of requirements we are building in spreadsheet -- https://docs.google.com/spreadsheets/d/1YAPlRNQEw-MZ0R0rI10IP2LxHFkKlBgbwCmogYD1rfg/edit?usp=sharing
Jose Costa Teixeira (Jun 12 2018 at 08:02):
Here's one thing that I completely overlooked: to run the IG we need jekyll which needs ruby.
Jose Costa Teixeira (Jun 12 2018 at 08:03):
I will update the IG build template with a portable Jekyll/Ruby stack - this is tested and runs on windows.
Jose Costa Teixeira (Jun 12 2018 at 08:04):
not sure how we would handle this on Mac or other Unix / linux
Jose Costa Teixeira (Jun 12 2018 at 08:04):
in the meanwhille @Michael van der Zel this may be an opportunity to have the build service run in a server soemwhere, leaving people only with their content.
Grahame Grieve (Jun 12 2018 at 09:44):
we've pretty much done that - there's a web server that runs the build. but it's languishing in the land of not enough interest
Jose Costa Teixeira (Jun 12 2018 at 09:46):
Grahame Grieve (Jun 12 2018 at 09:46):
yes that would be it
Jose Costa Teixeira (Jun 12 2018 at 09:47):
i saw it but was not sure what should be in the zip. the src folder? the entire thing? just the ig?
i would definitely rather reuse it than get something else.
Jose Costa Teixeira (Jun 12 2018 at 09:49):
What I would imagine is that we have a template that people only need to upload the files that an editor would work with (IG + images + pages + resources)
Jose Costa Teixeira (Jun 12 2018 at 09:51):
the framework (templates, logos) could be uploaded by IHE HQ, and it can reside in a repo somewhere, or be also uploaded every time (but it is redundant and is not small)
Jose Costa Teixeira (Jun 12 2018 at 09:51):
so, an editor would upload the src folder to the "build" server. the rest already exists there or is fetched any time.
Jose Costa Teixeira (Jun 12 2018 at 09:52):
i am guessing that the latter is trivial for ant.
Grahame Grieve (Jun 12 2018 at 10:10):
you'd upload a zip that contained the root, pages and resources folders.
Grahame Grieve (Jun 12 2018 at 10:10):
template would be fetched on the server side
Jose Costa Teixeira (Dec 14 2018 at 13:43):
I will give the publisher a try.
Jose Costa Teixeira (May 06 2020 at 07:11):
Just a positive note - this thread started 2 years ago tomorrow, and I think we've come a long way already. :)
Last updated: Apr 12 2022 at 19:14 UTC
