Does openEHR recommends to define service APIs using openEHR models as resources/TOs

Implementation
1

This is based on https://twitter.com/gaparv/status/1425471884204855297?s=21 which i mentioned i will raised also in this forum.

This is a question that pops in to my mind when thinking about how OpenEHR can be used best with real world solutions. So my question in what is the recommendation on using OpenEHR models such as Archetype, Composition, Careentry models in business service APIs.

When i say business service APIs, they could be

  • Micro-service APIs which are written for a certain clinical bounded context.
  • Traditional service APIs which are much course grain, but written to handle a certain user case in healthcare setup.
  • A Backend-For-Frontend service which might be used to provide data for a certain specific frontend application.

When considering Repository style services, such as Data Repositories, it make sense that we use openEHR models in those APIs, because the purpose of Data Repository is to read and write data.

But when it comes to above services i mentioned which are remote APIs most of the time, i don’t see why we should expose OpenEHR models because they are very detailed, information rich and very generic. These characteristics makes them weigh heavy. So transferring such heavy structures through the network might not scale well.

The way i interpret is we use OpenEHR to store information, so the data stores are interoperable, basically you can switch your Application layer without one needing to migrate the data to use the different Application implementation. But when it comes to the service APIs which i mentioned above, i would think its best to model your own models based on the use-case, so that you can optimize them.

But when you want to share information with another system, you have the option to share through your Data Repository (Clinical Data Repository) directly, provided that all term bindings and identifiers such as units, providers, patients are externalized. But otherwise you have the option of sharing information using FHIR.

So what i would like to know is, is the way i look at OpenEHR and how to and where to use it is correct ? or am i missing some important points that i should be thinking of when considering OpenEHR.

Thank you.

1 Like
2

AFAIK there is no recommendation on doing such thing or against it. In fact the openEHR REST API spec provides ADL and OPTs.

You are mixing some concepts there. Archeypes and templates are the openEHR model artifacts, which is metadata. A Composition, in the context of an API, is a data instance that complies with a template and a set of archetypes. A CareEntry is one type of Entry that can be included in a Composition.

I would suggest to check the openEHR REST API spec, so if you need to provide any of these elements, that is the way to do it. If you need, for some reason, to create your own API to comply with requirements not contemplated in the openEHR API, then you can provide anything that is needed by your specific requirement.

In any case, this is too abstract, a concrete use case would be useful to discuss specifics.

2 Likes
3

In my understanding, openEHR either has or aspires to provide specifications to build every layer in an EHR system.

  • Archetypes & templates provide the schema definition for repository design
  • Service specification talks about the interface designs for the repository. Apart form the abstract service specification it also includes a concrete REST API specification that can be directly consumes by application
  • Query specification that defines a top level query AQL syntax
  • Other specifications such as Task planning and Decision logic are at different levels of development

So you could build almost all of an entire EHR system using openEHR specifications. Additional interfaces such FHIR can be built as a bridge on to p of an openEHR as required.

I hope that helps

2 Likes
4

Thank you for bringing this up here!

Yes I’m also eager to get more specifics and examples on the usecase of these 3 different kinds of API’s you describe.

And it would help me to understand what kind of app you are building.

The way I see it, from the perspective of an end user of the EHR. For a frontend app that does CRUD on form like data (COMPOSITIONs based on a template modeled using CARE and ADMIN ENTRIES) the api between frontend and CDR should send (operational right?) templates (in JSON) in openEHR format.
For dashboard like frontend applications that display openEHR data (all patients with fever, recent blood pressure measurement of patient Smith), should use AQL queries and results (as JSON) as the format.
Backend services (e.g. billing deduced from ehr data) should probably use AQL as well, but I’ve thought less about this one.
In the perfect world all health apps use openEHR and we won’t need FHIR.
Realistically, applications outside the scope of the users of the EHR (e.g. transferring care from GP to hospital) could transform the openEHR data to FHIR and make the api send FHIR data.

I’m also eager to learn how other openEHR suppliers (Better, patientsky, Cambio, DIPS, tieto etc) look at this problem.

1 Like
5

Thanks everyone for the replies. They are really valuable. I will make a more detail reply with some follow up questions.

The context for my topic was not based on a real world app I’m working on. But this was to understand how we should use openEHR so that i might be able use it in right way in a future project i might work on.

But i will get some use cases for us to discuss from my experience as a patient and engineer where i can see we can use digital solutions. But i need say that I’m not a clinical expert by any mean, so the examples might not be really good.

1 Like
6

You’re thinking in DDD and ~Api Gateway terms (based on your Q). So I’ll try to respond in that context.

