Best practice for updating templates

Hi all,

I’m new to openEHR and have been playing around with ehrbase. I am wondering what is the best practice for updating a template that has been uploaded to an openEHR server.

I have noticed in the REST spec that there is no DELETE or PUT/PATCH endpoint for templates, and in my experimenting with ehrbase it prohibits me from uploading a template with the same template_id. My impression is therefore that templates can not be deleted or updated and the template_id must be unique (makes sense).

From looking at other templates and archetypes I named my test template ID acme.test-consult.v0(i.e. including the major version but omitting the minor and patch) however in order to make a change it seems I need to change the template_id. Should I put the full semver-style version as the template_id? E.g. acme.test-consult.v0.0.1? I haven’t seen the full version name included in any other example, but it’s the only way I can seem to upload a new version of an existing template. I noticed that a lot of archetypes have a revision field that contains the full semver-style version, however ehrbase at least does not seem to look at this.


Hi @jessarcher,

we are currently working on the Admin API in EHRbase that will allow you to delete and update Templates. There is also a spring configuration that allows to simply overwrite templates with the same ID. You can find this one in the application.yml


or you provide it as a parameter if you are using Docker:


Using semver-style is advised. When overwriting templates the challenge is to ensure it is backwards compatible and EHRbase unfortunately does not have these checks in place at the moment (I think the Clinical Knowledge Manager has some means to distingush between minor and breaking changes).

Hope this helps!

1 Like

Hi Jess,

Welcome - good questions and I agree with Birger’s response. We figured out how to apply the server config to a Docker install so let me know if you need any advice on that.

Quite clearly, once we are in a production phase, we really need to keep tight control of versioning, so not allowing updates via the REST API makes sense but this is pretty burdensome when in the development stages, particularly if one is rapidly iterating the UI and making changes to the template in response, or (as in the CVID scenario) where the template is changing fairly regularly in response to fast-moving requirements changes.

The semver numbering approach has served us well for archetypes but for various reasons has not yet been applied to templates. However, I think the general approach should be the same (certainly my policy) - add the Vn major version number to the templateId.

You can add minor and patch numbers to the templateID but you then get into problems of making it difficult to apply non-breaking changes. I think the principle that we applied for archetypes is best. Use a separate semver number to manage more subtle changes.

When we finally get moved to ADL2 for templates there is a formal place for semver , but we don’t have this now in the .oet/.opt files. I think it is time for us to agree on adding that as a ‘standard’ annotation
which would allow the semver to be carried until such time as we make the jump to ADL2.

and welcome to the community :slight_smile:

1 Like

One general request for feedback: we are currently implementing the delete template function in a way that we forbid it as long as templates are still being referenced by compositions.

Furthermore, we are thinking about a mechanism that provides versioning on templates similar to versioned objects in openEHR. This means that updating means not overwriting but creating an active version and still keeping track on the previous versions. This way, it is possible to re-create the state of the database at any point in time regarding the template used. Good idea, or do you think this is not too useful in reality?

Thanks for the great responses Birger and Ian :slight_smile:

I imagine Ian will have far more insightful feedback, but I can provide my early perspective.

With regards to deleting - the rule you’ve outlined sounds great, although I don’t currently have too much of a use case for deleting templates, especially with the overwriting functionality that you’ve previously mentioned.

I am very interested in template versioning and having the ability to upload new versions of templates. Both with backwards compatible changes, but also with breaking changes. Similar to the archetypes on CKM.

I have been involved with creating clinical forms and am currently investigating how openEHR might fit for us. I’ve witnessed a lot of change requests to our forms (mostly during UAT, but sometimes after launch as well) and I am trying to work out how best to handle that with openEHR when the form change requires a change to the underlying template.

I’m still in the proof-of-concept phase though. So I’m not sure yet how problematic it would be to just include the full semver in the template_id and effectively create a new template for every change. I’d just need to make sure that all new compositions use the new ID.

From an AQL point of view I think I should still be able to run queries like “give me all the blood pressure readings for an EHR” regardless of what template was used when the data was recorded.

What Birger has proposed is a great approach. That way the older versions will not be actively available, but still will not break any data already in the CDR.

  1. Delete only if no reference in any composition
  2. Version update for those in service already so that old version is not in service anymore, but available in the system.