Knowledge Manager Primer
The guide introduces the user to the COSMIC Knowledge Manager and has been written by the Clinical Modelling Group at Cambio Healthcare Systems. If you have any questions or would like to provide feedback on this document, please send us an e-mail at firstname.lastname@example.org.
All the best,
Clinical Modelling Group
Syeeda S. Farruque
The COSMIC Knowledge Manager (KM) is a web-based platform for viewing and testing GDL guideline applications.
The KM requires users to upload resources required for the proper functioning of the guideline application. The currently supported resources include: archetypes (ADL files), guidelines (GDL files), templates (OET files), views (DSV files), terminologies, studies and apps. To successfully view and test an application, users must upload at least one archetype, one guideline and one view modelled for the same clinical concept. The KM acts as an interaction platform for the resources required to execute a guideline application.
In addition, the KM supports a generation of different statistics that help the user measure and benchmark the performance of the guideline application. Speed of execution, number of guideline executions within a specified time period, number of guideline rules fired during execution, number of archetype elements used during guideline execution, among other statistics.
The KM is a veritable and powerful yet simple way to view and test modelled guideline applications before deployment to production systems.
Navigate to the website of the KM via the following URL: https://clinical-modelling-group.cambiocds.com/km/ and you will be presented with a login prompt that requires access credentials.
Enter your login credentials (Username and Password) at the prompt and click on Sign in.
As ‘user’, one has read-only privileges and can view all previously uploaded resources and automatically generated statistics, while as ‘admin’ one can also upload new resources (or resource versions) to the KM.
After login, the user is presented with the index page showing a list of all previously uploaded and available resources (if any), as well as all the keywords that have been automatically generated.
The following image shows the index page of the KM in an empty state (without any uploaded resources). The index page displays a listing of all individual resources that have been uploaded, and if no resources have been uploaded, the message “There are no resources to show” is displayed. Similarly, clicking on any of the individual resource links (guidelines, archetypes, templates etc.) reveals the same message.
The image below shows the same index page as above after some resources have been uploaded. There is now an alphabetic listing of all uploaded resources, each with an icon depicting what type of resource it is. There is also a keyword cloud that has been automatically generated, which presents the detected keywords in alphabetic order.
Next, we identify and describe the major items visible and accessible from the index page. Some of the items are visible on every page in the KM and to all types of users; other items are only visible when logged in as an administrator, and these are mentioned in the descriptions that follow.
- Link to the KM index page (default landing page after login), which shows a list of all available resources as well as a keyword cloud automatically generated from the contents of the resources.
- Link to the KM guidelines page, which shows a list of the guidelines (GDL files) that have been uploaded.
- Link to the KM archetypes page, which shows a list of the archetypes (ADL files) that have been uploaded.
- Link to the KM templates page, which shows a list of the templates (OET files) that have been uploaded.
- Link to the KM terminologies page, which shows a list of the terminologies that have been uploaded.
- Link to the KM studies page, which shows a list of the studies (STD files) that have been uploaded.
- Link to the KM views page, which shows a list of the views (DSV files) that have been uploaded.
- Link to the KM apps page, which shows a list of the applications (APP files) that have been uploaded.
- The admin button links to the admin page where the user can upload resources (archetypes, guidelines, views etc.), delete all uploaded resources (flush the KM), or retrieve resources from an alternate source. This button is only available when logged in as an administrator.
- The statistics button links to the statistics page where the user can view diverse statistics including the number of times a guideline has been executed, time taken to load or execute a guideline, results of a guideline execution, number of archetype elements used or guideline rules fired during execution, and all over different time periods. Statistics can include counts, averages, comparisons against the average etc.
- The logout button ends the active session.
- The search filter allows the user to filter the list of visible resources by language, keyword, or other characteristics.
- This check box allows the user to toggle between viewing only the latest versions of the uploaded resources, or viewing all available resources (including duplicate resources with different versions). With the box unchecked, all available resources are shown and duplicate resources (with multiple versions) are indicated with version numbers.
- Alphabetic listing of available resources. Depending on the status of the toggle check box (13), listing may or may not include duplicate resources with version numbers. The icon preceding the resource name is unique to the resource type (archetype, guideline, view etc.).
- The keyword cloud is automatically generated by the KM, using the contents of the available resources.
The admin page is accessible from the admin button, and only to users who are logged in with administrator credentials. From the admin page users can upload resources (archetypes, guidelines, views etc.), delete all available resources (flush the KM), or retrieve resources from an alternate source. To access the admin page, click on the admin button as shown below.
The admin page allows the user to perform a number of tasks:
- Open the file selection dialogue box to add resources to the upload queue.
- Retrieve resources automatically from a remote repository without having to queue them.
- Delete all available resources and return the KM to a clean (empty) state.
- Upload all queued files at once (upload all), cancel an upload queue in progress (cancel all), or remove all files in an upload queue (remove all).
To upload a resource to the KM requires that the user is logged in with administrator credentials. This can be confirmed by the presence of the admin button shown previously.
From the admin page, click on choose files to access the open file dialogue box.
Resources should be added to the upload queue according to resource type, and in the following order: archetypes, guidelines, templates, views.
From the open file dialogue box, navigate to the folder on your computer where the archetype (ADL) files are located. If the modelled clinical concept uses multiple archetypes, be sure to include all relevant archetypes. To select multiple archetype files, hold down the control (CTRL) key on the keyboard while selecting the archetypes for upload. When done click on open as in the image below.
When done selecting archetypes, click again on the choose files button and this time navigate to the location of the guideline (GDL) files for upload. Select the relevant guidelines in the same manner and add them to the upload queue. In the image below, the five archetype files added in the previous step are just visible behind the open file box.
If the model includes template (OET) files, they can be uploaded next. View (DSV) files are next in order, following the same procedure.
When all the necessary resources have been added, they can be viewed in the upload queue as in the image below. The upload (solid arrow) and remove (broken arrow) buttons set in-line with each resource can be used to individually upload a single resource to the KM, or remove it from the upload queue. Batch upload or batch removal of all files in the upload queue is accomplished using the upload all (green) and remove all (red) buttons respectively.
Click the upload all button to perform a batch upload of all the queued files.
When the upload is complete, the individual file upload bars and overall queue progress bar are filled blue and the status of each uploaded resource will carry a black check mark when finished ().
To avoid caching issues, terminate the current session by clicking the logout button (step 1) and refreshing the browser page (step 2).
You will be redirected to the login page; enter login details and sign in.
After signing in, click on the “COSMIC Knowledge Manager” logo (Step 1 below) to go to the index page. The highlighted area in step 2 is an alphabetic listing of the uploaded, and now available, resources on the index page. Step 3 is the keyword cloud generated automatically from the uploaded resources, and step 4 is the toggle button to enable/disable viewing of multiple versions of a resource.
Toggling off the checkbox in step 4 results in an alphabetic listing of the resources, along with version numbers as in the image below.
The guidelines page is accessed by clicking the guidelines tab (step 1).
Selecting a guideline from the list (step 2) defaults to its description tab (step 3) with metadata (guide details etc.) and definition information for the guideline. Step 6 allows the user to toggle between available languages in which the guideline was modelled (English and Swedish in this example). Step 4 is the graph tab and step 5 is the source tab.
The graph tab shows the relationships between resources (archetypes and guidelines) used in modelling the clinical concept. The image below is the graph tab of the MELD assessment guideline and shows the relationship between MELD score observation archetype (item 1), MELD score assessment guideline (item 2), and MELD score evaluation archetype (item 3). “A/CDS” (items 1 and 3) implies that input for the assessment guideline “G” is obtained from a CDS observation archetype, and output from the assessment guideline is stored in a CDS evaluation archetype.
The next image shows the graph tab of the MELD calculator guideline and reveals the relationship between the resources used in modelling the MELD calculation concept. There are 9 (nine) contributing resources and the solid red arrow allows the user view an expanded image.
In the maximized view seen below, there are four EHR observation archetypes (coloured yellow) marked “A/EHR”, and they provide the input for the calculation guideline “G” (coloured green). Output from the calculation guideline is stored in four different CDS observation archetypes (coloured purple) marked “A/CDS”. For the latter (CDS) observation archetypes, the MELD score observation is the input source for the MELD assessment guideline described earlier.
The source tab shows the ‘source code’ of the guideline, i.e. the contents of the selected guideline in raw guideline definition language (GDL).
- Allows the user to download the selected resource (in this example, the MELD score assessment guideline).
- Allows the user to download the selected resource along with all dependencies (related archetypes etc.).
- Allows the user to print the displayed source code data of the selected guideline.
The archetypes page is accessed by clicking on the archetypes tab (step 1).
Selecting an archetype from the list (step 2) defaults to its description tab (step 3) with metadata (archetype details, author details etc.) and definition information for the archetype. Step 6 allows the user to toggle between available languages in which the archetype was modelled (English and Swedish in this example). Step 4 is the source tab and step 5 is the mapping tab.
The source tab shows the ‘source code’ of the archetype, i.e. the contents of the selected archetype in raw archetype definition language (ADL).
- Allows the user to download the selected resource (in this example, the MELD score observation archetype).
- Allows the user to print the displayed source code data of the selected archetype.
The mapping tab shows how each data element (and each pre-set data value) within the archetype is mapped to an at-code.
AT-codes are automatically generated by the openEHR internal terminology system during archetype modelling, and take the format: atXXXX, where X is a positive integer between 0 and 9. In the image above, the solid red arrows point to some of the at-codes used in this archetype. For example, the dialysis history ordinal element maps to at0006, an ordinal value of 0 (zero), i.e. no history of dialysis maps to at0007, and an ordinal value of 1 (one), i.e. positive history of dialysis maps to at0008. AT-codes are unique only within an archetype.
The views page is accessed by clicking the views tab (step 1). A view file is simply a user-friendly visual representation of an underlying guideline application.
Selecting a view from the list (step 2) defaults to its description tab (step 3) with metadata (decision support view details, author details etc.) and definition information for the archetype. Step 8 allows the user to toggle between available languages in which the archetype was modelled (English and Swedish in this example). Step 4 is the graph tab, step 5 is the source tab, step 6 is the generated view tab and step 7 is the designed view tab.
The graph tab shows the relationships between resources (archetypes and guidelines) used in modelling the clinical concept that the view represents.
Because a view file is directly related to, and dependent on, an underlying guideline application, the resource relationship graph of the MELD view mirrors that of the MELD calculator guideline (see above), which the view represents. In the expanded graphical image seen below, just as previously, there are four EHR observation archetypes (coloured yellow) marked “A/EHR”, and they provide the input for the calculation guideline “G” (coloured green). Output from the calculation guideline is stored in four different CDS observation archetypes (coloured purple) marked “A/CDS”. For the latter (CDS) observation archetypes, the MELD score observation is the input source for the MELD assessment guideline as described earlier.
- Allows the user to download the selected resource (in this example, the MELD view).
- Allows the user to download the selected resource along with all dependencies (related guidelines etc.).
- Allows the user to print the displayed source code data of the selected view.
The generated view allows the user to inspect the data entry fields, and test the execution of the guideline application. It is the default view generated by Cambio Healthcare Systems’ Clinical Model Editor software (CM) using the archetype and guideline files as input resources. It captures the stepwise firing (execution) of guideline rules as trigger conditions are met, allowing for another level of troubleshooting at this advanced stage of model development.
- This is the language toggle button which allows the user to switch between available languages in which the view’s resources were modelled (English and Swedish in this example).
- This is the source file download button which allows the user to download the source code for the view as a text file.
- This is the share link button which allows the user to generate a URL that can be shared with others. The URL opens an expanded version of the generated view in a web browser, allowing others to inspect and test the application without requiring a login.
- This opens the generated view in a new browser tab/window.
- This column is for data input and shows the data entry fields required for (in this example) calculating the MELD score. The fields are generated from the data elements created while modelling the component archetypes. It is mandatory to enter an event time for any data value that is used as input.
- This column is for data output and shows the results generated from rule execution in the guideline application. As the user enters data and sets the event time, rules are executed on-the-fly if criteria for rule firing are met.
The image below is the same generated view as above, but with data entered in the variable input fields. Where applicable, measurement units have been selected, and for all input values an event time is mandatory. If the entered data (left column) meet any of the trigger conditions in the modelled guideline, the relevant guideline rule is fired and is added to the fired rules list (box highlighted in red). In addition, the results/outcome of the fired (executed) rules are shown in the output column (right column). This view allows the user to troubleshoot if a triggered rule fails to execute, or if a rule is executed without being triggered, among other possible issues.
The designed view allows the user to test the completely modeled guideline application without additional troubleshooting information present. It is created manually using separate html editing software with the default generated view as input. It presents a clean and simplified interface that allows the user enter data and view final output without observing the step-by-step rule execution.
Like the generated view, the user can toggle between display languages, click the share link button to generate a URL for sharing with others, and open the designed view in a new browser tab/window. The designed view can be visually customized to meet individual end-user requirements through hard coding, and as in the image above, is intended to be simple and show only the data entry fields (the event time defaults to the current date and time), the results of the calculation or protocol (in this example oMELD and MELD scores), and a list of references used in modelling the clinical concept.
The image below is the same designed view, but with entered input data. Guideline rules have been triggered and executed resulting in calculation of oMELD and MELD scores.
EHR archetypes and CDS archetypes
We have previously differentiated between observation archetypes and evaluation archetypes in another document, the Archetype guide. Now we also differentiate between EHR archetypes (A/EHR) and CDS archetypes (A/CDS).
The EHR module is a part of the electronic health record system (EHR). When a clinician enters patient data into an openEHR-based EHR system, the data is stored in EHR archetypes “A/EHR”.
The data in these EHR archetypes serve as data input to the clinical decision support (CDS) module.
The CDS module is a GDL guideline-based add-on to the EHR. When a CDS module receives data from EHR archetypes, it triggers the execution of one or more rules based on definitions in the GDL guideline. The result of the rule execution (calculation, protocol etc.) is stored in CDS archetypes “A/CDS”.
The KM is one of the platforms that allows interaction between the EHR module and CDS module.