Stream: IG creation
Topic: Rendering of CapStmts
Saul Kravitz (Nov 30 2020 at 22:26):
After working with @Eric Haas 's Capability Statement tools to generate CapStmts for Plan-Net, Carin-BB, and Formulary, I've gotten used to clear/complete HTML renderings of CapStmts within IGs.
Could use of the Jinja template that is used in Eric's tools to generate the text Div of the Capability statement be incorporated into the standard build IG build process so that all IGs would have clearly/completely rendered CapStmts? (If I understood Python and Jinja better, I'd hand over a script to do this, but the best I can do is to point you to the J2 template https://github.com/saulakravitz/MyNotebooks/blob/saul/CapStatement/R4capabilitystatement-server.j2 and a pure python version of the CapStmt script (https://github.com/saulakravitz/MyNotebooks/blob/saul/CapStatement/R4CapStatement_Maker.py see lines 190-217 ).
Grahame Grieve (Nov 30 2020 at 22:28):
I'm not adding python dependency to the build process
Grahame Grieve (Nov 30 2020 at 22:29):
it looks like it could be a liquid template, which is currently supported
Saul Kravitz (Nov 30 2020 at 22:36):
So it is a "simple" matter of jinja->liquid transformation, and we'd all be reading beautiful CapStmts?
Grahame Grieve (Nov 30 2020 at 22:37):
maybe. What's the difference between what you get now and this one?
Grahame Grieve (Nov 30 2020 at 22:37):
what you get now comes from java code, which would also be improved
Eric Haas (Nov 30 2020 at 23:17):
Liquid template could be added to the build but there is not much value add
to this approach. The liquid templating language is pretty similar but
doesn't support as many filters and python specific methods. I don't know
how the ig-publisher's narrative engine works, but assume is some type of
templating language based on the resource content.
Eric M Haas, DVM, MS
Health eData Inc
35 Crescent Avenue, Sausalito, CA 94965
Saul Kravitz (Dec 01 2020 at 04:50):
@Grahame Grieve compare/contrast ... two different IGs, but even so, the difference in readability is evident.
1) Eric's Jinja output -- https://build.fhir.org/ig/HL7/davinci-pdex-formulary/CapabilityStatement-usdf-server.html
2) Publisher's IG rendering : http://build.fhir.org/ig/HL7/davinci-epdx/CapabilityStatement-pdex-server.html
Grahame Grieve (Dec 01 2020 at 05:03):
this is not really a fair comparison, given the size difference between the statements. I certainly couldn't like to have to sort through 20x the same information wondering whether anything was different between them
OTOH, I could certainly process the markdown...
Grahame Grieve (Dec 01 2020 at 05:03):
I'll do that. Otherwise I'm interested in comments about this
Saul Kravitz (Dec 01 2020 at 13:50):
Agree that it is not a fair comparison.
Saul Kravitz (Dec 01 2020 at 14:26):
@Grahame Grieve - In general, how would you suggest that an IG improve upon the default rendering of resources for its examples?
Food for thought can be found in the RTPBC IG -- https://build.fhir.org/ig/HL7/carin-rtpbc/Claim-rtpbc-claim-03.html -- and the CarinBB IG -- http://build.fhir.org/ig/HL7/carin-bb/ExplanationOfBenefit-EOBOutpatientInstitutional1.html#notes
Grahame Grieve (Dec 01 2020 at 20:35):
in principle there are the following options for this:
- write your own narrative
- propose changes to the general rendering that the IG publisher does
- write your own liquid templates
- submit a liquid template to the core template
Saul Kravitz (Dec 02 2020 at 02:50):
Here is a fair bakeoff, admittedly a bit historical. I struggled to find "good" capability statement examples:
- original VhDir CapStmt as rendered with default rendering. https://build.fhir.org/ig/HL7/VhDir/CapabilityStatement-vhdir-server.html
- re-rendered VhDir CapStmt as rendered with @Eric Haas tools https://healthedata1.github.io/Sushi-Sandbox/CapabilityStatement-vhdir-server.html (Thanks Eric!)
Grahame Grieve (Dec 02 2020 at 20:33):
i'm interested in other people's opinions on this before I invest time in prettifying the CapabilityStatement rendering
Eric Haas (Dec 02 2020 at 20:45):
There are couple of other considerations:
Option of using my Jupyter Binder that can be used to upload your CapStatement and provide the IG package to generate and add this narrative to your CS - its a bit rough and the user interface needs work. (This narrative is focused only on Rest and biased to search and is limited to CapStatements that don't have primitive extensions due the PYFHIR model (hope to get that fixed soon).
See if Sushi wants to integrate it @Chris Moesel ?
The CapStatement is going to undergo radical transformation ( I don't know if there are going to be 2 to choose from or a new one) so the work now may be better spent on the new one.
Grahame Grieve (Dec 02 2020 at 20:46):
I'll still have to maintain publishing on the old one for years, no matter how much it changes
Gino Canessa (Dec 02 2020 at 21:04):
I'd be for some change in default narrative generation for CapabilityStatements. On simple ones (e.g., the one here), the current generated narrative looks like it's wrong / incomplete. I was considering adding the narrative by hand, but getting it to match the template isn't quick work (without a tool like Eric's) and makes it easy to get out of sync.
John Moehrke (Dec 02 2020 at 21:14):
In IHE we are mostly calling for each Actor within an Implementation Guide to be defined by a CapabilityStatement. Thus the dominant case is that a capabilityStatement is used to define an actor... However that is not the full story as for any transaction that is based on query parameters, these are also defined in a capabilityStatement... thus I would like to have at least two different types of rendering of a capabilityStatement.
Saul Kravitz (Dec 02 2020 at 21:16):
Having an easy to read and complete rendering of the CapStmt will increase the probability that the CapStmt gets proper review during the IG development process, and thus increase IG quality. I think it is as essential as the differential views of the profiles for effective review.
Based on my "vast" experience working on 3 IGs (Plan-net, formulary, and carin-bb) my sense is that IG reviewers only read HTML, not JSON. I received zero comments on the v1.0.0 formulary CapStmt (which was poorly done, and has been corrected since), and no comments on the Plan-Net capability statement during ballot, not even a comment "where the hell is your capability statement?", since we didn't have one. On Carin-bb Having a complete HTML rendering of the CapStmt comment enabled reviewers to comment during the reconciliation process.
Jose Costa Teixeira (Dec 02 2020 at 22:32):
an Actor in IHE is a particular case of a CapStatement.
Jose Costa Teixeira (Dec 02 2020 at 22:34):
(the transaction may or not be a capstatement). But there are other cases.
Jose Costa Teixeira (Dec 02 2020 at 22:40):
Should we handle different rendering depending on CapabilityStatement.kind?
Lloyd McKenzie (Dec 03 2020 at 00:23):
If we're going to tackle rendering of CapStatement, it'd be good to think about a modular/plugable way of doing that that reflects the modular/plugable way we're expecting it to work long-term. My initial impression of the revised rendering is that it seems really heavy on "how does search work" and doesn't talk about other capabilities.
Chris Moesel (Dec 03 2020 at 01:37):
@Eric Haas -- regarding SUSHI integration of CapabilityStatement (or CapabilityStatement2), our thinking is that the parameterized rulesets (proposed for FSH STU2) will actually mitigate the need for a special FSH syntax to support CapabilityStatements (and other not-yet-FSHified conformance resources). See the Wicked Fish slides for an example of how parameterized rulesets can be applied to the current CapabilityStatement resource. I expect (or hope) that something similar would apply to any other changes in CapabilityStatement.
Eric Haas (Dec 03 2020 at 03:08):
I was thinking of integration of Jinja2 or othe rendering templates for the completed CS to generate pretty narratives.
Eric
Eric M Haas, DVM, MS
Health eData Inc
35 Crescent Avenue, Sausalito, CA 94965
Eric Haas (Dec 03 2020 at 03:22):
@Lloyd McKenzie your stylesheet was the inspiration and starting point for this template
Lloyd McKenzie (Dec 03 2020 at 04:22):
I would like there to be one language that we use to write renderers in. Given that we already use liquid, my preference would be to stick with that (and perhaps add a few plugins to add extra capabilities). What I don't want is some IGs or templates that use Liquid, some that use Jinja, some that use XSLT, some that use something else. So lets figure out the desired feature set of what the renders need to be able to do and choose the minimal technical solution that will enable that - and then use it for everything.
Grahame Grieve (Dec 03 2020 at 20:09):
let me know what you think can't be done with liquid
Eric Haas (Dec 03 2020 at 20:37):
Getting the links correct would be the trickiest part for me. I render using mapping files I derived from the package. which means the CS narrative is generated after the build is created. So is much easier to do it outside the build....
Eric Haas (Dec 03 2020 at 20:38):
I create the CS and narrative in one go
Grahame Grieve (Dec 03 2020 at 20:59):
much easier to do it in the build where you can delegate the links to the publisher
Lloyd McKenzie (Dec 03 2020 at 23:45):
Build creates zips. So it needs to be done as part of the build
Saul Kravitz (Dec 08 2020 at 19:59):
Current approach: Build with everything but the capstmt, get the mapping files from the build, update capstmt, rebuild.
Last updated: Apr 12 2022 at 19:14 UTC
