-
Notifications
You must be signed in to change notification settings - Fork 111
Template Management (from EHRServer v1.3)
OPTs have two types of identifiers, the technical identifier (UID) and the domain identifier (Template ID).
Some modeling tools assign the UID without making any versioning consideration and do not provide tools to manage UIDs for different versions of the same OPT. Since this can generate inconsistencies, we don't rely on the UID from the OPT. When an OPT is uploaded to the EHRServer, the OPT UID is stored, but another UID is generated and assigned to the OPT by the EHRServer. That UID will be used to manage OPTs internally, and to access OPTs from the REST API.
Template IDs for openEHR spec 1.0.2 and AOM/ADL 1.4 (implemented in EHRServer) have no recommended format. Some suggestions on newer versions of the spec recommend archetype like IDs. That works out of the box with AOM/ADL 2, but not for 1.4. Also modeling tools for 1.4 don't enforce any format.
For the Template ID format in the EHRServer we recommend concept.language.version, since it allows both to manage language and versions by just looking at the Template ID. Also allows simple file management if OPT files use that format, for instance "concept.language.version.opt".
Template ID format rules:
- The concept is a word or phrase on snake case. Examples: demographic_data, consultation_note, lab_results, imaging_test_request, ...
- The language is a valid ISO 639-1 code. Examples: en, es, pt, ...
- The version part is a major version number, prefixed with a "v". Examples: v1, v2, v192, ...
Some valid Template ID examples following those recommendations are:
- demographic_data.en.v1
- demographic_data.es.v1
- demographic_data.es.v2
Since version 1.2, the EHRServer manages revisions of OPTs internally, associating all revisions of the same OPT together inside the EHRServer. Revisions are not major versions, are just small changes done to OPTs while developing. We consider this is useful because it allows to have a more formal way to manage small changes to OPTs, and test the EHRServer using different revisions of the same OPT. Behind this revision management are a strong set of rules that were designed to avoid inconsistencies when two or more OPTs are uploaded with the same Template ID. Those inconsistencies have a huge impact in how the EHRServer works, since the core functionalities rely on consistent OPTs, like committing and querying clinical data. And the EHRServer can't rely on the user to know all the rules, because most modeling tools also generate problematic OPTs. Another problem caused by informal modeling processes that the EHRServer can't control is that some developers make manual changes to their OPTs, introducing inconsistencies.
The internal revision management is not for major versions of the OPTs. If a new version of the OPT is created, in the Template ID, the version part should add one. So if the current latest version of the OPT is "v3", and there is a new major release of that OPT, the new Template ID should version "v4".
For revisions, the Template ID should be maintained. For instance, if we have an OPT "demographic_data.en.v1" in the EHRServer, and we made a little change, the new OPT should have the same Template ID. When the new revision is uploaded to the EHRServer, the EHRServer will ask the user if that is a new revision, and will upload and associate that with the previous one. Internally revisions will have a "version number", so the first revision will be "1", the second "2", and so on. Don't get confused, this internal version number is really the revision version number, not the version number in the Template ID. As was stated above, all revisions will have the same Template ID, so will have the same version number in the Template ID e.g. "v1".
When a manager user access an OPT from the Web Management Console, the EHRServer will show all the revisions of that OPT and their internal version numbers.
From EHRServer v1.3, OPTs can be deactivated. This allows to have a better management and synchronization between the EHRServer and the front-end applications. Let's say we have two front-end apps that commit data to the EHRServer. Both apps use the same OPT clinical_encounter.en.v1, and we are about to release a new major version of that OPT, clinical_encounter.v2. We can upload v2 to the EHRServer and create new queries based on it's structure. Still both apps keep committing clinical documents for v1. Both apps need to be updated to use the new v2 OPT when committing data, let's say the dev team can update the first app. Now one app keeps committing data for the OPT v1 and the other app for the OPT v2, no problem!. Then the second app is updated, and both commit data for OPT v2. If no other app needs the OPT v1, it can be deactivated. Deactivation save some database and memory space. One big consideration is that commits for deactivated OPTs will be rejected, that means the app should be updated to use the latest major version of the OPT. To keep front-end and back-end in sync, we recommend to have at most two active OPT versions, the pre-last and last major versions, so all previous versions are deactivated.
At any time, a previous version can be activated again. For instance when a front-end app can't be updated just yet and is on production, so it can't have downtime. This should happen only on exceptional cases.
This process of deactivating OPTs and have at most two active OPT versions allows to have a better sync between the modeling process (creating new OPT versions), the OPT management in EHRServer, and the front-end app development.
Deactivated OPTs can't be used to create new queries.
Suggested flow:
Initial state:
- concept.lang.v1 (active)
Upload new major version:
- concept.lang.v1 (active)
- concept.lang.v2 (active)
Don't upload new major version until v1 is inactive.
All front-end apps are updated to use v2, deactivate v1:
- concept.lang.v1 (inactive)
- concept.lang.v2 (active)
Upload new major version:
- concept.lang.v1 (inactive)
- concept.lang.v2 (active)
- concept.lang.v3 (active)
Don't upload new major version until v2 is inactive.
All front-end apps are updated to use v3, deactivate v2:
- concept.lang.v1 (inactive)
- concept.lang.v2 (inactive)
- concept.lang.v3 (active)
And so on...
OPTs can be logically deleted from the Web Management Console. A deleted OPT is not listed on the main list, only appears on the "Trash", and can't be used to commit clinical documents or create new queries.
When an OPT is deleted, all it's revisions are also deleted.
From the "Trash", a physical delete can be done. Keep in mind this can't be undone! In development environments this is a much useful functionality, since we can do tests uploading some OPTs, then delete them to do other tests. In prod environments, deleting OPTs should be done with caution. This won't affect stored data or existing queries, even if data an queries reference elements from the deleted OPT. But if queries should be edited, the parts that use that OPT can't be modified, since the OPT should exist to do so. We created two step confirmation for these actions, but in case you make a physical delete by mistake (it takes five actions to make a physical delete!), the OPT can be uploaded again, and the EHRServer will see it as it was never deleted. At this point also queries that referenced the deleted OPT will allow to modify the parts that referenced the deleted OPT.
These design decisions were made thinking of the elements commented above:
- Inconsistencies on modeling tools for template identification
- Human errors caused by manually editing OPTs
- Not having a formal modeling process
- Not having a formal template and OPT management and versioning process
- The EHRServer should grant all data is consistent
Also we wanted to balance consistency and robustness, with ease of use and useful functionalities for devs.
On future versions, we might update these rules considering new versions of the openEHR specs, but for now we are confident with this set of rules, and hope this helps our users to formalize their modeling, management and versioning processes..