openEHR (not capital o btw :wink: ) came to be way before software industry, at least its mainstream chunk arrived at DDD. Even though there’s been various discussions and even ongoing efforts to define services that are closer to particular clinical domains, majority of the API specifications, if one can call the REST spec that, are closer to data, and their semantics do not necessarily overlap with what you’d put into surface of a bounded context. I.e. pushing compositions via rest calls is not probably the API semantics for DDD. The central EHR concept does not define capabilities you’d see in a carefully designed aggregate root, even though it is an obvious aggregate root candidate from a DDD perspective.

So your question, at least for me is how do you do DDD with this thing? :slight_smile: Happy to be corrected if I got it wrong, np.

My response to that question would be: you’d have to change your thinking so that your clinical domain is your bounded context, and openEHR and most of its concepts will become the repository, i.e. a secondary port if you’re also into hexagonal.

There are pros and cons. openEHR is pretty well thought out, so you can actually argue that the complexity and maintenance of a DDD layer on top of openEHR methodology may not be worth the price. As all things do, it depends on the case at hand. The pro is stopping openEHR leaking into other bounded contexts, which is admittedly a problem.

My view is that the idea of a service layer built on concepts closer to clinical domain the solution is targeting than openEHR’s relatively more generic concepts (Compositions, even templates) is a good idea. I’m doing this for at least one Ocean solution. Would I go full DDD? I’m not so sure about that.

Hope this helps.

3 Likes
7

Let me explain more about my question with a use case which i think more suitable for explain my thinking

Lets say i want to build a app which capture patient records at a Out Patient Ward. Where i come from we don’t have proper structured documents which capture out patient information as i know (at least i have not seen). But i assume that there could be several forms which could help to capture the information about the visit. Such as

  • vital signs of the patient
  • social background

and also if the patient has some specific illness or has gone through like Domestic violence then the physician might decide to do some additional documentation about it with some specific form for that.

So for the first part i see we could have a visit archetype template with relevant archetypes. But for the second part we might have a different archetype template.

So now in my hypothetical application, the physician might first document about the visit using the visit template and the additional information will be documented in another patient record using the second template. So i need to provide a way to select relevant template and document in the application UI. For that i need to load archetypes and interpret them in my application to populate the UI if i directly consume Definitions openEHR APIs. Now once the physician has entered data in the UI, the application need to transform the UI data into a Composition and use the EHR openEHR API if i plan to use them directly.

The problem i see with this approach is:

  • Using Archetypes Template make the UI Application to bring down information more than what it needs when considering some meta data those templates has.
  • if we need to use some kind of UI layouting or specific UI controls based on different use cases on top of the template, then the we need to build it separate and perform it on the UI application. (I saw this was implemented as a Form layer on top of templates in one of openEHR demos)
  • The UI Application is totally responsible for creating the Composition structure with all relevant attributes and metadata.
  • Again the structure has more data than what is needed to represent the data we captured.

So i was thinking what if we can defined

  • Our own template entity or Form entity based on archetype template, so it can be configured by informaticians and application admins to looks more user friendly. May be use a more intuitive layout to make the template more presentable. Also this will only contain the essential attributes.
  • Our own entity to capture the information in generic way similar to Composition structure, but not contains all the openEHR attributes, we only capture the data in the UI and some meta information about the form so we can later use that to create a Composition

So these new entities will be implemented by the OP Application Service (DDD speaking these are domain models and what we will use to communicate with client will be some DTO representation of that). And the implementation of this service/domain layer will convert these entities into openEHR models and use a CDR as the repository or infrastructure layer.

So the advantages of this approach is that,

  • We can add workflow support which i don’t see in openEHR spec, for example if some thing recorded by a student physician must be attested by that student and by the physician who he works with. So to do this we need to handle this workflow, so these logics can be implemented in the domain layer.

  • We ca support more form data on top of archetype templates, for example if a certain form allows to attach x-ray reports, then that can be defined in the form layer connected to a archetype entry. The type of capturing application and related meta data can be at the form layer, even multiple options might be in need to be configured to choose from in the UI.

  • Also we could have different APIs from the Application Layer based on the different applications that might be used to capture information. In a highly digital hypothetical environment, a application might offer you to enter quantifiable things into the form directly, while the physician might take digital short note in the same application, which the physician can later translate into proper documentation later by looking at the short notes. These short notes doesn’t need to go into openEHR repository since it will be discarded once the physician is done with the task.

  • For analytics, we could direct query the CDR using a BI tool, may be something like Power BI for example. But if there are more end user application which needs to feed some specific dashboards i would prefer the same approach as above with a BFF.

So as you can see this gives from freedom for the application developers to have more optimized DTOs and that will benefit when the application backend is hosted in cloud where there might be a certain network latency to consider.

