Standardised API for custom GUI-widgets for openEHR-based form editors & renderers?

erik.sundvall · 13 October 2021 14:53

Most openEHR platform/tooling suppliers with form creation/editing and other GUI-building support will likely need a way for customers to add their own extra custom widgets to forms and some other views - widgets that are not included “in the box” from the platform/product.

I believe at least Better, Cambio, Solit Clouds, Code24 and likely DIPS have thoughts about custom extra widget import or library/store functions, but not neccesarily compatible approaches (yet).

An example of this is Better’s widget store, see image:

Specifying these things is just a narrower openEHR-specific context for the more general need of reusable web app components that has already been solved by “Web Components” standards and could thus likely be reused as is, but perhaps with some naming conventions and expected behaviours defined regarding data in/out, events, config parameters.

Thoughts? Suggestions?

P.S. Context/ background:
When platform customers (like hospitals and health systems) invest thier own developers’ time in creating missing widgets they’d prefer if they can be reused in many vendors solutions. Reusability also makes it more interesting to share the widgets with the world (e.g. as open source) if they so wish - thus adding to the openEHR ecosystem for rapid application development.

erik.sundvall · 15 February 2022 18:01

Nice! Now Better has announced Widget-support officially in EHR studio. And they indeed seem to be web components, as expected above.

@borut.fabjan (or somebody else from Better) - would it be possible to publish the info (or edited versions of it) from the Studio-internal pages…

…here in order to help a discussion on standardisation? Or is ist already published openly somewhere?

Thank you very much for openly providing code to start custom widgets creation with at:

(But the github projects need the great “creating-widgets” explanation to be easily understood.)

Excerpt from announcement mail:

boris.marn · 16 February 2022 13:31

Hey Erik!

Finally I registered here!!

Yeah the first specification is written (and too sparse) and I agree - we need to publish it in our github repository.

We will do it in a couple of days and I will notify you on this form.

The specification we have currently is very basic and there are many other things that need to be implemented.

For widgets specifically we are still lacking:

conditions (when some inputs are mandatory)
language change
input/output actions (widgets don’t have to be only visual presentation)

And the whole idea of marketplace we are currently developing is not only widgets. There are other possibilities as well:

medical functions/calculations
plugins (valida client, mails ending, other integrations, …)

And of course forms, terminologies etc.

Hope it grows to be a fantastic repository with a lot of reusable elements

Sidharth_Ramesh · 17 February 2022 04:01

This is great!

I’m the maintainer of Medblocks UI - a component library for OpenEHR based purely on web components and is open-source. We take some standard props and emit events. We would like to help in coming up with a standardised API.

We’ve used lit-element to build out the components, but once we have an API, it shouldn’t matter.

I’d have a few thoughts and questions:

Are the individual widgets from Better Form Builder available for use outside of the Better ecosystem? For example with a generic form builder application that uses web components? What will be the licensing arrangement?
Can we not limit this to just web components but “any component”? Since there has been a lot of work even towards Flutter components @NeoEHR and Vue components @jessarcher (not sure how it’ll work, but just a thought)

Most of all, I’m worried about the financial and licensing arrangements of such solutions and how the creators of the widgets will be compensated. Having a library of open components will benefit everyone. Especially if we can separate the form building application from the components.

boris.marn · 17 February 2022 08:25

Hey Sidharth.

I watched a couple of your videos - great job!

Currently we wont opensource widgets. We need to think about this - what to opensource, what not.

We didn’t yet do the example for Vue.js - but as far as i understand vue component is a web component is it not? We also need to test Vue.js and see how it works. Ill get back to you.

For Flutter … We hadn’t yet tackled this technology. Not sure how to do it? Flutter can probably create a web component can it not?

There is the idea that some of the content will be payable. So you can use/download them only if you pay. Gives the authors that are creating content ability to get some kind of compensation. Not sure this is the way to go and is not part of the short roadmap.

We can discuss ideas definitely

Sidharth_Ramesh · 17 February 2022 09:47

Vue.js can support custom elements just like React kinda can, but it’s not purpose built for it. There will be some quirks and runtime bundle size will be huge.

I’m more interested in defining an abstract model for how the UI Components can best represent RM types and a uniform way to customise these.

For eg:
In medblocks ui all web components follow this:

data (property) takes the value represented in an element. And this is a different format for each RM type.
mb-input (event) is emitted every time something changes
min, max, required (properties and attributes) for validation values on an input
other additional properties like “showunits” for quantity, “terminology” for codedtext etc.

