User Guide: OpenMRS Dictionary Manager

Owned by Bruce Makaaru
Last updated: Jun 09, 2021 by Ellen Ball
9 min read

User Testing Pointers

Please follow this link to test the application.
Key pointers:
- If you do not have credentials, use the old OCL to sign up, and then be sure to come back to the new OCL client, here.
- If you are unable to login even after you had signed up, the database may have been reset and you would have to sign up again

All feedback can be shared at the user feedback discussion channel on Talk.


Login

To login, provide your registered username and password, then click the "Log in" button. 

Note: You can use your credentials from the Traditional OCL or click the "Sign up" link to register a new account, which will take the user to Traditional OCL.


User Home

After successful login, the application will redirect to the homepage. This page contains a list of the Dictionaries you created. Users can also navigate to the tabs side by to see

  • Your Organizations' Dictionaries: Dictionaries that are created and maintained under the Organizations they're member of 
  • Public Dictionaries: Dictionaries across OCL that are enabled with Public view access. This will also include the Dictionaries created by the user themselves if it has Public access enabled. 

You will have the option of creating a new Dictionary by clicking the "Create New Dictionary" button (circular plus icon).


Your Organizations' Dictionaries

Users who are part of an organization can create Dictionaries under that organization and also can contribute to the Dictionaries created by other members of the Organization. Below page allows the users to browse through such Dictionaries that are created and maintained under the Organizations they're member of. 


Public Dictionaries

Users can browse through all the public dictionaries, including those that belong to other people/organisations. Users can switch tab from their landing page to Public Dictionaries, which will take them to below page



New Dictionary

A real-life user may be creating dictionaries for different reasons, e.g. they may be creating an implementation dictionary for a specific hospital, or a starter set that will eventually be used by multiple hospitals. The UI for these is the same. Click "Create New Dictionary" to get started.


Field level details:

  • Dictionary name: Commonly used name for the dictionary
  • Shot code: Mnemonic used to identify the collection in the URL (usually an acronym e.g. Community-MCH)
  • Description: Details about the collection
  • Preferred Source: Source from which the concepts are going to be referred from.
  • Owner: Logged in user or the organizations that the user is member of
  • Visibility: Public access would enable people across OCL to view the Dictionary and subscribe. Private access would allow only the Owner to view and manage the dictionary. 
  • Preferred language: Language in which the concepts needs to have their names displayed on the UI.
  • Supported language: This helps while defining the translations for a concept where the locales will be based upon the languages selected here.

User will be taken to the same page when they want to edit a dictionary. Fields such as Short code, Owner cannot be changed from the value defined while creating the dictionary.

Dictionary Overview

Click on any of the available Dictionaries to access its overview page. This includes:

  • General details (Description, Owner, Access, ... )
  • Concept counts (From Preferred Source, Custom concepts from other Sources, ... )
  • Option to view the list of concepts in the HEAD version of the dictionary
  • A list of released versions with options to:
    • Create new version of the dictionary
    • Release/Unrelease a version of the Dictionary
    • Copy the Subscription URL, which can be used in OCL Subscription Module for importing the concepts from a OCL Dictionary into OpenMRS.
  • Option to edit the Dictionary

Releasing a Dictionary Version

Subscription to an OpenMRS dictionary should be made using a published version of a dictionary/collection on OCL. You can release a dictionary version, essentially creating a frozen 'checkpoint' for the contents of your dictionary. Clicking the 'Create new version' button will give the following prompt;

Name your version and provide an optional description. Note that the version name must be one you have not used before, e.g you cannot release two 'Version 1's.

You can mark the Release status as Yes/No, indicating whether this version of the dictionary can be used for subscription or not. 

Providing these details and confirming the version creation will add that version to the list;

Please note that once a dictionary is versioned, you cannot modify the concepts in that version of the dictionary. Any changes required in the list of concepts can be done only on the HEAD version of a dictionary and only upon creating a version of it, users can subscribe to that dictionary. 