Also you can see this type of use case is not so specific for a single archetype based data capturing.

The above use case is something i made up, looking at how my home country (Sri Lanka) hospitals works and what i see as a patient. Hope this will give you some background to my original question.

As @Seref mentioned, my thinking is also in that same description. But i wanted to make sure how others think when using openEHR and what are pros and cons in these different approaches and some practical experiences with the suggestion brought up by others in this discussions.

1 Like
8

Any input on my last explanation?

Hope its clear and gives a better idea about my question.

9

Hi Gayan,

I think your explanation is clear and gives a better idea about your question. I’m eager for the engineers in the forum to give their take.

1 Like
10

If I understand you correctly, you are thinking about an additional level of abstraction between the openEHR apis and the UI application so that the application can be made simpler and reduce the amount of data that the UI has to handle.

From our experience, we feel this may be a good idea if your applications are anything non-trivial. An ‘appserver’ that manages a lot of complexities such as converting simple key-value data from the UI into the openEHR JSOn formats required by the CDR, management of any of the context data in compositions etc.

However if your application is simple and composes of forms that represent simple openEHR templates, then such a layer may add more complexity.

regards

2 Likes
11

Hi Gayan,

this request is something that I agree upon. We need some custom (REST) APIs that only expose the level of complexity that is appropriate as frontend devs often don’t have a specialization in health IT data standards.

This need can be addressed by using some functionality from our Software Development Kit (GitHub - ehrbase/openEHR_SDK). This will allow you to automatically generate a set of classes from Templates. These are human-friendly as the remove many abstractions of the openEHR Reference Model.

These classes can be directly used in Spring Boot to define the payload for a REST API. We built an example application for educational purposes. The payload might look as follows (sorry for the German terms used in this example, the point here is that you have flattened structures with nice labels) for the documentation of a problem/diagnosis:

{
  "language": "DE",
  "territory": "DE",
  "healthCareFacility": {
    "name": "MHH"
  },
  "startTimeValue": "2021-08-19T11:04:20.982Z",
  "settingDefiningcode": "SECONDARY_MEDICAL_CARE",
  "categoryDefiningcode": "EVENT",
  "problemDiagnose": {
    "subject": {
      "name": "self"
    },
    "letztesDokumentationsdatumValue": "2021-08-19T11:04:20.982Z",
    "language": "DE",
    "atiopathogenese": {
      "atiologieDerKrankheit": [
        {
          "value": {
            "definingcode": "ARBEITSRISIKOFAKTOREN"
          }
        }
      ],
      "beschreibungDesEntstehens": []
    },
    "anatomischeLokalisation": [],
    "schweregrad": {
      "schweregradDefiningcode": "SCHWER"
    },
    "diagnosedetails": {},
    "diagnostischeSicherheit": {
      "diagnostischeSicherheitDefiningcode": "BESTATIGT"
    },
    "nameDesProblemsDerDiagnoseValue": "Diabetes Type II",
    "datumDesAuftretensDerErstdiagnoseValue": "2021-08-19T00:00:00.000Z",
    "feststellungsdatumValue": "2021-08-12T00:00:00.000Z"
  },
  "fallidentifikation": {
    "fallKennungValue": "123456"
  },
  "composer": {
    "name": "Birger"
  }

Here you can roughly see the relationship between the form and data format:

image
image1277×890 51.1 KB

The SDK does the translation (in both directions) from the simplified DTO to the openEHR composition in canonical format. You can examine the example in more detail here:

It will also be possible to remove some of the technical fields or those that can be populated by the application backend instead of the user frontend part (like language, territory etc.).

The request URL looks like the following in this example:

http://localhost:8888/api/02a84e08-e8d5-4b49-9664-804e019a14e0/diagnosis

Hope this helps!

1 Like
12

I think there is broad agreement here. Under the hood we are going to be working with standard openEHR APIS and data formats, and for some application / dev partners , this will be absolutely fine. They will have the skills and knowledge to work at that level.

However health data management can get very complex and be overwhelming for third-party devs, so having per-use simplification layers on top of that standard infrstructure is very helpful.

My own interest is in whether GraphQL has a place to play here, as it was developed by Facebook for a similar requirement. A Birger has indicated, the cool thing is that we should be able to auto-generate some of these artefacts from openEHR templates, similar to the ehrBase SDK approach.

In some cases, FHIR-based APIs will be appropriate esp for things like medication, allergy lists but it is often even more complex for other datasets e.g vital signs.

2 Likes
13

Thanks a lot everyone, i think its more clear to me with all different initiatives and different implementations.
For sure i will keep an eye on things like up coming SDK supports, specials projects like what @birger.haarbrandt mentioned.