CKM Release 1.20.0

Release Date: 14 June 2024
Deployments: Starting mid-June 2024

 

Summary of Changes

CKM 1.20.0 addresses a total of

  • 60 issues relating to new or improved functionality,

  • 26 bug fixes, and

  • 13 general tasks relating to upgrades or redesign under the hood.

A few selected release highlights are described in the next section, followed by the detailed list of changes.

Selected Release Highlights

Instance-wide Translation Administrators (per Language)

In response to the need for managing translations across projects and languages more efficiently, a new instance-wide role called "Translation Administrator" has been introduced in this release of CKM. Unlike project-based roles, Translation Administrators can oversee translations for all archetypes in all projects and incubators without needing individual project-based roles. They are designated per translation language and possess various capabilities such as archetypal checkout and translation, conducting translation reviews, and setting translation statuses. Additionally, they can commit archetype translations from branch to trunk under specific conditions and have access to relevant editor tasks and reports. The user interface for assigning and revoking roles has been updated to accommodate Translation Administrators, and roles are dynamically created on demand to avoid system clutter. This role enhances translation management across the CKM platform, providing more flexibility and efficiency in overseeing translations across multiple languages and projects.

image-20240507-091408.png

 

Manage FHIR and OMOP Mappings, AQL Queries and Subset Models

To facilitate the integration of various downstream artefacts, a new "Mappings & Queries" tab has been introduced for each archetype and template in CKM.

This allows users to upload and maintain the following artefacts:

  • Mappings from openEHR to FHIR®, supporting various approaches including YAML files based on the FHIR Connect simple spreadsheets. This is to formally document mappings between models, i.e. from openEHR archetypes and templates to FHIR® resources, or contextual mappings to FHIR® artefacts such as resources, profiles, bundles, or implementation guides. Mappings can for example be expressed using various approaches ranging from simple spreadsheets to formally defined YAML files based on the FHIR Connect Mapping Specification.

  • Mappings from openEHR to the OMOP Common Data Model (CDM), supporting various approaches including YAML files based on the OMOP Conversion Language (OMOCL), a declarative mappings language for mappings between openEHR archetypes and templates to the OMOP CDM.

  • AQL Queries, serving as examplars, and enabling the reuse of ‘typical’ queries expressed in the Archetype Query Language (AQL). These query files can be pure AQL snippets stored in a file with an .aql extension or might also be YAML, JSON or XML files with additional meta data accompanying the AQL definition.

  • Subset Models, showcasing subsets of archetypes that directly correspond to another model in another approach/formalism. For example, if only some elements of an archetype designed as a maximum dataset can be mapped to a FHIR® resource, this subset model or subset archetype would be stripped down to only contain these directly mappable elements while guaranteed to be consistent with the (maximum dataset) archetype. Subset models can be stand-alone or be defined in addition to or in combination with mapping files to e.g. OMOP or FHIR.

     

CKM enables the upload of different file types and remains agnostic to the formalism used, recognizing the need for flexibility in this evolving landscape. Projects now have a designated role of Mappings and Queries Editor to manage these artifacts, with Clinical Knowledge Managers and Project Editors holding subsuming this new role. With this role, users can upload mapping files, specify their relevance to specific archetype/template revisions, and optionally version them. Uploaded files are displayed with warnings if they are not applicable to the current revision. Mappings and Queries Editors can view, edit, and delete mapping files as needed. This initial implementation addresses immediate needs while leaving room for future extensions and refinements based on user feedback and uptake.

Since the need is very clear, but the exact formalism is not as of now, CKM at this stage will enable the upload of various filetypes including YAML and Spreadsheets and otherwise remain agnostic to the formalism used. Potential future enhancements may include metadata extraction, detailed governance, project-wide mapping overviews, and bulk downloads of mappings.

image-20240506-133355.png

Release Set Overhaul

One focus of this CKM release is on significantly enhancing the functionality and usability of Release Sets.

Release Set Editors can now easily revise Release Sets from the revision history and enjoy the benefits of Semantic revision numbers are now fetched and displayed during archetype version changes, and resource revisioning in Release Set grids now includes semantic revision numbers where available. The overview and individual display of Release Sets have been enhanced for better clarity.

A new Release Candidate state has been introduced that is exclusive to Release Sets, allow a Release Set to be marked as a Release Candidate before its publication (Status: Published). Additionally, a (configurable) strict Release Set Governance mode has been introduced to lock release sets once they are in status Release Candidate: From there on, they can only be Published or Rejected.

Other notable additions include

  • the ability to clone Release Sets,

  • a new markdown manifest of the Release Set, replacing the existing free text format.

  • REST-like direct links have been fully enabled for seamless navigation, and

  • improved support for direct links to resource center documents within Release Set manifests.

These enhancements collectively aim to streamline Release Set management and improve user experience.

Key bug fixes include fixing an error encountered when creating a Change Request for Release Sets beyond their initial status. Moreover, transparency issues with incompatible change popups have been resolved.

 

 

Review Round Overview Redesign

In this update, the Review Rounds Overview panel for each resource is undergoing a significant redesign aimed at enhancing usability and intuitiveness. The new layout will group reviews primarily by Review Round, presenting each round as a collapsible panel. Starting with the latest review round and descending to the earliest, key information such as the number of completed reviews, status (open or closed), initiator, initiation date, and deadline will be prominently displayed. Additionally, donut charts illustrating recommendations from submitted reviews and review invitations will be included for each round. Users with appropriate permissions, such as Clinical Knowledge Administrators (CKAs) or project members, will have access to buttons enabling actions like opening the review summary, viewing invitations, closing/reactivating rounds, modifying open rounds, and deleting rounds, as well as access to an additional grid to display and manage individual reviews within each round, providing a comprehensive overview and control of the review process.

 

 

Reporting Finetuning

Various finetuning of reporting, for example:

  • The Data Points Report has been made available for each project directly.

 

  • The total number of Change Requests is now displayed in the Change Requests Overview.

  • The total number of owned, referenced and remote archetypes used by a project or incubator is now displayed directly on the Projects & Incubators overview page.

 

Syntax Highlighting

Syntax highlighting and copy-to-clipboard features for various displays such as

  • ADL Archetypes

  • XML Archetypes

  • Template OET and OPT

  • OMOP and FHIR Mappings (e.g. YAML or JSON)

  • AQL Queries, and

  • Release Set Markdown.

Detailed List of Changes

New & Improved Functionality (60 issues)

Key

Summary

New or Improved Functionality Description

Key

Summary

New or Improved Functionality Description

1

CKM-1461

Instance-wide Translation Administrators (per Language)

To manage translations, CKM features the project-based role of “translation editor”. A translation editor can manage all translations of archetypes owned by the project.

However, unlike the development and management of the content of archetypes, that is often organised along project boundaries, there is a need for a role to:

  • Manage the translations for all archetypes in all projects (as well as incubators) without assigning a project-based role to the user for each project.

  • Manage the translations per translation language, not necessarily for all translation languages.

Therefore, this release introduces a new CKM instance-wide role, the role of “Translation Administrator”.

The role Translation Administrator is assigned (by Clinical Knowledge Administrators or Technical Administrators) per translation language, so that a CKA instance can have separate Translation Administrators for - say - Norwegian Bokmål, Catalan, Farsi and German.