Users can see the list of concepts in each version by expanding the Actions button (3-dotted icon) and by clicking on the View concepts button. 

Users can then use the subscription URL to import a particular dictionary version.

For example, in the previous example, we have two release versions. The URL for version 2 is this;

https://qa.openconceptlab.org/users/admin/collections/TestVersions/2/

and for version ID 1;

https://qa.openconceptlab.org/users/admin/collections/TestVersions/1/


Dictionary Concepts

Click "View Concepts" to view the page similar to the one above. This shows a tabulated list of all Concepts in the HEAD version of the Dictionary with options for Search, Filter, Edit, Remove, and Retire

Note: Concepts that are imported from a source can only be Removed from a dictionary. Custom concepts created within the dictionary can be Edited and Retired but cannot be removed from the dictionary. 

Add Concepts To Your Collection (e.g. Add CIEL Concepts)

Users can add concepts to a dictionary by two ways:

  • Import concepts from a source (e.g. CIEL)
  • Create a custom concept within the dictionary

Add Concepts from a Source

Users can add concepts from a source, either by

  • Picking concepts from the source
  • Bulk import concepts with concept IDs

Pick concepts:

Select the desired source from the list and use the search field and/or the filters to find your desired concept then click "Add to Dictionary" to add it to your Dictionary. It is possible to add multiple concepts in a search result list by clicking on the result row (not the concept name), then using the checkboxes and then pressing the "+" button at the top right. Already added concepts are represented by tick mark and you can also filter by retired concepts.

To see a preview of a Concept, click the Concept Name, which will take the user to a page similar to below

Bulk Add Concepts

To add existing concepts in bulk:

  1. Select the bulk import option to Add concepts
  2. You can switch between the preferred sources (top right corner) from where the concepts are to be imported into the dictionary.
  3. If you already have the Concept IDs, simply write/paste them into the Concept IDs field
  4. Click the "Add Concepts" button
  5. You can track the progress of the import in "Progress Notification" page (shown below)


Update A Concept's Version

Adding a CIEL concept adds the latest published version of that concept from the CIEL source to your collection. A later release of CIEL may update this concept with new information or mappings. If you would like to have these updates in your collection, simply remove the concept and then add it to the collection again. This will pull in the latest version of the concept once again.

Removing a concept from your collection

Clicking the remove button removes a concept from your collection.

Create a new concept

Click "Create new concept" then select the class of the Concept you wish to create. Fill in the form with appropriate values for Names, Descriptions, Mappings, e.t.c and click "Submit".

Create a concept example


Update a concept in HEAD version

Once a concept is added to the HEAD version of a dictionary, it only takes the reference of that concept's latest version from the CIEL source at that moment to the dictionary. Any updates done on the concept to CIEL at a later point of time will not be taken to the dictionary automatically. Users can update the concepts in a dictionary by manually removing the concept from the dictionary and adding it again. This updates the concept to its latest version in the HEAD of the dictionary. Users can create another version of the dictionary which will then have the latest version of the concept and can be subscribed to by an OpenMRS server.  

Your Sources

Users can view all sources by clicking the sources tab(second tab at the top left corner of the page). This page contains a list of the Sources you have created. Users can also navigate to the tabs side by to see

  • Your Organizations' Sources: Sources that are created and maintained under the Organizations they're a member of 
  • Public Sources: Sources across OCL that are enabled with Public view access. This will also include the Sources created by the user themselves if it has Public access enabled. 

You will have the option of creating a new Source by clicking the "Create New Source" button (circular plus icon).


Your Organizations' Sources

Users who are part of an organization can create Sources under that organization and also can contribute to the Sources created by other members of the Organization.. The below page allows the users to browse through such Sources that are created and maintained under the Organizations they're members of. 


Public Sources

Users can browse through all the public sources, including those that belong to other people/organizations. Users can switch tab from their Sources page to Public Sources, which will take them to the below page.

New Sources

