CKM Release 1.18.0
Release Date: August 2022
Deployments: August - October 2022
Summary of Changes
The Clinical Knowledge Manager (CKM) Release 1.18.0 incorporates the changes of a total of 91 Jira Cards: 34 cards with new or significantly enhanced functionality, 35 mostly minor bug fixes and 22 changes “under the hood” of CKM, giving a myriad of improvements and extensions for CKM Editors and Clinical Knowledge Administrators, including:
Reusable review invitation templates that enable editors to setup new review rounds faster and more consistently.
Editors can now add additional (e.g. motivating) text directly to the review invitation email sent to the potential reviewers to increase the likelihood of reviewers participating.
Editors collaborating as a team are now able to display the various revision changes for each review feedback element to better support editor collaboration during the review feedback process.
Editors also benefit from an improved user interface to update contributors of archetypes, and a variety of other smaller improvements like improved warnings displayed before committing or publishing a resource, about uploading a resource to an outdated branch BEFORE submitting.
Normal Users benefit from the new release in many ways. The Archetype Data Points report has been enhanced and its performance has been improved significantly, the internal terminology client has been upgraded to support LOINC 2.72, the Welcome Emails have been improved, the Template Resource Centre has been cleaned up and the Archetype and Template Resource Centres now support JSON as Sample Data.
While maybe less relevant in the international context, CKM administrators can now bulk create and update users via uploading a CSV File - which is useful for national or regional programs as well as hospital groups using CKM for review purposes.
Various parts of CKM have been finetuned visually, with an improved and harmonised visual distinction of secondary headers in various CKM tabs, finetuned various project and subdomain related displays, improved the layout of the sticky note style (as used on the Dashboard and for editor comments), folded the ADL and XML tabs into one and finetuned some icons and various texts. Also, a new CKM theme based on navy blue & teal blue colours has been developed that can be configured for each CKM instance.
The REST API of the Clinical Knowledge Manager has been extended, for example by adding the ability to update the template status and by adding the semantic version numbers of the latest and latest published version to the listing of archetypes.
Minor bugs have been fixed in this release, most notably perhaps a fix to the Drag and Drop functionality when uploading files and improved support for Code System implicit FHIR® Value Sets which were not always automatically updated if cached from an external Terminology Server (such as Ontoserver®) connected to CKM.
“Under the hood” changes of CKM such as improved resilience of asynchronous mail sending if the configured mail server is temporarily unavailable, reworked and enhanced CKM connection handling and pooling, internal streamlining of the complete review invitation process, and a reworked subdomain export service that streamlines and thus also significantly improves the speed of - the resource export for larger subdomains.
Detailed descriptions of all changes in the following sections.
New & Improved Functionality (34 issues)
Key | Summary | Description |
|---|---|---|
CKM-444 | Reusable Review Invitation Text Templates | When editors initiate a review round, they need to supply an invitation text that is displayed to all reviewers on starting their review. To better support editors in initiating review rounds, functionality is added to CKM to define and then use and reuse review invitation templates. For this, CKAs can define review invitation templates with the following characteristics:
This functionality is available from the Reviews/Manage Invitation Templates menu. When creating a new review round, editors can select any applicable preconfigured review invitation template. This is done via a Button to import the invitation template which opens a window to select the desired invitation template. The selected review invitation template is then displayed in the usual review invitation text RichTextArea in CKM and can be finetuned for use in this particular review round, using the existing editing functionality. Any Review Invitation Text Template can contain a selection of placeholders to better enable the reuse. The following placeholders can be used in the Review Invitation Template:
Placeholders need to be wrapped like this: %{ … }% - for example: %{resource-type}% All placeholders are wrapped in percentage signs and curly brackets. To avoid problems with these placeholders, the invitation template cannot be stored if it contains an unsupported placeholder. Neither can a review round be created nor can reviewers be invited if non supported placeholders are found in any invitation text. Note that there are two types of invitation templates. Inline invitations are displayed inline in CKM when a reviewer starts to conduct a review. Custom mail invitation texts are ADDED to the usual invitation email in order to customise these emails, see CKM-1421: Ability to add additional (e.g. motivating) text to the review invitation email itself for details. Example invitation:
|
CKM-1274 | Improve warnings displayed before committing or publishing a resource (or initiating a review round) to look more like a checklist | When a resource is being committed or published, any warnings to check the archetype before committing or publishing are currently displayed like this: Likewise, these warnings are displayed when initiating a review round, however the layout is horizontal to save some space in the review round creation wizard. The display of these warnings has been improved to be be more like a checklist that shows what has been validated and where there are still warnings or errors. The number of errors/warnings has been added as a badge, and if there aren’t any errors/warning of a given type, then a green badge with a tick is used to clearly state that there no errors/warnings of the type, for example: |
CKM-1421 | Ability to add additional (e.g. motivating) text to the review invitation email itself | With this issue, we add the ability for editors to define an individual text that is included in the review invitation email. This email is sent out to the reviewers when an editor initiates a new review round. This text would usually be different to the complete review invitation text that is displayed to reviewers when starting their review in CKM. The latter is usually a fairly lengthy text with detailed instructions on how to review on what to take into account. The reason for adding the ability to specify an additional text for the email invitation (“mail-invitation-details”) is to increase the likelihood that a potential reviewer is interested in reviewing the resource under review in the first place and accepts the review invitation. This separate mail-invitation-details field that can be filled in during review round setup via a new step. This text then added to current invitation email sent out to the reviewers, just before the “Your Options:” paragraph. This functionality has been designed for editors to have maximum flexibility: Editors can provide completely different or also exactly the same content for both the invitation details displayed to reviewers in CKM and in the email. Of course, they can also completely omit the additional email invitation text, which simply preserves the status quo of the current review invitation emails. In case that the content of the two invitation details (email vs. in CKM) overlaps, the editors would need to enter (copy-paste) the relevant parts at both places when initiating the review round. To simply this, CKM-444: Reusable Review Invitation Text Templates also introduces reusable invitation text templates. |
CKM-1455 | Warn the user about uploading a resource to an outdated branch BEFORE submitting | When a user uploads an archetype to a branch and that branch is outdated, for instance, because another branch has been committed to the trunk in the meantime, this may cause problems or simply unnecessary editorial work down the line. While it is - and should be - possible to continue work on the branch and integrate the changes from the trunk accordingly, it may in some cases be preferable to start again with a new branch. Therefore, CKM will now present an warning when an archetype or template is uploaded BEFORE it is actually submitted to the outdated branch. The user can then consider to reject/resolve/delete the outdated branch first. This warning is in addition to the warning the user currently already gets after the submission to the branch has been completed. |
CKM-1475 | Editor functionality to show the revision changes for each review feedback element | When multiple editors work collaboratively on the feedback for a review round, it has so far not been possible to see which editor contributed to the Editor feedback in the reviews, i.e. added/changed and maybe even deleted the feedback for an element. This is of course desirable when displayed to the reviewers - the editors speaking with one voice. However, when there are multiple editors, it is useful as an editor to see the editor and timestamp for each feedback element. This is to be able to reconstruct and streamline editorial discussions (especially afterwards). As each item could be changed multiple times, the whole history of who changed what when is relevant for each element under review. For this purpose, a new button is added next to the button to “Add New Task” for each feedback element. This button (like the existing “Add new task” button) is only displayed when the feedback element is focussed and will display the complete Feedback History for the element. |
CKM-1536 | As an Editor, access the Reviewer's User Profile directly from Completed Reviews and Review Invitations | For editors, it should be possible to directly go to the user profile of a reviewer from the following grids:
If an editor right-clicks on a user in these grids, the editor can now select the new “View User XYZ” menu item to directly access the user profile. |
CKM-1539 | Enhance the Archetype Data Points report | The Archetype Data Points Report has been enhanced in the following ways:
|
CKM-1554 | Bulk Create/Update Users via CSV File Upload | A Clinical Knowledge Administrator (CKA) or Technical Administrator - both referred to as admin in the following - bulk creates users by uploading a csv file containing specific user details. Under certain conditions, details of existing users can be updated using the same approach. This use case starts when an admin is in possession of a CSV file with user details and wants to bulk create accounts for these users in CKM (or update some of the user details). This use case ends when CKM has created/updated the user accounts and provided respective feedback to the admin. CSV File Structure
Required columns:
Optional columns:
The username is constructed from <first-name>.<last-name> and does not need to be specified in addition. The secondary (recovery) email address is not commonly stated as part of the registration process and new users will be asked if they want to provide one at a later stage within CKM as per normal CKM processes. Health Domain and ProfessionIf health domain and/or profession are specified, the name of a specified health domain and profession needs to be provided exactly (case-sensitive) as in CKM, including the complete hierarchy, separated by forward slashes (“/”):
Note: If a class in itself contains a forward slash “/” this MUST be replaced with a pipe symbol (“|”), for example for Health domain: Additional Input OptionsIn addition to the input from the CSV file, it is possible to make some additional choices in the CKM GUI that apply to all users to be created:
Preconditions
Basic Flow
Exceptional Flows
|
CKM-1602 | Create a new CKM theme based navy blue & teal blue colours | Ocean has developed a new theme for CKM based on navy blue and teal blue colours. Customers who want to switch to this theme, please contact Ocean. Note: The background of the top header can be either in navy blue as in the screenshot below or in white. |
CKM-1603 | Improved User Interface to Update Contributors of archetypes | The user interface to Update Contributors of archetypes has been enhanced in the following ways:
The Update Contributors functionality is available from the menu of an active branch in the Archetype Revision History |
CKM-1615 | Improve the layout of the sticky note style (as used on the Dashboard and for editor comments) | Improve the current “sticky note” style used in some places of CKM to look more modern (and less like a sticky-note). This includes:
Harmonise with the style used for the right hand side explanation of the “Register as a new user” tab. |
CKM-1628 | Add caching to the Archetype Data Points report | Currently, compiling the Archetype Data Point report takes a fair while in CKMs with many archetypes. This is not only time-consuming but also quite a drain on the server resources at the time of compiling the report. To reduce, the (typical) time required to open the most common reports, CKM now caches the latest compiled reports. This - WHEN cached - reduces the amount of time to close to 0. The cache cannot be used when resources in private incubators are possibly selected while the user requesting the report is not a technical admin or Clinical Knowledge Administrator. This is because the report only considers archetypes visible to the user. |
CKM-1635 | Add support for non top-level pipes in Slot regexes | Slots with regular expression containing non top-level pipes (inside one archetype id expression), e.g. are now considered valid by CKM following the discussion at https://discourse.openehr.org/t/medication-order-medication-details-dosage-ready-for-republication-as-a-new-major-version/2208/10 In addition, the general validity of the regex should be evaluated and reported as a VDFAI error if invalid. |
CKM-1642 | Update layout/colour of the default button | Update layout/colour of the green default button style. Often, nowadays, a blue colour is used for a default action rather than a green colour and this also harmonises better with the CKM themes. |
CKM-1649 | "Refresh All" should also check if a resource has been updated and change the revisioning statement if required | The asset version displayed for e.g. an archetype or template will not change with the “Tools/Refresh All” functionality. This is so because there are various ways in CKM to open a specific version of an archetype or template and then we cannot just update this to the latest. It will however update the Change requests, reviews, etc, revision history i.e. anything that is not directly tied to a particular version of the archetype or template. What "Refresh All" should do however (and previously didn’t) is to refetch the data used for determining whether the latest revision is displayed or not. If the resource has been updated in between by someone else or e.g. an automated call to CKM’s REST API, the revision at hand is now an older revision and stating that it is the “LATEST REVISION” as in the example tooltip below is now incorrect. This is now updated on “Refresh All”, and it is thus
|
CKM-1650 | "Refresh All" should also refresh the Manage Users tab and other finetuning | When refreshing the panel via "Tools/Refresh All", an currently open “Manage Users” grid should also be refreshed to take into accounts to updates to the user base. In addition, the usage information that used to take up an extra line has been transformed into a tooltip next to the heading - only presenting the information when hovered over. |
CKM-1661 | Project members such as project reviewers should always be able to be invited to review rounds for resources of the project | Project members such as project reviewers should always be able to be invited to review rounds for resources of the project even if the user has otherwise indicated not to be a general reviewer for any resource. Based on the discussion at https://discourse.openehr.org/t/tooling-support-for-inviting-reviewers/2236/15 it is reasonable to assume that a main task of a project reviewer is to review the resources of the project, even if the user does not want to be involved in reviews for other projects. This needs to be clear in the selection process of whether a user would like to serve as a reviewer: The user can either select to be available as a reviewer for any applicable not blocked resource or only for any resources of the user's project. Note: Independent of this, a user can of course decline or ignore any invitation. This also includes the following work:
While this is intuitive, the exact rules of when a user can be invited are complex and have been summarised in the following table:
|
CKM-1670 | The "Active Review Round already exists" warning should be based on whether the previous review round has been closed or not, not based on the completion deadline | Previously, when setting up a new review round for a resource while a review round of the same type exists already for the resource to be reviewed, the initiator was warned that an active review round exists IF the completion deadline hasn't yet passed. However, it seems more reasonable to trigger the warning if the review round is still active (i.e. not closed by the editors). This is because the completion deadline may have passed a long time ago in some cases, but the review round may still be accepting reviews. Therefore: The "Active Review Round already exists warning" should be triggered based on whether any previous review round of the same type has been closed or not (and not whether the completion deadline has passed or not). Also, this warning was previously not currently triggered at all for template reviews. It should be triggered in the same way as for all other review types. |
CKM-1676 | Upgrade the internal terminology client to LOINC 2.72 | Upgrade the internal terminology client to LOINC 2.72 (February 2022) release. Note: Customer-specific configured terminology servers with a FHIR API can always be upgraded to use various terminologies at any time and take precedence. However, this is used to ensure all CKM instances can display LOINC term bindings etc. |
CKM-1678 | Update template status via the REST API | In CKM instances with for example well over 20,000 templates - based on an advanced tool-chain - it is important to automate the template publishing process. This issues introduces an extension to CKM’s REST API to be able to update the resource status of a template. PUT /templates/{cid-template}/status with parameter The |
CKM-1680 | Separate the service to "delete an user and delete all users" into two separate services with different privileges | Previously, there was one service that enabled the deletion (“unregistering”) of a particular user. This service featured an additional option to delete all normal users. This exists for administrative purposes only and would only ever be used by Ocean admins. To clarify this and also to improve the rights management for this service, this service has now been split into two separate services. Only the first service is available to non Ocean admins in the first place. |
CKM-1683 | Extend CKM's resilient mail sending service to also try to recover if the email was initially advised to be sent asynchronously | CKM's resilient mail sending service always tries to recover and resend emails if the configured mail server is temporarily down and did not accept any mail for whatever reasons. However, previously this only applied to emails that were advised to be sent synchronously initially. While this is the default for nearly all cases (because it enables feedback to the users if emails could not be sent), sending emails synchronously is fairly slow. For bulk operations requiring the sending of mail (like CKM-1554: Bulk Create/Update Users via CSV File Upload) synchronously sending the emails is far too slow. Therefore the same functionality to recover from a mail server that is temporarily down has been extended to emails that were initially advised to be sent asynchronously. |
CKM-1685 | Improve Welcome Emails | Improve the Welcome emails to new users - with or without activation required.
|
CKM-1686 | Clean up the Template Resource Centre sections | Clean up some aspects of the resource centre for templates, such as the CDA related group of sections which is likely unnecessary nowadays. In detail:
|
CKM-1691 | Improve the visual distinction of secondary headers in CKM tabs and harmonise the first header underneath the resource icon toolbar | Secondary headers are used in some places for further grouping in addition to the first heading, for example in the Resource Centre for Archetypes and Templates. However, the visual distinction between the first header underneath the icon toolbar (for a resource) and the secondary header was not always clear. This has been improved and harmonised. This applies to the headers underneath the icon toolbar for an archetype, template, termset or release set, as well as projects and subdomains. |
CKM-1692 | Support JSON as Sample Data in the Resource Centres | Sample data related to archetypes or templates can be uploaded to the Resource Centre of the resource. However, this is currently limited to XML whereas sample data nowadays often will be in json format. The advantage of using XML is that XML Sample Data can be displayed using various (configurable) transforms. This is potentially quite powerful, but has rarely been used (see e.g. https://ckm.openehr.org/ckm/archetypes/1013.1.130/resourcecentre and click on Render Sample Data for the uploaded Sample Data for an example.) Therefore:
|
CKM-1694 | Archetypes: Fold the ADL and XML tabs into one and finetune icons and texts | For archetypes, fold the ADL and XML tabs into one tab with archetype serialisations (ADL 1.4, ADL2, XML for now). The XML (1.4) tab is rarely used and combining the serialisation formats under one tab reduces the number of icons in the archetype toolbar. It also enables easier integration of more serialisations in the future. The ADL tab already has two options 1.4 and 2.0 and having the xml serialisation as part of the same tab seems reasonable and helpful. Also: Improve the ADL icon (but keep as ADL as the most common serialisation format) and the (related) ADL Validation Report icon) and update the tooltip and context menu text to “ADL / XML”. |
CKM-1699 | Various finetuning of subdomain related displays |
|
CKM-1711 | Minor finetuning of Project and Subdomain Export panels | Minor finetuning of Project and Subdomain Export panels to ensure that after clicking on the Export button,
This is so that a user get better feedback that the button has been clicked. Also, add an icon to the export buttons. (Note however: It is technically not possible to determine the exact point in time when the zip file is eventually presented to the user for storing/opening, therefore the time to end these temporary actions can just be estimated.) |
CKM-1712 | Harmonise heights in Review Round creation panel in all languages | Depending on the language, a few of the various panels that are displayed during the steps of setting up a new review round or modifying an existing Review Round had different heights. The heights have now been harmonised. |
CKM-1715 | Increase the height for the "Available as reviewer" and "Available as translator" and the "User roles" tab within the User Profile Panel & other minor finetuning | Up to now, all tabs of the User Profile had the same height. However, the 2nd, 3rd and 4th tab (reviewer availability, translator availability and the user roles tab) would benefit from making better use of the available height, especially when selecting health domain, professions or languages. Therefore, their height is now change accordingly on tab change. Also: Finetune wording and tab paddings. |