The role of Translation Administrators enables the holder of the role to

  • Checkout and translate archetypes (relevant if the CKM is configured to restrict resource checkout to user’s with special roles).

  • Conduct Translation Reviews (only in the assigned translation language). NB: Reviews are a feature of projects only, not incubators. the user has full access to Translation Reviews of the language.

  • Be notified if a new or updated translation (in that language) is submitted by a user to the editors. (Note: In case an archetype owned by a private incubator is translated, the Translation Administrator must be able to view the incubator to be notified)

  • Commit an archetype from branch to trunk if the archetype only has changes to translation languages the user is a translation administrator for. (Typically this will be one language, but can be multiple as well). For this to be allowed, there must neither be any other active branches for the archetype, nor must the translation branch to be committed be an outdated branch (i.e. another branch was committed after the translation branch has been checked out. (This is behaviour aligned with the recent restrictions of CKM-1477: Translation editors should only be able to commit translation-only branches if there are no other active branches for that archetype and if the branch is not outdated).

  • Set the status of an archetype’s translation.

  • View the Editors' Task List for the archetypes and make changes to To Dos from the Task List if it explicitly mentions the translation language (either the ISO code or the translation language in server localisation). This is to mark the automatically generated “commit the translation” tasks as completed.

  • See the “Editor’s Review Rounds” Dashboard widget and related review round overviews.

  • See the Active Branches report.

NB: The above is similar to the behaviour and rights of translation editors of a project, but for all archetypes visible to the user, and only for one (or selected) translation languages.

NB: This role does NOT give the user access to private incubators. If however, the user is a member of a private incubator, the translation administrator can use this role to manage translations of the archetypes in this private incubator as well.

The user interface for CKA or technical admins to grant and revoke user roles (in the User Profile) has been revamped to deal with translation administrators by selecting the appropriate language from a combo box. As part of this rework, the Multiselect boxes with the currently assigned and unassigned user roles) have been removed in favour of combo boxes to grant or remove user roles.

The Translation Administrator role for a specific translation language is created (automatically) on demand only - this is to avoid cluttering systems with hundreds of roles where only a few are currently needed.

Translation Administrators have also been added to the “Users per Role” overview available from the Tools menu for CKAs and technical administrators. A Translation Administrators role is only listed here if at least one user has this role for a particular translation language. This is to avoid cluttering the overview with hundreds of empty roles.

Also see discussion at https://discourse.openehr.org/t/request-to-join-project-as-translation-editor/4170/12 .

2

CKM-1707

Data Points Report per Project

Add a data point report per project, available directly as a tab from the project.

For normal users, this should be the second last entry, just before the Download of Project Files.

 

3

CKM-1807

Support REST-like URLs for direct links to resource centre documents and add the links of these Associated Assets to the Release Set manifests

Direct links to documents are currently only accessible via a query string, e.g.

https://ckm.openehr.org/ckm/document?cid=1013.17.14

https://ckm.openehr.org/ckm/document?cid=1013.17.14&version=1

It should be possible to access the documents via a REST URL, for example:

https://ckm.openehr.org/ckm/documents/1013.17.14

https://ckm.openehr.org/ckm/documents/1013.17.14/1

ckm/documents/<cid-document>

ckm/documents/<cid-document>/<version>

In addition:

4

CKM-1828

Ability to Add OMOP Mappings to Archetypes and Templates

It is increasingly recognised that openEHR and OMOP can and should be used in combination, cp e.g. https://discourse.openehr.org/t/ohdsi-and-openehr/308/28 . For this to be supported, it is paramount to create detailed mappings from commonly used openEHR archetypes and templates to OMOP CDM where and to the extent possible.

For this purpose, a new Tab has been added for each archetype and template, dubbed “Mappings & Queries” where mappings from openEHR to FHIR can be uploaded and maintained.

There are various approaches to mappings ranging from simple spreadsheets to formally defined YAML files based on the OMOP Conversion Language (OMOCL), a declarative mappings language for mappings between openEHR archetypes and templates to the OMOP CDM.

Since the need is very clear, but the exact formalism is not as of now, CKM at this stage will enable the upload of various file types including YAML and Spreadsheets and remain agnostic to the formalism used.

To display the mappings, some generic syntax highlighting has been added to CKM as well: cp. CKM-2128.

Projects have a new role of Mappings and Queries Editor enabling the management of these artefacts on a project-level. Clinical Knowledge Managers and Project Editors also hold these rights.

With this role, an OMOP mapping file can be uploaded to an archetype or template by providing the file, a title and optionally description, the archetype or template revisions this mapping file applies to, and whether the mapping file is to be versioned. All uploaded mappings files are displayed. If a mapping file is NOT applicable to the currently displayed revision of the archetype or template (typically: the latest or latest published), a warning is displayed for this mapping. Each (text-based) mapping file can be viewed and each mapping file can be downloaded. Mappings and Queries Editors can edit and delete as required.

Note: This work is intended to cater for an immediate need expressed by various parties while some details remain unclear as of now. Depending on uptake this can be extended and finetuned as required in future releases of CKM (e.g. extract meta data from the file if the format and the meta data is agreed upon, provide more detailed governance, provide and overview of all mapping within a project, ability to download of all mappings, …).

Cp. CKM-2104, CKM-2119, CKM-2132 for related functionality.

Example OMOCL mapping file: medical_data/action/Medication_v1.yml

archetype_id: "openEHR-EHR-ACTION.medication.v1" mappings: - type: "DrugExposure" concept_id: alternatives: - path: "/description[at0017]/items[at0020]" drug_exposure_start_date: alternatives: - path: "/items[at0043]" - path: "../" - path: "." drug_exposure_end_date: alternatives: - path: "/items[at0043]" - path: "../" - path: "." quantity: optional: true alternatives: - multiplication: - path: "/description[at0017]/items[openEHR-EHR-CLUSTER.dosage.v1]/items[at0144]" - path: "/description[at0017]/items[openEHR-EHR-CLUSTER.dosage.v1]/items[at0164]" - path: "/description[at0017]/items[openEHR-EHR-CLUSTER.dosage.v1]/items[at0144]"
5

CKM-1926

Complete Rework of the Review Rounds view of each resource

The Review Overview of each resource currently consists of two grids (“Completed Reviews”, “Review Rounds Overview” (collapsed)), and a section to “Open Review Summary”.

This review panel is being revamped as part of this card guided by the idea that review round can be displayed and managed much more intuitively if grouped primarily by Review Round.

Therefore display each review round as one collapsible panel, starting with the newest review round and going down to review round 1.

For each review round, display some core statistics and facts for each review round prominently, such as

  • the number of completed reviews,

  • the status of the review round (open or closed),

  • the initiator of the review round,

  • the initiation date,

  • the deadline.

In addition, show

  • a donut chart of the recommendations of the submitted reviews, and

  • a donut chart of the review invitations

for each review round.

Also - depending on the user’s rights - buttons to

  • open the review round summary with the consolidated view of all submitted reviews.

  • view the review invitations,

  • close or reactivate the review round, respectively,

  • modify an open review round (opens the known review round panel with the resource already selected), and

  • delete an open review round (as CKA).

For user with appropriate rights as CKA or within the resource’s project, an additional grid is displayed to display and manage the individual reviews of the review round.

 

6

CKM-1981

Add validation for missing at code on LOCATABLEs

Add a validation check for missing at code on LOCATABLEs - such as ITEM_TREE:

https://discourse.openehr.org/t/missing-at-code-in-item-tree/4035

This should report a VACSI validation error (which seems to be the best match), with a specialised message clarifying that a LOCATABLE mandates an archetype_node_id.

7

CKM-1985

Clone a Release Set

Ability to duplicate/clone a release set and set back initial state, so that the previous Release Set can be used as a basis for the new release set.

Use Case: A new version for a CDR with an updated set of archetypes and templates. There should be no need to start completely from scratch each time, even with the strict governance mode introduced in CKM-1996 (see below).

In more detail, functionality is introduced to clone a release set from the following places (assuming rights to edit release sets):

  • Release Sets/View All Release Sets: click on Release set and select “Clone Release Set”

  • Release Sets/Revise Release Set: click on Release set and select “Clone Release Set”

  • In the Revision History of a Release Set, click on the Details button of the latest revision and select “Clone Release Set”

Once selected, a prompt appears for the user to provide a new Release Set Identifier (such as myreleaseset.v1).

If the provided release set identifier is valid and not yet in use, the release set is cloned and opened directly to be able to immediately start making changes to it.

 

8

CKM-1986

Add a Release Candidate state for Release Sets

Add a Release Candidate state for Release Sets. This is so that release sets can be rejected or accepted in testing stage. If the Usage of the Release Sets fails in the testing environment, then editors would reject the release set and create another RS.

If testing turns out to be ok, editors can then formally publish the release set, otherwise reject it.

It would be helpful to have a “Release Candidate (RC)” state to identify a Release Set that has been integrated in the CDR but is still in the pre-production phase. Once this Release set has been approved for production, the state would be set to “Published”, in the case of being rejected the state would change to “Rejected”.