Click "Create New Source"  (circular plus icon) at the rightmost bottom of the page to create a new source.

Field level details:

  • Source name: Commonly used name for the source
  • Short code: Mnemonic used to identify the source in the URL (usually an acronym e.g.-CIEL)
  • Description: Details about the source
  • Owner: Logged in user or the organizations that the user is a member of
  • Source Type: Type of source like dictionary or external
  • Visibility: Public access would enable people across OCL to view the Source. Private access would allow only the Owner to view and manage the Source. 
  • Preferred language: Language in which the concepts need to have their names displayed on the UI.
  • Other languages: This helps while defining the translations for a concept where the locales will be based upon the languages selected here.

Users will be taken to the same page when they want to edit a Source. Fields such as Short code, Owner cannot be changed from the value defined while creating the Source.

Source Overview

Click on any of the available Sources to access its overview page. This includes:

  • General details (Description, Owner, Access, ... )
  • Concept counts (Active Concepts  and Retired Concepts )
  • Option to view the list of concepts in the HEAD version of the source
  • A list of released versions with options to:
    • Create new version of the source
    • Release/Unrelease a version of the source
  • Option to edit the Source

Releasing a Source Version

Users can release a source version, essentially creating a frozen 'checkpoint' for the contents of the source. Clicking the 'Create new version' button will give the following prompt;

Source Concepts

Click "View Concepts" to view the page similar to the one above. This shows a tabulated list of all Concepts with options for Search, Filter, Edit, Remove, and Retire.

Add Concepts To Your Source

Click "Create custom concept" then select the class of the Concept you wish to create. Fill in the form with appropriate values for Names, Descriptions, Mappings, e.t.c and click "Submit".




Your Organizations

Users who are part of an organization can create, view,  and edit Organizations. Users can view the page by clicking the My Organization tab (the second last tab) at the left corner of the page. The below page allows the users to browse through all the user's Organizations they are members of. 

Public Organizations

Users can browse through all the public Organisations. Users can switch tab from their landing page to Public Organizations, which will take them to the below page.

New Organization

You can create an Organization so that members of your Organization can share content. The UI for creating an organization is to Click "Create New Organization" to get started. Then the user will be redirected to Create Organization page as below.

Field level details:

  • Organization ID: ID of an organization like, CIEL
  • Organization Name: Name of an organization like, Columbia International eHealth Laboratory
  • Company: Name of the company organization is associated with like, Columbia University
  • Website: Website of the organization like, http://ciel.dbmi.columbia.edu/ciel/?q=content/columbia-international-ehealth-laboratory-ciel
  • Location: Location of the organization like, New York City, NY, USA
  • Public Access: Public access would enable people across OCL to either view, edit, or none of them to the organizations. 

Users will be taken to the same page when they want to edit an organization. Organization ID field cannot be changed from the value defined while creating the organization.

Organization Overview

Click on any of the available Organizations to access its overview page. This includes:

  • General details (Name, Company, Website, Location, Public Access)
  • Members (List of members associated with the organization with add and delete members button)
  • Sources(list of sources of an organization)
  • Collections(list of collections of an organization)
  • Option to edit the Organization

Add Member to an organization

Users can add members to an organization by clicking the ADD NEW MEMBER tab inside the Members box. (You will need to first find the correct organization by going to the Organizations tab and searching for the organization. You will also need to be a member of the organization in order to add a new member.)

You will need to use the member's OCL username. They can get this username by signing up for OCL here: https://app.openconceptlab.org/#/accounts/signup

Delete Member to an organization

Users can delete members to their organization by clicking the delete icon inside the Members



Other OCL for OpenMRS Wiki Resources

Non-Technical Users: Getting Started with Dictionary Manager

Road map: OpenMRS Dictionary Manager

MVP Testing Scenarios


Miscellanous


The hierarchical relationship  between concepts vs sources vs collections ?

For any concept either custom or belonging to an organization , they belong to a source ,

Collections are stacks or categories of sources from which do concept grouping.