DRAFT: Introduction (openEHR Tooling Overview series)

Software Program - open
1

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:

  1. Introduction and key concepts (you are here)
  2. Archetype Authoring Tools
  3. Template Authoring Tools
  4. Clinical Data Repositories (CDRs)
  5. Knowledge Management and Repositories
  6. Developer Tooling - SDKs, Libraries and Extensions
  7. Query Tools, Form Builders and Clinical Decision Support
  8. Deprecated and Obsolete Tools
  9. Quick Comparison Table and Where to Get Help

Key openEHR terms and concepts

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.

Next: Section 1: Archetype Authoring Tools

2

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.

4

@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.

Am I on the right track here?

5

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.

6

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.

7

Agreed! Lets all work on the official text-based documentation.

8

Can we reuse the open source practise of the list of amazing for x on GitHub?

Explaining all the formats and language seems more of a specs and educational effort seperate from a tooling list to me.

9

@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.

10

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.

11

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.

But it is up for the group to take a direction.

12

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.