9

CKM-1992

Improve the Related Resources Display for "Release Sets Using This Archetype" and "Release Sets Using This Template"

In the Related Resources page of an archetype or template, all release sets that contain the archetype or template (in this exact revision) are listed.

 

 

This view should be improved in the following ways:

  • Add an icon showing the status of the Release Set in the same way as this is currently already done for archetypes. This refers to the most recent version of the release set using the resource in the currently displayed revision.

  • Properly style the “latest revision” etc. indicators as this is currently already done for archetypes.

  • Add the Release Set Icon in the header.

  • Add right hand top comparison menu button (“Compare/Details) with latest and latest published revision of the release set (as applicable). (Similar for other resource types).

If an archetype or template is contained in various revisions of a Release Set:

  • List all release set versions where the archetype or template is being used in.

  • Explicitly add the LATEST REVISION or LATEST PUBLISHED indication.

  • If the LATEST REVISION or LATEST PUBLISHED is not containing the archetype or template (any more), indicate this as well with a reference to these special revisions.

This results in the following example displays:

 

Example, if the current revision of the release set does NOT contain this archetype or template anymore in the specified revision:

 

10

CKM-1994

Fully enable REST-like Direct Links for Release Sets and use them consistently everywhere for all links

REST-like direct links for release set exist in principle.

They take the form of e.g.

<ckm-server-base-url>/ckm/release-sets/1013.10.30

However, they currently are not displayed like this in e.g.

  • emails about a new or updated release set,

  • tweets about a new or updated release set, and

  • the Release Set Manifest file.