I feel that the customisation properties can’t be standardised, but the data property (and format for each RM type), event emitted on input change and validation properties can be standardised.

Advantage being web components from multiple parties can be swapped out on demand.

Having uniform styling is still a challenge, but that’s a discussion for another day.

NeoEHR · 17 February 2022 10:32

Data format for each RM element is already standardized in the specifications

This is one way of representing constraints on DV_QUANTITY using only standard RM elements:

"constraints": {
  "value": {
  "occurrences": {
    "_type": "Multiplicity_interval",
    "lower_unbounded": false,
    "upper_unbounded": false,
    "lower_included": true,
    "upper_included": true,
    "lower": 0,
    "upper": 1
  },
  "value": [
    {
    "_type": "DV_INTERVAL<T>",
    "lower_unbounded": false,
    "upper_unbounded": false,
    "lower_included": true,
    "upper_included": true,
    "lower": {
      "_type": "DV_QUANTITY",
      "magnitude": 0.0,
      "units": "mm[Hg]",
      "property": {
      "_type": "CODE_PHRASE",
      "terminology_id": {
        "_type": "OBJECT_ID",
        "value": "openehr"
      },
      "code_string": "125",
      "_code_text": "Pressure"
      },
      "precision": 0
    },
    "upper": {
      "_type": "DV_QUANTITY",
      "magnitude": 1000.0,
      "units": "mm[Hg]",
      "property": {
      "_type": "CODE_PHRASE",
      "terminology_id": {
        "_type": "OBJECT_ID",
        "value": "openehr"
      },
      "code_string": "125",
      "_code_text": "Pressure"
      },
      "precision": 0
    }
    }
  ]
  }
},

DV_QUANTITY data value format is shown in “lower” and “upper” of DV_INTERVAL.

For widgets to be usable in different vendor implementations you also need to standardize the language for conditional expressions (e.g. for show/hide) and scripting (e.g. calculations).

If the expression/scripting language is vendor specific it results in the vendor lock-in.

Ideally the “rules” section of the OPT2 should be used as much as possible. This way forms built on OPTs can be transferred from one implementation to another without much re-work needed.

boris.marn · 17 February 2022 11:27

Advantage being web components from multiple parties can be swapped out on demand.

Yeah. This!

Widget specification we created is not meant only for transformations of RM types.

And it is completely customizable. So there is no restriction what types of events the widget sents and what is the data that it gets.

Here is the first version of specification we use for widgets:

We will update it with the language (web component can be used in different languages), input events etc soon.

erik.sundvall · 5 April 2022 20:32

For some widgets I believe the openEHR AQL response format would be useful as data input (and possibly output) format/API. (Corresponding to the arrow marked “input widget data” in Better’s illustration).

The AQL response format is logically a matrix that can have named columnns and where the cells are filled with primitive or tree-formed openEHR data snippets. The widget could specify what vatiable/column names it expects. Expected table size could also be specified, and needs will vary depending on widget (1x1, 1xN, Mx1, MxN).

Perhaps just the ‘columns’ and ‘rows’ attributes would need to be used?

P.S. Cambio’s form runtime currently uses the AQL response format for carrying data into the form as a whole (e.g. for pre-population of fields). The data does not need to come from an actual query response from a CDR, it could for example come form the surrounding application/context . The suggestion above uses the same principle but in a smaller widget context rather than for the entire form.

Sidharth_Ramesh · 6 April 2022 17:18

Hey @erik.sundvall! Interesting…can you tell more about how Cambio derieves the AQL response format at runtime without querying the CDR?

Also, why? Won’t the composition format be a more natural format to use when we’re in the application context? Why go through the effort of converting it to the AQL response format?

I do understand how some visualization widgets like tables and graphs might want to take in the AQL format as the input format - I’ve always had to parse and preprocess the official openEHR AQL response format before consuming. I find the EhrScape AQL response much easier for consumption!

erik.sundvall · 6 April 2022 18:01

It can be data from anywhere provided by the application surrounding the “Form Runtime” (form renderer). That surrounding application is not necessarily built by Cambio, for example Karolinska builds an application that also talks to a legacy chemotherapy system and our developers can build code that convert legacy data to desired form. The AQL response format is just a list of named columns and can thus be used to provide any kind of data.

Of course other ways to provide contexts with named variables can be invented/used, but for openEHR data the AQL response is something that you’d likely would want to support anyway in an widget framework.