openEHR Tooling: A Comprehensive Guide - Introduction
[!warning] DRAFT - Work In Progress
This series is intended to help new openEHR community members navigate the complex world of openEHR tools. It is a work in progress and may contain inaccuracies or outdated information. Please advise the author of any amendments or corrections by replying to the Discourse topic where this is posted, ideally supplying a suggested alternative form of words.
[!info] Tooling changes frequently
The openEHR tooling landscape changes frequently. Always cross-check against openehr.org/modelling-tools and the openEHR Discourse forum for the latest status.
If you see errors in these Wiki guides, please comment so that we can update them.
openEHR Tooling and Software overview
openEHR has accumulated tools over more than twenty years. Some are still the recommended choice. Some are deprecated but still downloadable and occasionally referenced in older tutorials. Some are commercial products that sit on top of open foundations. This guide tries to be honest about all of them in one place.
Tools are grouped by purpose, because that is how most people approach this: they want to author archetypes, or design templates, or run a clinical data repository, or query it.
This guide is split into separate Discourse Topics to make them a little more manageable:
Before surveying tools, it helps to understand what each tool category does:
Archetypes
are reusable clinical content models written in ADL (Archetype Definition Language). They define what clinical concepts mean and what data they hold (e.g. âBlood Pressureâ or âBody Weightâ). Archetypes are shared internationally via the CKM. Archetypes are intended to be (primarily) clinically authored, using clinician-friendly GUI tools.
Templates
assemble archetypes together for a specific clinical use case (e.g. an ED discharge summary). A template can be localised or use-case-specific. Templates are also authored using GUI tools and stored in a CKM.
Operational Templates (OPTs)
are the compiled, flattened output of a template, exported from a CKM and consumed by CDR platforms and form renderers.
CDRs (Clinical Data Repositories)
store actual patient data in openEHR format and expose it via REST APIs and AQL queries.
Archetype Definition Language versions
ADL 1.4 vs ADL 2 - ADL 1.4 is the current workhorse version, universally supported. ADL 2 is the newer specification that unifies archetypes and templates into a single formalism and is progressively gaining support, but is not yet universally deployed.
This is a bit of a âstarterâ attempt to create a Wikified entrypoint which we can build on. Feedback welcome. I have rough draft content for each of the sections enumerated above, but will post them one by one so I can edit for style and triple-check the details for accuracy.
@SPB as mentioned in the meeting I have started work on this overview, which aims to clarify for new developers/clinicians what tooling is available, what each thing does, and which tools are considered the âindustry standardâ vs which ones are legacy/deprecated.
I was thinking to start out first with an inventory of everyting akin of an excel sheet, so it would be easier to filter and distribute the review work.
But if we are comfortable to dive right in the more âhuman-readableâ format, you can count on me to review the lists of applications/software/scripts.
Excel sheets are a disaster area for text. Iâm happy for other people to collate a spreadsheet from this data, but I will be continuing with a text-based series of articles.
@marcusbaw I know Discourse will be up for what are you proposing with wikified page set - but I was wondering what is your opinion on having a static website, rendered with mkdocs on github pages, based on markdown sources? it is also a âwikiâ, easy to maintain, version control, cheap and easy maintenance, visually customisable.
Yes, a static documentation site based on Markdown source could be a better fit for what we want to do than Discourse is.
The reason I didnât suggest it initially was that I didnât want to start by suggesting yet another now toolset/platform, when we already have Confluence and Discourse.
However, it could be argued that a static generated site is just leaning more into our existing GitHub presence.
Very happy to go with the static site idea - I have extensive experience with static documentation sites using Material for Mkdocs or Zensical frameworks - but the choice of framework is immaterial as long as the source is in Markdown, itâs easy to switch framework. I know youâve used Antora a lot, sadly I have no experience with it but Iâd give it a go since all openEHR specs are in Antora already.
No, Antora would be too complex for this.
Markdown on github, with static build with Mkdoc is much easier to manage and sufficient for the job, in my opinion.
I think everybody here knows markdown and static pages. I personally donât know Material for Mkdocs or Zensical but I guess with markdown knowledge itâs easy to handle. Let the group decide. Also open for Github pages.
This may be my newcomer brain speaking, so please season generously with salt, but I wonder if there are two slightly different audiences being discussed here: the people maintaining the documentation and the people trying to read and learn from it.
From a maintenance perspective, Markdown in GitHub sounds sensible. My only hesitation is around the reader-facing experience, especially for newer users (like myself) who may not be as familiar with GitHub, Markdown, or the many acronyms floating around.
If the GitHub side is mostly the backend/source of truth, and the output is a well-structured, searchable, visually friendly documentation site, then that seems like a good direction. But I think the success would depend heavily on how beginner-friendly the published site is: clear navigation, introductory pathways, glossary/appendix, and key Discourse learnings surfaced somewhere more permanent.
In other words, my concern is less âGitHub badâ and more âplease donât make the learning curve wear a disguise and call itself documentation.â
Apologies if this has already been covered elsewhere. Iâm still deep-diving through Discourse and have accepted that I may emerge in approximately 2037.
Well put @sheeren.khalifa. I think from my understanding of the proposed solutions the rendered git approach would deliver the user friendly interface youâre hoping for. e.g. https://www.mkdocs.org/ is itself built with Mkdocs, with its source editable on Github.
I like @joostholslagâs suggested approach of it being open source itself, where we could have maintainers that could approve any proposed changes through a pull request flow.
Totally hear this @sheeren.khalifa and the aim will be to make readable, accessible, and less technical documentation than we had before.
Iâm fine with any Markdown-on-Git based approach - it gives us simple editable source and it can be presented in a range of ways (even multiple ways from the same source).
Equally nice is a new framework my son showed me this week called DocMD which is popular in the Rust community.
The difference between all of these is just a few lines of configuration, because for the most part they all consume Markdown as source. If we go with that, we can use anything we want, we can change in the future. It doesnât matter all that much as long as what we produce is readable, well written, and helpful.
On a side note, I found this PGx modelling page really interesting. I worked on similar modelling in my previous role, where we broke things down in more detail using real PGx reports, so it definitely sparked a lot of thoughts and questions for me.
I can see a few ways this could potentially be made more granular to improve data structuring, although this would depend on the use case ofc, but I wonât go too deep here as I donât want to add too much noise to the thread. Thanks again for sharing.