(Up to CKM 1.19.1, the link would have been e.g. #showReleaseSet_1013.10.30)

11

CKM-1996

Introduce an option for a strict Release Set Governance mode, where Release Sets are locked once in Release Candidate or Published state

This card introduces a new configuration of CKM to support a stricter governance mode for Release Sets.

If this stricter governance mode is enabled in a CKM instance, the following restrictions are enforced:

Once a Release Set has been set to Release Candidate or Published state, (or has been rejected or deprecated), it is no longer possible to make any more changes to the Release Set (i.e. it is not possible to Revise the Release Set). I.e. if a Release Set is in status RELEASE_CANDIDATE, PUBLISHED, REJECTED, or DEPRECATED, the Release Set cannot be revised but is eternally locked.

The states and transitions between states are also reduced, so that it is only possible to transition in the following ways once the Release Set is a Release Candidate or has been published.

  • RELEASE_CANDIDATE → PUBLISHED

  • RELEASE_CANDIDATE → REJECTED

  • PUBLISHED → DEPRECATED

It must not be possible to return to a state that allows modifications to the release set. Thus it is not possible to transition from REJECTED → DRAFT.

The intention of this is that, once a Release Candidate, a Release Set can then either be published (if all subsequent tests with it succeed) or rejected (if any test fails or it needs to be modified in any way for whatever reason), but it can never be modified.

It is however possible to transition from DEPRECATED → PUBLISHED and REJECTED → RELEASE_CANDIDATE. This is to be used only to correct accidental transitions to an inactive state. Note that it is not possible to modify the release set in any of these states in strict governance mode.

12

CKM-2003

Use "latest revision (unstable)" instead of just "latest revision" to make it clearer that this is not an officially published version

In some places in CKM it is useful to use the wording "latest revision (unstable)" instead of just "latest revision" to make it clearer that this is not an officially published version.

This is most useful for headings and tooltips related to resources that are currently in a REASSESS_* status, waiting to be republished.

(Note: While “latest draft” probably sounds best, we also have the resource states of “DRAFT” and “REASSESS_DRAFT” which would make its use for an overlapping concept somewhat problematic/inconsistent.

13

CKM-2004

Improve Display of Resource Revisioning in a Release Set's Resources Grids - in particular include the semantic revision number where available

The various resource grids used as part of displaying or creating/modifying a release set should display more information about the revision of the included resource.

This is particular useful for archetypes where the semantic revision number such as 1.10.1 or 1.11-0.alpha can be displayed directly in the revisioning column as well as in the tooltip.

In the revisioning column, use the typical labelbox - also to give another visual indication what is the latest, latest published or a previous revision.

 

14

CKM-2006

[Internal] Various Code improvements, refactoring, commenting, cleanup - 1.20.0

Various code improvements, refactoring, commenting & cleanup

  • Minor cleanup of ResourcesGridPanels in preparation for Release Set changes.

  • Cleanup of ReleaseSetsOverviewPanel before Release Set rework.

  • Various Code improvements, refactoring, commenting, cleanup - 1.20.0 Minor clean up of OPTServiceClient and some minor logging improvements.

  • Harmonise usage of throwing error if error element from mediaflux in UserHandlerImpl and ProjectHandlerImpl. Minor cleanup of ReviewFunctionalityController and ClassificationHandlerImpl.

  • Cleanup in preparation for CKM-1992 - Improve the Related Resources Display for "Release Sets Using This Archetype" and "Release Sets Using This Template"

  • Minor clean up of ReleaseSetsOverviewPanel, ReleaseSetHeaderPanel, GridPanelOi in preparation for CKM-2040 Improve Display of Overview of Release Sets and the Display of each Release Set.

  • Minor clean up of UserTooltipRenderer and FullTextAsTooltipRenderer in combination with CKM-2040 - Improve Display of Overview of Release Sets and the Display of each Release Set.

  • Minor cleanup for ReviewInvitation model in combination with CKM-2040 Improve Display of Overview of Release Sets and the Display of each Release Set.

  • Some code and comment cleanup of Object creators, html generators, review field enum and the review feedback history window in preparation for CKM-2046: Error message displayed when Review Feedback History cannot be retrieved (1.19.1)

  • Cleanup and improve ArchetypeHTMLPanel in preparation for CKM-2033 On clicking on "Show technical", the panel gets a bit larger and the bottom buttons moved down

  • Minor cleanup related to the OPTServiceClient related to CKM-2012 OPT generation fails when an explicit CDATA segment is present (1.19.1).

  • Cleanup and finetuning of AssociatedAssetsGridsPanel in relation to CKM-1991 Removing a template from a Release Set may cause the "Recalculating" Wait Dialog to never disappear

  • Various rework related to Resource Main Data records and their usage for Release Set modification

  • Minor cleanup of code re Rich Text Area and its toolbar

  • Clean up service to reactivate a review round in preparation for CKM-2020 - Terminology and Translation Review Rounds should not be able to be reactivated if the main status of the archetype itself is an inactive state (i.e. deprecated or rejected).

  • Clean up Statusable, Notifiable interfaces, and some comment finetuning of PResource and subclasses in preparation for CKM-1994: Fully enable Direct Links for Release Sets

  • Clean up of DocumentationHandler* classes, AllResourcesPerProjectPanel and services related to transforming operational templates and listing resource documentation in preparation for CKM-2068: Show Project-based OPTs from the Project Resource Centre on the Project Dashboard as well

  • Minor clean up of change requests and revision history services

  • Minor cleanup of user login and opt classes.

  • Minor cleanup of RichTextArea and related classes related to CKM-2062 - Improve Consistency of Formatting when editing in RichTextAreas, especially for the Review Mail Invitation

  • Some cleanup of Role Manager and internal user classes in preparation for CKM-1461: Instance-wide Translation Editors

  • Some cleanup of various OPT and Value Set Injection classes related to CKM-2087 Transform Changes required to support templates where the same code is used in different 'terminologies'

  • Minor cleanup of the Archetype Validation Manager.

  • Cleanup/finetune/streamline some backend classes related to CKM-2086 Improve and streamline the query syntax for queries with the main identifier of a resource, CKM-2088 Manually triggered regeneration of OPTs only regenerates 100 OPTs, CKM-2089 Slot fills where no archetype from CKM fits are no longer validated.

  • Minor cleanup of ArchetypeSimplifiedHierarchyItem, ArchetypeSerialisedObjectCreator and the Resource Queryer Impl.

  • Minor cleanup of UserHandlerImpl in relation to CKM-2086 Improve and streamline the query syntax for queries with the main identifier of a resource.

  • Rework ReviewAndReviewRoundDetails to be converted from a Record and use accordingly. Various other finetuning related to CKM-1461: Instance-wide Translation Administrators and CKM-1926: Complete Rework of the Review Rounds view of each resource.

  • Clean up of GeneralSpecialQuestionsSpecifyPanel and Clean up of ArchetypeHTMLGeneratorTwoLanguages

  • Minor cleanup of Active Branches Report Panel and wordsmithing.

  • Cleanup of Resource Documentation related classes/services.

  • Minor cleanup of some Change Request and Project related classes/services.

  • Clean up ResourceExportPanel (incl. introduction of flex layout) in preparation for CKM-2110 - Resource Mirrored in Git Repository should not be shown for Incubator resources

  • Rename title case method for consistency

  • Fix potentially/theoretically leaking termset input stream when updating a termset.

  • Harmonise colour order in theme.

  • Finetune/correct and streamline the css for toolbar, including finetuning of the colour when selected.

  • Clean up of General mf Object.

  • Clean up Change Request service classes in preparation for: CKM-2134 - Error on Creating a Change Request for a Release Set in any status beyond INITIAL

  • Minor Cleanup of Comparison, and Submit Panels related to CKM-2034 - Comparison Report: On upload/commit state the comparison basis: "trunk" or "branch <branchname>".

  • Title capitalisation for Order templates in the Project Dashboard and other minor cleanup

  • Minor cleanup of mail with recovery sending service and the core String Utils, the frontend String Utils and the logins list service.

  • Finetune title capitalisation and general harmonisation of Email headers

  • Correct stylesheet errors and ensurer Loading panel is not selectable

  • Code improvements and clean up for Template and other Resource related services in preparation for CKM-2141 - OPT generation should honour a language explicitly stated in the oet file over CKM's configured resource display locale

  • Code improvements and clean up Resource related services in preparation for CKM-2142 - Prevent reverting a resource if the version is the requested version for reversion is equal to the current version

15

CKM-2019

Icon Improvements and Additions 1.20.0

  • New icon for review invitations used in a variety of places

  • Improved icons for the Revision indication in Release sets (latest, latest published, latest and latest published, previous revision)

  • New Save icon used for release sets.

  • Rework the adoption, watching, not watching, start adopting icons as SVGs

  • Rework the Editor's summary of adoptions icon as SVG

  • Rework the Resource Centre icon as SVG

  • Finetune discussion and classification icons for visibility (especially when selected in the toolbar).

  • Rework the Printable View icon as SVG

  • Rework the Related Resources icon as SVG

  • Rework All Resources and All Order Templates Icons for the left hand explorer.

  • Rework as SVG and and improve the various Review type related icons.

  • Minor update to the template “org chart” icon

  • Rework of translation, translation submit and translation upload icons as SVG

  • (Re)move some old icons no longer in use.

  • Rework Archetype Proposal Icons as SVGs.

  • Rework the three magnifier search/find icons + latest search as SVGs

  • Rework Audit Log icon as SVG

  • Rework left-hand explorer Expand/Collapse all icons as SVGs

  • Rework Projects, Incubators and Projects & Incubators menu / select box icons as SVGs.

  • Rework export, import, bulk-export, bulk-import icons as SVGs

  • Rework Revise Resource icon as SVG

16

CKM-2020

Terminology and Translation Review Rounds should not be able to be reactivated if the main status of the archetype itself is an inactive state (i.e. deprecated or rejected)

Terminology and Translation Review Rounds should not be able to be reactivated if the main status of the archetype itself is an inactive state (i.e. deprecated or rejected).

In total, the expected behaviour is the following:

  • No resource with an inactive main resource status should have an active review round of ANY kind. In practice this applies to terminology and translation review rounds for archetype. Independent of the status of the terminology or translation, respectively, if the main (content) status of the archetype is inactive, review rounds should not be able to be reactivated.

  • Terminology and translation review rounds should also not be able to be reactivated if the status corresponding to the terminology (e.g. Snomed CT) or translation (e.g. Norwegian) is in an inactive state.

  • Either way only the latest review round of its kind can be reactivated.

17

CKM-2022

Review Rounds Overview Panel Finetuning

Various improvements to the review round overview panel available from Reviews/Review round overview with appropriate rights.

  1. Change double-click behaviour to open the Review Round Overview (instead of the invitations of the review round which are easily accessible from that panel after CKM-1926: Rework the Review view of each resource.)

  2. Adapt the explanatory text accordingly

  3. Add an action arrow to the grid for the context menu to be found more easily and also show this on a normal click on the action arrow.

  4. Restructure the context menu to use an additional separator. Reorder according to the above and some wordsmithing.

18

CKM-2029

Localise some components for Norwegian Bokmål and Catalan

Additional localisation of relevant components into Catalan and Norwegian.

Grid menus and Grid groupings for example have not been localised to Norwegian Bokmål and Catalan because this uses a different internationalisation mechanism based on the framework.

Also Framework buttons like Yes, No, OK, Cancel were not translated.

19

CKM-2030

User Roles Panel: Subdomains and Projects/Incubators should be sorted by name, case-insensitively

In the User Roles Panel available from the User Profile (as a CKA or Technical Admin), the subdomain and then project/incubators should be sorted by their name, case-insensitively. For subdomains, also use the remote or local or customised icon.

20

CKM-2034

Comparison Report: On upload/commit state the comparison basis: "trunk" or "branch <branchname>"

Resources such as archetypes are compared for example when

  • a new revision of a resource is uploaded to a branch, or

  • a branch is committed to the trunk.

In the first case, the resource is compared with the latest revision on the branch, whereas in the second case, the final branch revision is compared with the latest trunk revision. This is the case even if the resource was checked out from a previous revision (in which case a warning is displayed and the user must have appropriate full editing rights to continue).

While this is the natural comparison to be executed, for the avoidance of any doubt, the resulting comparison report (“Changes”) should clearly indicate the basis of its comparison such as the branch name or the trunk latest revision.

21

CKM-2036

Better visual way to close the South Panel Notification

The South Panel with the upgrade notification etc. can be closed by clicking on the tiny arrow in the border between center and south panel.

This is useful, but naturally very easy to miss. Using a right-hand X to close that highlights itself on hover seems appropriate here.

To reopen, the small arrow in the middle can be used, on hover it is also highlighted a bit.

Also, if the notification is a temporary one like an imminent outage to due a CKM upgrade, the right-hand x is of darker colour, whereas for a permanent notification such as a small licencing message, this is lighter.

22

CKM-2040

Improve Display of Overview of Release Sets and the Display of each Release Set

This issues relates to a series of many improvements to the Display of Release Sets, in particular:

  • Improve various height and width and paddings, including the various grids the overview grid, the various grid panels and the header form to make better use of the available space for larger release sets.

  • Naming the “Release Set ID” as such (instead of just “release set”)

  • Menu on click: Ensure that “Revise” is before Export if it exists. This is because that is the main functionality of the form then.

  • Add action column to the grid (or switch the icon to the default action arrow icon).

  • Finetune distance between the status and the release set id, and remove the explicit “Status: ” that does not align with the rest of the form

  • Show warning on incompatible change that may require a new release set version also if the release set is currently deprecated, i.e. always when it has ever been published.

  • Add resource type icons to the resource tabs of the release set.

  • Add Save icon to the buttons and the Save tab.

  • Add icons for Associated Assets and Secondary Assets tabs.

  • Use coloured instruction panels for explanations.

  • Improve widths, heights, paddings, capitalisation for Release Set Comparison

  • Change button type for incompatible change.

  • Improve title casing and display various titles as the grid header instead of as a separate heading.

  • Improved icons for the Revision indication in Release sets (latest, latest published, latest and latest published, previous revision)

  • Internal Extract ResourceTooltipRenderer and ResourceRevisionTooltipRenderer for reuse and consistency in a few places - also in the left hand panel.

  • Internal Extract and use TextInCombinationWithBooleanAsCheckboxRenderer for the SecondaryAssetsGridPanel

  • Add title for ReleaseSetOverviewPanel

  • Finetune resource status icon alignment

  • Add ReleaseSet icon to grid in ReleaseSetOverviewPanel

  • Add icon for validation tab

  • Remove Export as bold context menu entry (still available as a normal context menu entry)

  • Harmonise some method names and add various javadoc comments.

  • Add initial explanation instruction panel

  • Add main display name to Release Set Modify Panel heading (not only "Revise Release Set")

  • Add icon to Context menu of an archetype/template: “Remove Archetype” or Remove Template”

  • Only show context menu to remove the resource or select a different revision if it is not a resource that has automatically been included (where it does not make a lot of sense as the validation will fail in the end anyway if the wrong revision is selected).

  • If view only, or if the resource is automatically included, use the normal Resource Context Menu instead for easier navigation.

  • Finetune explanation text and when it is shown and adjust heights accordingly.

  • Hide the “previous” and “next” button in the toolbar completely if disabled because it is the first or last tab.

  • When modifying a release set and adding two templates: Any archetypes used by both templates in the exact same asset version should only be displayed once in the “Automatically included archetypes” grid. (NB: If they are included in different asset versions, then the do need to be displayed twice of course.)

23

CKM-2042

The Overall Change Requests Report should list the total number of Change Requests per Resource Type

Currently, the Overall Change Requests Report lists the total number of archetypes and templates with one or more change requests.

It is however not possible to easily see the total number of Change Requests. Therefore, the Overall Change Requests Report should list the total number of Change Requests per Resource Type in addition to the total number of resources with one or more change requests.

Therefore, add a summary panel that lists the following information PER RESOURCE TYPE:

  • Total number of open Change Requests

  • Total number of open PRIORITY Change Requests

  • Total number of in process Change Requests

  • Total number of in process PRIORITY Change Requests

  • Total number of closed Change Requests

  • Total number of closed PRIORITY Change Requests

Do not report zero values.

The same information should also be listed for the project-based Change Request reports.

 

 

24

CKM-2048

Bulk Create/Update Users via CSV File Upload: Clarification in the tooltip of the password field to clarify that this password will only be set for new users.

In CKM’s Bulk Create/Update Users via CSV File Upload, the tooltip explaining the password functionality is not clear that the password only applies to new users, not to users that are updated. Therefore, clarify in the tooltip of the password field to clarify that this password will only be set for new users.

25

CKM-2053

Ensure that the Norwegian "Konseptbeskrivelse" does not break on the last character in the Archetype Header tab

The Norwegian "Konseptbeskrivelse" is too long to fit on one line in the Archetype Header tab. This should be properly broken up between Konsept and beskrivelse.

Likewise, the German localisation should use the same mechanism to properly break “Konzeptbeschreibung”.

26

CKM-2055

Stop users saving Review Round Mail Invitation Templates without any text in them

As a user with the role CKA or Techincal Administrator, I create Review Round Mail Invitation Templates as required.

When I create these Invitation Templates, I need to enter the text that will be displayed in the mail invitation emails sent to users.

When we leave the text blank when creating a Mail Invitation Template, we see an error message which is technically correct because it does not make any sense to store an empty invitation template.

When saving an existing Mail Invitation Template, and removing the text, we see a message the changes have been successfully saved, however, upon reviewing the Mail Invitation Template, no changes were made to the text.

In both of these cases, in order to improve the user experience, we should consider improvements such as:

  1. Stopping the user save the Mail Invitation templates with no text by greying out the buttons to save the Templates and providing an information message as to what is missing being at least one letter in the text field

OR

  1. Stopping the user from saving the Mail Invitation Templates with no text in them and displaying a message advising the user that the Mail Invitation Template cannot be saved as there is no text entered in the Template.

Message displayed when saving new Mail Invitation Template with no text in it

 

27

CKM-2059

Show at codes of runtime name constraints in the Technical View of an Archetype

The at codes of runtime name constraints should be shown in the Technical View of an archetype.

For example in https://ckm.openehr.org/ckm/archetypes/1013.1.5907, the runtime name constraints related to Dimension (Length, Width, height, …) should be shown when the Technical View of the Archetype is chosen.

 

Also, this needs to work for the Volume Element of https://ckm.openehr.org/ckm/archetypes/1013.1.6655 which has runtime names and bindings to the (coded) runtime names:

 

The at code should also be displayed in the the technical view for all possible coded runtime names.

28

CKM-2060

Don't allow user to click 'OK' on Add Task dialogue Box in Review Summary when no text is entered or provide a more user-friendly error message

As an Editor, I may want to add a Task to a resource through a review by clicking the Editor Feedback field in the Review Summary and selecting the button Add Task

When I don’t enter any text in the dialogue box that is displayed when I click on Add Task, a message is displayed effectively advising the task could not be created as no text was entered in the Add New Task dialogue box.

A user may not be able to interpret that message should they see it and may raise this a bug in CKM.

It would be ideal if this could be improved such as disabling the OK button until at least 1 character is entered in the Add New Task dialogue box or making the message that is displayed more user friendly.

Review Summary: Add New Task dialogue box displayed when Editor clicks on Add Task button in Editor Feedback field

 

Message displayed when no text is entered in Add New Task dialogue box

 

29

CKM-2062

Improve Consistency of Formatting when editing in RichTextAreas, especially for the Review Mail Invitation

Improve Consistency of Formatting when editing in RichTextAreas.

RichTextAreas are used for example to provide review invitation details and review mail invitation templates.

They are also used for discussions in CKM or when composing emails within CKM directly.

Currently there are some consistency problems with the display during editing in a RichTextArea and when displaying the result - either in CKM or in an email.

For example:

  • Depending on user browser settings, it is likely that some text that was supposed to be “smaller” is actually displayed larger than the default.

  • When “Remove Format” is used from the Toolbar above the RichTextArea, the default styles are also removed in the RichTextArea. This leads to a ugly styles in the RichTextArea which are replaced again with the default styles on saving. However, this is then inconsistent with the display.

The aim is to provide a more consistent appearance of what is displayed in the RichTextArea on editing and then in the emails and inline in CKM.

  1. When the text is for an email only (review invitation email, composing email), just add the default email styling to ensure that the email is a (somewhat) faithful representation. Note that due to differences in support, this is never 100% accurate across all email clients.

  2. If it is for both email and inline (e.g. discussions), add the typical CKM styles to the iframe of the RichTextArea, so that the display after editing is faithful to what is displayed when editing the text.

  3. Remove Format button: The default format should not be removed (e.g. font) from the RichTextArea, just reset.

To support this several changes have been made under the hood.

30

CKM-2065

Release Sets Creation and Modification: Fetch and Display Semantic Revision Number when changing the version of an archetype included in a release set

During the creation or modification of a Release Sets:

If the editor changes the asset version of an archetype included in the release set (via right-click on the archetype in the “Selected Archetypes” grid), the corresponding semantic revision number should be fetched and updated in the archetypes grid as well.

 

31

CKM-2067

Replace the existing free text manifest of a Release Set with a markdown manifest

Release Sets currently have two manifest files.

  1. An xml manifest file

  2. A free text txt manifest file

The latter is not very well structured and suffers from various layout and naming problems.

Therefore, this free text manifest has been replaced by a markdown manifest.

This markdown manifest:

  • is localised,

  • is included in the Release Set File Set as manifest.md,

  • can be displayed as a separate tab of the release set, and

  • can be downloaded from the release set’s export tab.

32

CKM-2068

Show Project-based OPTs from the Project Resource Centre on the Project Dashboard as well

It is possible to upload Operational Templates to the Resource Centre of any Project. This is for example useful to showcase examples of how an archetype could be used or to just quickly show the end result of a template rather than having to upload and sort out all dependencies of the template.

For direct access, these Operational Templates should also be listed on the Project Dashboard and a note displayed in the Project Resource Centre that uploaded OPTs will also be displayed on the Dashboard.

33

CKM-2069

Link the Usernames displayed in Change Requests and Tasks and Archetype Proposals to the User Profile

Change Requests, Archetype Proposals and also Tasks are a frequently used feature in CKM.

Change Requests and Archetype Proposals can be submitted by any registered user - and it happens regularly that users register to CKM in order to create a new Change Request for an archetype (or template).

Therefore, it is very useful to be able to directly navigate from the various usernames (creator, modifier, commenter) of Change Requests, Tasks and Archetype Proposals to the user profile in the way as this is already implemented for discussions in CKM. If a user is no longer registered with CKM, the user’s original username is displayed without a link to the non-existing user’s profile.

34

CKM-2070

Add concept description placeholder for review invitation templates

While the recently introduced Review Invitation Templates are very helpful in organising review rounds, a frequent use case is to be able to display the archetype’s concept description in the review invitations as well.

Therefore, add support for a new placeholder, named
%{resource-description}%.

This should use the same “most appropriate” language as used for the concept name (resource-main-display-name placeholder).

This is only applicable to archetypes and will be replaced with an empty string for templates (or termset) reviews. The new placeholder should also be mentioned in the example mail invitation and the description of supported placeholders at the top of the ‘Manage Review Invitation Templates’ functionality.

35

CKM-2073

Revision History: Only display links to Change Requests extracted from the log message that are known to be Change Requests of the resource

In CKM 1.19.0, CKM-1286 introduced the ability to automatically link Change Requests mentioned in a log message to the Change Request.

For performance reasons, this did not take into account whether the mentioned Change Request actually exists for this resource.

However, this behaviour has been found to be confusing if for example editors mention a CR from a remote CKM.

To avoid confusion if Change Requests are mentioned in the log message that do not belong to this resource directly, these Change Requests should not be displayed as direct links. Only Change Requests (open, in process or closed) for the resource at hand should be extracted and displayed.

36

CKM-2076

When exporting a project or incubator as a zip, the zip filename should indicate the type (project or incubator) and its name

When exporting a project as a zip, the zip filename should contain the project name in order to clearly separate different project downloads. In case that the filename contains characters that may be problematic they need to be replaced/excluded to ensure a valid filename is suggested on download.

Also the filename should differentiate between incubator and project,

e.g.

  • project_Common_Resources_2024_04_03-12_15_37.zip

  • incubator_Health_Assessment_Scores_2024_04_03-12_15_37.zip

37

CKM-2078

Overview of all Projects/Incubators: Add number of owned, referenced and remote resources to each project

Add number of owned and referenced & referenced from remote archetypes and templates to each project in the overview of all projects and incubators available from the Projects menu. This is helpful in many ways, e.g. in determining which projects may be easy to clean up etc.

 

38

CKM-2079

Improve error message to clarify that a "status code 0" error is most likely caused by an internet connection problem

If the user has no internet connection, or a very unstable one, the user may be presented with “Status code 0” error messages. While there is a general explanation that this error may be due to an internet connection problem, a more detailed and dedicated error message would be helpful.

Therefore, add the following details to the error message in case of a status code 0 error:

This status code indicates that your request most likely failed because of a problem with your internet connection. Your connection is currently either not available or unstable. Please ensure that you have a stable internet connection and try again.

39

CKM-2080

Ensure that documents in each section of a resource centre are sorted alphabetically and case-insensitively

Currently, the documents are sorted in order of latest modification (upload time).

Even though typically the number of documents per section is limited, this seems undesirable.

Therefore, it is now ensured that documents in each section of a resource centre are sorted alphabetically and case-insensitively.

40

CKM-2081

New Comments should be tweeted using the canonical REST URL and should pick up the appropriate card image

When a new comment is tweeted, the canonical REST direct link to the comment should be used in the email notification as well as in a tweet (if configured).

In addition, social media linking to this REST URL should pick up the associated card image of CKM and display it in the post (e.g. tweet).

REST URL examples:

  1. <ckm-server>/ckm/archetypes/1013.1.1302/discussions/1013.18.1767

  2. <ckm-server>/ckm/projects/1013.17.52/discussions/1013.18.1901

  3. <ckm-server>/ckm/generaldiscussions/1013.18.1902

41

CKM-2083

More detailed warning if the Review Round Summary Email cannot be sent to one of the editors

The initiator of a new review round and the editors of the corresponding project, receive a summary email with information about the review round that has just been created.

In case one of the editors is not currently active (or theoretically: has just unregistered completely in this moment), CKM displays a warning to the initiator that the review round summary email could not be sent.

However, no further information is given, whereas in this case, the reason is that one of the editors is not active. This information should be added to the warning message displayed to the initiator of the review round.

42

CKM-2090

Finetune regex validation and display of archetype slots and correctly differentiate between literal parent archetype ids and regex patterns in slot assertions

Finetune regex validation and display of archetype slots and correctly differentiate between literal parent archetype ids and regex patterns in slot assertions.

When evaluating slot regexes need to be fully evaluated as regex patterns and then we need to validate if at least one applicable base archetype exists.

allow_archetype CLUSTER[at1030] occurrences matches {0..1} matches { -- Exertion include archetype_id/value matches {/ -- linebreaks for clarity only openEHR-EHR-CLUSTER\.level_of_exertion(-[a-zA-Z0-9_]+)\.v1| openEHR-EHR-CLUSTER\.level_of_exertion(-[a-zA-Z0-9_]+)\.v\d+| openEHR-EHR-CLUSTER\.level_of_exertion(-[a-zA-Z0-9_]+)\.v[0-9]+| openEHR-EHR-CLUSTER\.level_of_exertion(-[^.]+)*\.v.+| -- simplified openEHR-EHR-CLUSTER\.level_of_exertion(-[a-zA-Z0-9_]+)\.v[2-9]+/} }

However, the parent archetype here should not be treated as a regex.

archetype (adl_version=1.4; uid=0fcb36df-75c6-4b52-87c5-ecd6f7c6e9a9) openEHR-EHR-CLUSTER.inspection_body_fluid-urine.v0 specialise openEHR-EHR-CLUSTER.inspection_body_fluid.v0
43

CKM-2095

Deactivated editors should not be included as editors in review invitation emails

If the user account of an editor is (temporarily) deactivated, the editor should not be listed as Editor in review Invitation emails, nor as reply-to recipient of such emails.

44

CKM-2096

Templates with (annotation) paths where the name/value predicate has leading or trailing whitespace should be rejected on upload

CKM should reject any templates with (annotation) paths where the name/value predicate has leading or trailing whitespace.

In addition to preventing templates from being imported into CKM if they have a renamed node with leading or trailing whitespace (CKM-1353) which was deployed as part of CKM 1.16.0 release, the whitespace may also be in the name/value predicate of an an (annotation) path in the template ONLY. This leads to two different paths (one without extra whitespace and one with) and it is up to any downstream tooling to interpret these paths as identical or not, resulting in unnecessary discussions and errors.

Example problem, note the extra space in e.g. “ name/value=' Irgendwelche Medikamente“:

45

CKM-2097

Localise the language code in the Editor's Task list for a submitted translation

Localise the language code in the Editor's Task list for submitted translation.

When a user submits a translation and opts to notify the editor, a task is created in the Editor’s To Do List for the archetype.

This task should contain a localised version of the translation language (if possible depending on server locale), not only the language code, e.g. German de instead of just de.

See To-Do List featuring a new task and an old task:

 

46

CKM-2102

Finetune Audit Log and Audit Log CSV Export

Finetune the Audit Log in the following ways:

  • Add total number of found events to the Audit Log grid header

  • Improve the generic csv export filename to NOT include any “div”s or “span”s and associated class names (cp. Audit Log (31-Jan-2024 to 01-Mar-2024) div class= oi-font-smaller oi-italic oi-normal-font-weight _div _01-Mar-2024 08 23.csv).

  • Avoid adding a column that just includes an arrow icon name (such as arrow_***.svg). This indicates an action column in the original grid and does not to be exported.

47

CKM-2104

Ability to Add FHIR Mappings to Archetypes and Templates

It is increasingly recognised that openEHR and FHIR can and should be used in combination, with openEHR being focussed on long-term persistence and FHIR on data exchange.

For this to be supported, it is paramount to create detailed mappings from commonly used openEHR archetypes and templates to FHIR where and to the extent possible.

For this purpose, a new Tab has been added for each archetype and template, dubbed “Mappings & Queries” where mappings from openEHR to FHIR can be uploaded and maintained.

FHIR® Mappings formally document mappings between models, i.e. from openEHR archetypes and templates to FHIR® resources, or contextual mappings to FHIR® artefacts such as resources, profiles, bundles, or implementation guides. Mappings can for example be expressed with ''FHIR Connect'' or with mapping tables/spreadsheets. There are various approaches to mappings ranging from simple spreadsheets to formally defined YAML files based on the FHIR Connect Mapping Specification.

Since the need is very clear, but the exact formalism is not as of now, CKM at this stage will enable the upload of various filetypes including YAML and Spreadsheets and remain agnostic to the formalism used.

To display the mappings, some generic syntax highlighting has been added to CKM as well (see CKM-2128).

Projects have a new role of Mappings and Queries Editor enabling the management of these artefacts on a project-level. Clinical Knowledge Managers and Project Editors also hold these rights.

With this role, a FHIR mapping file can be uploaded to an archetype or template by providing the file, a title and optionally description, a FHIR Version (e.g. R5) the archetype or template revisions this mapping file applies to, and whether the mapping file is to be versioned. All uploaded mappings files are displayed. If a mapping file is NOT applicable to the currently displayed revision of the archetype or template (typically: the latest or latest published), a warning is displayed for this mapping. Each (text-based) mapping file can be viewed and each mapping file can be downloaded. Mappings and Queries Editors can edit and delete as required.

Note: This work is intended to cater for an immediate need expressed by various parties while some details remain unclear as of now. Depending on uptake this can be extended and finetuned as required in future releases of CKM (e.g. extract meta data from the file if the format and the meta data is agreed upon, provide more detailed governance, provide and overview of all mapping within a project, ability to download of all mappings, …).

Cp. CKM-1828, CKM-2119 and CKM-2132 for related functionality.

48

CKM-2105

Rework the Transform Execution of CKM Transform Engine to avoid problems with rogue transforms that never finish and/or consume excessive amounts of memory consumption

The CKM transform engine enables instance owners to configure their own XSL-based Transform scripts.

This poses the immediate question of what happens with transforms that never finish and/or use excessive amounts of memory, e.g. due to a loop that never finishes.

Since the inception of the Transform Engine, it already has the inbuilt capability to try to stop such transformations after a fixed timeout of 120s.

This has worked very well, however, in cases where a customer configured transform consumes excessive amounts of memory very quickly, this has the potential to bring down CKM before the transformation can be stopped, requiring a restart due to an Out Of Memory Error.

To better deal with user configured transforms that use excessive amounts of memory very quickly, this issue provides the following improvements:

  • Reworked transform task threads to improve the release of used memory.

  • Introduced a two step approach with two timeouts:

    • An initial short timeout. After this timeout most usual transforms will have finished. If however a transform has not finished, memory consumption is checked and based on this information it is decided whether it is possible to continue the thread or if it should be aborted immediately. If memory consumption is already high, the thread is aborted. If however, the transformation is just time-consuming, but not claiming excessive amounts of memory, the transformation can continue until:

    • A second longer timeout. If the memory consumption is ok, the transformation can continue for longer. This second time is needed because there are indeed longer running transforms that are complex and time-consuming but otherwise perfectly fine.

  • Added configurable timeouts with sensible defaults. CKM provides sensible defaults for these timeouts. However, depending on server configuration (e.g. RAM) and the configured transforms, some finetuning may be required.

  • Enhanced synchronisation: Avoid too many simultaneous transformations taking place.

  • Advanced logging into a dedicated log file for possible further future improvements of this.

  • On transform failure, remove the “Loading please wait” panel and display an Error panel instead.

49

CKM-2107

For deleted archetypes, templates and termsets, also audit log the project type and project name as well

For deleted archetypes, templates and termsets, also audit log the project type and project name as well as part of the description/comment.

This is potentially important information to figure out why a resource has been deleted and what the consequences of this are.

50

CKM-2108

Template Related Resource Panel: Finetune Display of directly vs. indirectly embedded templates

The Template Related Resources Panel lists embedded template of the template at hand, if any.

In case that there are multiple levels of embedding, the embedded templates are listed separately under the following headings

  • Directly Embedded Templates

  • Templates Indirectly Embedded Via Another Embedded Template

Typically, when templates have multiple levels of embedded templates, they are very large templates with lots of directly and indirectly embedded templates.

In this case, the current separation headings are easy to miss, however are important to differentiate.

Therefore, finetune to

  • slightly increase font-size.

  • add a top margin, and

  • increase the font-weight (bold).

51

CKM-2111

Menu: Remove twitter bird logo and add "x"

Menu: Remove Twitter bird logo and add "x" to “Follow CKM on Twitter” menu item in the help menu - as long as this is needed.

52

CKM-2117

Prevent files being 'dropped' to perform tasks when File Browse dialogue is open

As a user, I may want to drop files when taking relevant actions by simply dragging and dropping them.

When dragging and dropping a file using the File Browse dialogue in the browsers Google Chrome and Microsoft Edge, error messages may display when we hit the button CANCEL instead of Open in the File Browse Dialogue.

The file that was dropped may not display the file name. The user can still take action which may or may not be successful. We do not have these behaviours in Mozilla Firefox.

Therefore, it may be best to prevent the file drop when we have the File browse dialogue opened.

53

CKM-2118

Use Display text for UCUM units in DV_QUANTITYs

Most of the UCUM units are easy to read or at least easy to understand, however for some UCUM units, there are special display texts - see latest https://github.com/openEHR/specifications-TERM/blob/master/computable/XML/PropertyUnitData.xml and also latest additions from Silje Bakke at:

https://github.com/openEHR/specifications-TERM/pull/13/files#diff-7f87965dca60b3e9582ba03056984693493fb757a42dc9df481eb3dd60d05538 [ |https://openehr.atlassian.net/browse/SPECTERM-28][https://openehr.atlassian.net/browse/SPECPR-412|https://openehr.atlassian.net/browse/SPECPR-412|smart-link ]

The display text should be preferred for display purposes in CKM where available, e.g,

  • J/cm² instead of J/cm2.

  • °C instead of Cel

  • μg instead of ug

  • °F instead of degF

A tooltip should be added to show the full name of the unit (e.g. Joules per square centimeter) if available and the UCUM unit (J/cm2) if it differs from the display text.

54

CKM-2119

Ability to Add AQL Snippets to Archetypes and Templates

It is increasingly recognised by various parties that it is useful to be able to reuse ‘typical’ queries expressed in the Archetype Query Language (AQL).

For this purpose, a new Tab has been added for each archetype and template, dubbed “Mappings & Queries” where AQL snippets can be uploaded.

These snippets can be pure AQL snippets stored in a file with an .aql extension or might also be yaml, json or xml files with additional meta data accompanying the AQL definition.

CKM at this stage will enable the upload of various file types remain agnostic to the formalism used. To display the AQL, some generic syntax highlighting has been added to CKM as well (see CKM-2128).

Projects have a new role of Mappings and Queries Editor enabling the management of these artefacts on a project-level. Clinical Knowledge Managers and Project Editors also hold these rights.

With this role, an AQL file can be uploaded to an archetype or template by providing the file, a title and optionally description, the archetype or template revisions the Query applies to, and whether the Query file is to be versioned. All uploaded Queries are displayed. If an AQL file is NOT applicable to the currently displayed revision of the archetype or template (typically: the latest or latest published), a warning is displayed for this Query. Each AQL file can be viewed and downloaded. Mappings and Queries Editors can edit and delete as required.

Note: This work is intended to cater for an immediate need expressed by various parties while some details remain unclear as of now. Depending on uptake this can be extended and finetuned as required in future releases of CKM (e.g. extract meta data from the file if the format and the meta data is agreed upon, provide more detailed governance, provide and overview of all Queries within a project, ability to download of all queries, …).

Cp. CKM-2104, CKM-1828, CKM-2132 for related functionality.

55

CKM-2121

Improve the Published Translation Tweets and the 'Invitation of Reviewers Summary' Email by Localising the Translation Code

The tweet for a new published translation should be finetuned, so that the localised display name of the language code is used (if available), e.g. “German” instead of “de”.

 

56

CKM-2122

When submitting translation from one branch to another, the source branch should not automatically be marked as "resolved" by default (if the user does not unselect the corresponding checkbox)

When submitting a translation from one branch to another, the source branch should not automatically be marked as "resolved".

In scenarios where there is more than one translation on the source branch (or other content that has changed), this may not be desirable.

We already ask the user on submitting a translation from one branch to another whether the source branch should be resolved and only resolve the source branch if the user says so.

However, the corresponding “resolve source branch” checkbox is ticked by default.

 

To avoid accidentally resolving the source branch in cases where this is not desirable, this should be an active selection by the user.

Therefore:

  • Rework to use a Radio Group with two elements (yes= resolve source branch / no= keep branch active) with no choice preselected and the “Finalise Upload of Archetype Translation” Button deactivated until the choice is made may be appropriate here.

  • Add a tooltip explaining what “resolving the source branch” means and what the implications are.

57

CKM-2128

Add Syntax Highlighting and Copy-to-Clipboard functionality to Mappings, Queries, and other displays (ADL, XML, Release Set Markdown)

To properly display the new FHIR Mappings and OMOP mappings and AQL queries and subset models it seems very useful to improve the current display of technical artefacts such as ADL, XML, JSON, YAML, AQL, MARKDOWN, so that they can be viewed inline in CKM.

This can be used to improve the existing ADL and XML displays as well as well as the MARKDOWN Release set manifest (also of CKM 1.20.0).

To support syntax-highlighting, technically, in turned requires moving away from a text area based display of ADL and XML. This then requires an alternative way to select the ADL or XML (etc) directly and copy to the clipboard. This is because CTRL-A CTRL-C will only work within inputs such as text areas - otherwise CTRL-A will select all selectable text in CKM.

Therefore, a copy-to-clipboard button is added to the bottom right of these displays.

 

58

CKM-2132

Ability to Add Subset Models to Archetypes

Subset models showcase subsets of archetypes that directly correspond to another model in another approach/formalism. For example, if only some elements of an archetype designed as a maximum dataset can be mapped to a FHIR® resource, this subset model or subset archetype would be stripped down to only contain these directly mappable elements while guaranteed to be consistent with the (maximum dataset) archetype. Subset models can be stand-alone or be defined in addition to or in combination with mapping files to e.g. OMOP or FHIR.

To managed subset models, a new Tab has been added for each archetype, dubbed “Mappings & Queries” where Subset Models, expressed as ADL, can be uploaded as well. To display the ADL some generic syntax highlighting has been added to CKM as well (CKM-2128).

Projects have a new role of Mappings and Queries Editor enabling the management of these artefacts on a project-level. Clinical Knowledge Managers and Project Editors also hold these rights.

With this role, a Subset Model can be uploaded to an archetype by providing the file, a title and optionally description, the archetype revisions this Subset Model applies to, and whether the model is to be versioned. All uploaded subset models are displayed. If a Subset Model is NOT applicable to the currently displayed revision of the archetype (typically: the latest or latest published), a warning is displayed for this Subset Model. Each Subset Model can be viewed and downloaded. Mappings and Queries Editors can edit and delete as required.

Note: This work is intended to enable further exploration of this approach after interest has been expressed by various parties while some details remain unclear as of now. Depending on uptake this can be extended and finetuned as required in future releases of CKM (e.g. extract meta data from the file if the format and the meta data is agreed upon, provide more detailed governance, provide and overview of all subset models within a project, ability to download of all Subset Models, Support in creating Subset Models from the existing archetype, ensuring its consistency.

Cp. CKM-1828, CKM-2104, CKM-2119 for related functionality.

59

CKM-2141

OPT generation should honour a language explicitly stated in the oet file over CKM's configured resource display locale

OET files are assumed to be in one language, for example use, purpose etc. are not available in more than one language. Also for example, annotation paths may rely on name/value constraints, thus implying one specific language. On the other hand, OPT generation can be done using any language available in the underlying archetypes.

On top of this, the OET format does not explicitly state the language it is intended to be in. To compensate for this, CKM uses its configured preferred "resource display locale" to determine the language used for OPT generation. This works fine in most cases: The international CKM has English templates, regional CKMs have templates in their own language.

However, there are cases, especially in Europe, where templates with a mixture of languages are required, for example English and German, or also where countries have multiple official languages.

When Archetype Designer exports an OET file, it asks for the export language and uses this to export the oet accordingly. For lack of other options, the export language is stated in the oet template’s other_details field as follows:

Given this and the absence of a formal specification, for practical purposes, OPT generation should prefer a language explicitly stated in the oet file over CKM's configured resource display locale.

If no language is specified in the template, the usual CKM fallback process for language selection will be used (as is).

60

CKM-2153

Ensure that the most recent version is loaded when opening a resource from the left-hand explorer

When CKM is open and another user or the REST-API updates a resource on the trunk, there needs to be a better process on how this update is propagated to a CKM already opened by another user at the time of the update. It is also possible that in this browser, the user is currently looking at the Resource in a CKM tab.

It needs to be ensured that the LATEST version is available for the user when opening the resource e.g. from the left-hand accordions - even if this version was not available when the user loaded CKM or last refreshed the left-hand explorer. Previously, this was handled by not supplying a version and thus automatically retrieving the latest version. This approach however was faulty and a subsequent regression led to the problem that this was not actually updated automatically when needed.

A preferred approach is to check at the time of opening the resource (e.g.) via dbl-clicking on it in the left-hand accordions - as QUICKLY as possible if a resource

  • has been updated, or

  • has an updated main content status (e.g. changed from DRAFT to TEAM_REVIEW).

If so, the resources required main data needs to be re-retrieved in order to:

  • Update the selected tree node in the left-hand accordion (name, status icon, tooltip).

  • Open the correct latest version of the archetype, template, termset or release set.

  • Refresh any other open CKM tabs for this resource the user may have open to ensure it is now known that the resource as displayed is no longer the latest version. In this case, the user is alerted to this update with an Information Message.

  • Refresh the CKM Dashboard to ensure the News are updated as required as well.

Also, when the user right-clicks on the resource in the left-hand accordions, it also needs to be checked before the context menu is displayed whether the resource has been updated. If so, the update process as described above is executed and the context menu constructed and displayed as soon as it is guaranteed that this relates to the latest revision.

In addition, when an open CKM Resource Main Panel switches its view to the Revision History, it is checked whether the latest revision as known matches the latest revision as retrieved from the revision history. If not, any CKM tabs for this resource (including self) are also updated as described above.

 

 

Bug Fixes (26 issues)

Key

Summary

Bug Fix Description

Key

Summary

Bug Fix Description

1

CKM-1991

Removing a template from a Release Set may cause the "Recalculating" Wait Dialog to never disappear

When removing a template from a release set again (e.g. directly in the creation process), the Associated Assets may fail to properly recalculate and display a modal popup forever.

This happens most likely if the template to be removed contains a large number of archetypes.

This can most reliably reproduced by adding e.g. 3 large Composition templates to a new Release Set and then removing them again one after the other. This doesn’t always fail, but often.

2

CKM-2038

Catalan Localisation Fixes for 1.20.0

  • Ensure UTF-8 for shared Catalan localisation

  • Split localisation key for resource owned by project/incubator

  • Finetuning of various other localisation texts

3

CKM-2052

Translation editor, Terminology Editor and Terminology Reviewer roles are not localised in the "Welcome to Project" emails to the user

Translation editor, Terminology Editor and Terminology Reviewer roles are not localised in the "Welcome to Project" emails to the user.

Steps to reproduce:

  1. Login as CKA or Technical Administrator

  2. Open a project and go to the Project Members tab

  3. Choose a user to be added in “Add Users to Project” and one of the roles Translation editor, Terminology Editor and Terminology Reviewer.

  4. Click on “Add Users to Project” Button

The new Translation editor / Terminology Editor / Terminology Reviewer gets an email where it says: “You have been added to the XYZ as translation-editor.”

Note that translation-editor is not localised for any language, but identical in all CKM translations.

In English it should read “You have been added to the XYZ as Translation Editor.”

Note: Except for the failed localisation, all emails are sent out correctly.

Error Message

4

CKM-2058

Gray and ocean blue themes: The X to close the configurable alert should be more clearly visible

The X to close the configurable alert (e.g. after an upgrade to point to the release notes) should be more clearly visible, otherwise it is easily missed.

This is ok in the usual blue theme, but a bit hard