Short Link to this page: om.rs/translate

This documentation guides community members and implementers of OpenMRS in contributing to and managing translation, ensuring that OpenMRS can be utilized in various languages.

Here we will guide you through these main areas in OpenMRS that involve translation configuration work - Implementers need to know all 3, but Volunteers only need to use the first one:

Let’s get started!

Overview

Importance of Localization for OpenMRS

Localization is crucial for OpenMRS for several reasons:

• Increased Accessibility - Localization will make OpenMRS more accessible to non-English speaking users, expanding its reach and usability across different regions and cultures.

• Improved User Experience - Users can interact with the software in their native language, which enhances their overall experience and efficiency in using the system. This is particularly important in healthcare settings where clarity and understanding are paramount.

• Broader Adoption - As more regions can use OpenMRS in their local languages, the platform's adoption rates increase, leading to a larger, more diverse user base. This diversity can drive further improvements and innovations within the system.

• Community Engagement - Providing resources for volunteers to contribute to translations promotes a sense of community and collaboration. Volunteers worldwide can contribute to the project, bringing in diverse perspectives and expertise.

• Quality of Care - In healthcare, accurate communication is vital. Localized software helps ensure that medical records, patient information, and other critical data are understood correctly, reducing the risk of errors and improving the quality of care.

Who Should Translate?

Translation Volunteers

These individuals are proficient in English and at least one other local/native language and are interested in contributing to the localization of OpenMRS. They can range from community members, medical professionals, linguists, or anyone passionate about improving healthcare accessibility through better localization of the OpenMRS platform.

You can translate as much as you want, when you want. It’s only a matter of how much time and energy you are willing to invest as a volunteer translator.

Motivation

• Contribute to a global open-source healthcare initiative.

• Improve the usability of OpenMRS for non-English speaking users.

• Gain experience in translation and localization.

• Collaborate with a diverse, international community.

Skills and Knowledge

• Proficiency in English and one or more target languages.

• Basic understanding of translation tools (e.g. Transifex) or willingness to learn.

• Familiarity with medical terminology (helpful but not required).

• Attention to detail and commitment to quality.

Remember we want you to enjoy contributing and not burn out or lose interest.

Implementers

These are individuals or teams responsible for deploying and customizing OpenMRS for specific healthcare settings. They may include business analysts, project managers, developers, and IT professionals who work on configuring, translating, and maintaining OpenMRS distributions.

Motivation

• Ensure OpenMRS meets the linguistic and cultural needs of the local population.

• Facilitate smoother adoption and use of OpenMRS in non-English speaking regions.

• Provide comprehensive and accurate translations to improve user experience.

Skills and Knowledge

• Have an understanding of the OpenMRS architecture.

• Be familiar with internationalization (i18n) and localization (l10n) concepts.

• Be able to work with translation tools.

• Have an understanding and knowledge of healthcare and linguistic requirements of the implementation region.

Responsibilities

• Configure and maintain translated versions of OpenMRS.

• Coordinate with translators and review the translated strings.

• Ensure accuracy and relevance in the translated strings.

• Guide users/translators on how to use the localized OpenMRS system.

Current State of Localization

Localization involves translating the user interface, content, and metadata into different languages, allowing users to interact with the system in their preferred language. The current state of localization in OpenMRS is as follows:

• OpenMRS supports the translation of various UI components and metadata. However, this varies across different languages.

• OpenMRS has integrated automated translation tools on the site openmrs.org and automated the website's SEO results in multiple languages.

• Volunteer contributors primarily drive the currently available translations, and this guide highlights how one can get started.

Even though efforts have been put in place to help with translation efforts, there are still gaps and a need for clear documentation and guidance.

Existing Translation Infrastructure

The translation flow of OpenMRS consists of several tools and resources designed to help the localization process.

1. Transifex

   • This is the main tool used to manage the translation flow of OpenMRS. It provides a collaborative environment where volunteers can contribute translations, review peer submissions, and ensure quality contributions.

   • It gives a clear-to-follow and easy UI for the translators.

   • The platform is integrated with OpenMRS, allowing real-time synchronization of translated strings to the main application.

2. Auto-Translation Tools

   • With the help of automation tools such as Discourse Translator, the website can now be translated into different languages. This improves the SEO and attracts more non-English speaking users and translators.

3. Documentation and Guides

   • Some guides are already available, such as the one on using Transifex to translate the OpenMRS front end. However, these guides are not comprehensive.

   • In addition, the OpenMRS wiki includes high-level pages on translation but lacks detailed, step-by-step instructions for both translators and implementers.

4. Community and Forums

   • The forum, also called Talk, serves as a platform for discussion and support, where community members can seek help, share experiences, and collaborate on translation projects.

   • In addition to having the forum as a general chat place, threads are tagged with “translation” which provides updates related to translation efforts.

Guidance for Translation Volunteers

(Step 1) Translate Code Strings Using Transifex

Overview of Transifex

It’s our dream to provide a platform that can be used by anyone no matter the language they speak. To help us with this massive effort, we have integrated our open-source codebase with Transifex - A tool to help us localize our codebase.

The translation workflow is split into three main sources:

• Backend translation strings

• Frontend translation strings

• The concept dictionary

The first two sources are technical as they are built into the back or frontend but still provide localization keys and translation strings. The translation of these sources is automatically synchronized from Transifex so that when new strings are added, they appear on relevant frontend and backend modules.

As a translator, you can sign up on our translation platform and contribute translations in any of the 50+ languages enabled there.

Getting Started

If you have not contributed to our translations before, you will need to create an account. Head over to the Transifex using this link: https://www.transifex.com/openmrs/. Click on "Sign Up" to create a new account if you don't already have one.

After you finish the sign-up process using the link provided, you will be directed to the OpenMRS project but in case you did choose to sign-up directly on the Transifex site, search for the "OpenMRS" project, Click on the project, and then click "Join Team" to request access. Once approved, your landing page should look like the one below.

Explore the available languages and modules that need translation while familiarizing yourself with the project layout and the translation interface.

Select a Project and Resource

Once on the homepage, you should see multiple “resources” available for translation.

All of these projects contain files that need translation and on the main dashboard as shown in the screenshot above you can see the progress of each project. Select any project you want to contribute to, and you will see a list of available languages for translation.

Select the language you want to work on, and you will see all the resources under that project that need to be translated. Transifex provides different ways of selecting a language that you can translate. The first option is via the Dashboard, where you select a resource and language you want to work on, which will open up as shown below.

The second option is via the resource file itself. On the left panel, Select the Editor option and a window will open that will require you to:

1. first, select a project

2. select a resource file, and lastly

3. select a language from the drop-down menu that you would like to translate it to. (the steps are as shown in the image below).

While in this editing mode, pay close attention and double-check that the language you are translating for is correct. When you change the source file you are translating for, the language may also change and you may be required to reselect the language again.

Each resource will show a progress bar. The Blue portion of the progress bar indicates what percentage of the resource has been reviewed, while the Light Sea Green portion of the progress bar indicates what percentage of the resource has been awaiting review, and the Grey part indicates what has not been translated yet.

In the case that your language isn’t listed, you get the opportunity to request for it to be added using an option provided at the bottom of each resource page.

Select a resource to work on and Transifix will open the editor view.

Translate Project

Transifex opens a source file into translatable “text”, usually in a sentence or word form. Each text is translated individually as seen in the image above.

1. Shows a list of all strings both translated and untranslated.

2. Shows the number of untranslated strings only.

3. Shows a list of the translated strings that are yet to be reviewed/approved.

4. This shows the strings tab, which can be selected by translators under this particular project.

5. This is the editor pane, that shows the selected string to be translated.

6. This is the editor pane, where you may write your proposed translation for the selected string.

7. This button allows you to save the proposed translation.

8. A new feature in the editor that allows you to use AI to enhance the translations of the strings.

9. If a different contributor has proposed a translation to a string, Transifex will display those proposals here. You will not be able to save an identical translation rather it will be highlighted as Used - instead, if a translation is accurate and hasn’t been used yet it will allow you to copy and use it.

10. This overview “pane” button will hide the right side of the page and right.

The editor pane has a lot of functionality in it but what has been highlighted here is just an overview of the main parts that will make translation easier for you.

Once you are done making a contribution and have clicked the save button, the translation will be stored on Transifex. Other contributors will then be able to use your translation which will be stored under the suggestion tab and reviewers will be able to approve it if it’s correctly translated.

Feel free to translate as many strings as you wish. There are no extra steps needed after you complete translating a source file or suggesting a new translation. Simply click the Save button to store your translation.

Tips for Better Translation

• Always check the context of the String to ensure accurate translation.

• Pay attention to regional differences and cultural differences.

• Make use of the translation memory to see suggestions based on previous translations.

• Refer to the glossary for standardized terms and phrases to ensure consistency across translations.

Note After translating a string and saving it, it is automatically submitted for review and also open to be used by other translators.

Reviewing and Approving Translations

Reviewing ensures there’s accuracy consistency and quality of the translated strings. The reviewing process is manually done and hence requires a set of eyes to catch incontinence and errors, suggest improvements, and approve the correct translations.

There isn’t that much difference between the translator's page and the reviewer's page. The only visible difference is the accessibility of the review functionality.

As a reviewer, your focus should be drawn to the Unreviewed tab and the Reviewe button if everything is correctly translated. In case there’s a wrong translation you can edit the available suggestion save the changes and review them at the same time.

As a reviewer, you can still get all the translations approved at a go using the Bulk review feature. Select all strings by clicking at the top checkbox (highlighted with the blue square on the image below), then Mark selected translations as Reviewed, and click Apply.

Tips for Better Reviewing

• Be sure you are on the Unreviewed tab.

• Read both the original string and the translated string carefully.

• Compare the translation with the context and any provided comments.

• Pay attention to details and ensure the translation accurately reflects the original meaning.

• If improvements are needed, leave constructive comments and suggestions for the translator.

Guidance for Implementers

Overview of the Implementation Process

Implementing OpenMRS in a non-English language environment involves steps to ensure that the software is fully localized and functional for end-users. This section provides an overview of the key stages in the implementation process, highlighting essential tasks and best practices for achieving successful localization.

For the implementors, the localization of OpenMRS is not just about translating words, it’s more about ensuring the entire system meets the needs of the local users. This includes translating the user interface, forms, and metadata, and ensuring the medical terminology is accurate and culturally appropriate.

To work on the localizations locally, implementers may also choose to configure OpenMRS distribution to accommodate additional languages and manage the translation files effectively. This process involves the initial setup of language support and the continuous integration and maintenance of translations as the system evolves. The next section will guide you through the key steps in configuring your distribution, from adding new language locale codes to generating and managing translation files.

(Step 2) Configure your distribution

Distribution Configuration

This section provides step-by-step guidance on configuring your OpenMRS distribution to support additional languages. It covers how to add a new language locale code and create additional translation files locally.

To begin with, you must understand the different language locales available, and this resource https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes might come in handy.

Locale codes are identifiers used to support different languages and regional settings in OpenMRS. Each locale code follows the format <language>_<country>, such as en_US for English (United States) or fr_FR for French (France).

To add a new language, you will need to first navigate to the configuration files of your OpenMRS distribution usually located at https://github.com/openmrs/openmrs-distro-referenceapplication/blob/758a11fc510df7dd09e23b565ebc8e366cf9e673/distro/configuration/globalproperties/i18n.xml#L5. Add the new locale code to the list of supported locales.

<config>
    <globalProperties>
        <globalProperty>
            <property>locale.allowed.list</property>
            <value>en, es, fr, he, km</value>
        </globalProperty>
    </globalProperties>
</config>

If you are working locally, save the configuration file and restart your OpenMRS instance to apply the changes. Create a PR for your changes afterward.

Creating Additional Translation Files

This is helpful when creating translation files that will reflect the user interface. There are a couple of steps that should be followed for this which include:

• First, visit the mono repo, this repo contains the core packages for the OpenMRS Frontend.

• Next, you will be required to install the required dependencies, usually using yarn

• Now proceed to add a new language locale code as shown in the distribution configuration step.

• Create additional translation files using yarn run extract-translations. This command is used to generate translation files by extracting translatable strings from your codebase. This is essential when you add new features or update existing ones that require translation.

Code String Translation with Transifex

Please see the same guidance as shared for volunteers above.

If you have a contractor working on translations for you, you might even want to send them that section so that they work in Transifex directly for you. Some translation firms will be accustomed to tools like Transifex; others prefer using docs or spreadsheets.

Right to Left Languages

Yes, OpenMRS v3 supports Right to Left (RTL) Language display! When you configure your languages as described in Step 2 above, the system detects these languages and configures them to display RTL automatically.

Calendars and Date-Pickers

Yes, OpenMRS v3 supports non-Gregorian calendars! When you configure your languages as described in Step 2 above, the system detects these languages and automatically adjusts the calendar component to display the matching calendar for that language, such as in the Arabic and Amharic examples below. Specifically, this component supports 13 calendar systems out of the box, including Gregorian, Buddhist, and Ethiopic calendars.

(Step 3) Translate Your Metadata

Metadata Part 1: Concept Dictionary

Concept Dictionaries

A concept dictionary is a fundamental component of OpenMRS that defines all the medical concepts used in the system, such as diagnoses, procedures, drugs, and lab tests. These concepts are central to the functioning of OpenMRS, as they form the basis for all clinical data entry.

Similar to a dictionary defining the function, meaning, and relationships of the words, the concept dictionary defines the name, code, and appropriate attributes for any observations or data collected (including medical tests, drugs, results, symptoms, and conditions). It is the basic element of flexibility in OpenMRS. To even further simplify the concept dictionary, one could compare it to an infinitely large Excel spreadsheet, where patients are represented as rows and concepts are represented by columns.

Concept

Concepts are the individual data points collected from a population of patients. Concepts include both questions and answers. 

OCL not only gives you the option to manage concepts but also gives you access to a wide range of dictionaries from other organizations making it easier to work. In a scenario where you will need to create your concept contemplate these three steps:

• Make sure the concept doesn’t already exist in the dictionary. When searching the dictionary, use partial names (e.g. "Kale" or "Kalet" instead of "Kaletra"). Looking for partial names will help catch misspelled entries. Think about what your organization most generally refers to this concept as – consider all possible synonyms! You may be surprised what concepts already exist.

• Make sure that you can describe/understand the concept that you're getting ready to enter! Say for example, that you're asked to create a new term for the retroviral drug eliminatehivudine. Knowing that it's a retroviral drug is insufficient, as you're going to need to detail eliminatehivudine's differences from all other antiretrovirals within the term's description. Don’t be too sure of yourself - double-check with the person requesting the new concept that you have the correct, specific definition.

• Make sure that you include and standardized representation of the concept, e.g. LOINC or ICD10. If you have no idea what this is – go to the internet or a coworker and find out!

For example, blood type data is collected for a patient.  The question is "What is the blood type for the patient?", with a set of discrete answers of "A, B, AB, or O".  To implement this in OpenMRS with concepts, the question is a concept ("blood type") and each response ("A", "B", "AB" and "O") is also a concept.  For this one question, a total of 5 concepts are required.

In the context of localization, the concept dictionary needs to be translated and customized to reflect the medical terminology used in the target language. Implementers use OCL to manage these dictionaries, ensuring that the translations are accurate and contextually relevant.

The bottom line is, that if you need a medical word within your electronic records system, it needs to be defined within the concept dictionary. 

More on Context Dictionary Basics on this wiki page here.

Options for Managing and Translating Concept Dictionaries

Implementers have several options for managing and translating concept dictionaries based on their specific needs, the scale of their implementation, and their understanding of the system. Below are three main methods to manage and translate concept dictionaries:

1. Manage your concepts directly in your EMR distribution using the Admin User Interface

   • This method allows implementers to manage and translate concepts directly within their OpenMRS distribution via the Admin User Interface (UI). It is an ideal approach for smaller implementations or for implementers who prefer a more hands-on, real-time method of managing concepts without exporting or importing files.

Steps to follow include:

• In your Admin panel, locate and click on Manage Locale and Themes - this option allows you to set your default locale.

• To add a new concept, access the concept form.

• Here you will have the option to:

  • see all the available locales

  • add a new concept or edit an existing one

  • search for existing ones.

  • Each concept includes fields such as concept names, descriptions, data types (e.g., coded, numeric, text), and attributes.

• For each concept, add translations by selecting the desired language and entering the corresponding translation and other relevant information.

• After entering all required details and translations, update the concept.

In case the language you want to implement is missing, then you will need to add it via the i18n-core_demo.xml file available here on GitHub before it can reflect under the available locales sections.

2. Manage your concepts with a CSV file like this one: https://github.com/mekomsolutions/openmrs-module-initializer/blob/main/readme/concepts.md

   • This method is useful for implementors who need to manage a larger number of concepts or perform bulk translations. It allows implementers to work with concepts offline, manage translations in a structured format, and import/export them as needed.

3. Use Open Concept Lab (OCL)

OCL does not only give the option to manage the concepts but also the ability to manage translations.

Steps to follow:

• You will need to have an OCL account, if you don’t check out this section on how to get started with OCL.

• Once logged in, you can set up a custom dictionary for your specific OpenMRS distribution or choose from publicly available concept dictionaries.

• For each concept, you can add translations by selecting the appropriate language and entering the translation for both the name and the description.

• Once you’ve managed or updated your concepts in OCL, you can synchronize them with your OpenMRS distribution.

• Use the OCL module to import the concepts directly into your OpenMRS system, ensuring that all translations and updates are reflected in the EMR.

Metadata Part 2: Other Non-Concept Metadata

In addition to managing and translating concept dictionaries, implementers will often need to manage and translate other forms of metadata within OpenMRS. Non-concept metadata refers to all the other types of data that define how the system behaves, displays information, and captures clinical workflows. These include forms, encounters, observations, locations, user interface elements, and various system configurations.

For Address Label translation, see this guide here.

Metadata Part 3: Translating Forms

Forms

Forms are a very important part of the OpenMRS user interface, they allow healthcare providers to enter and retrieve patient data. Implementers must translate these forms to ensure that they are usable by non-English-speaking users.

How to Translate Forms in OpenMRS v3

To set up multiple translated versions of a form, you will need to set up some JSON files, which will live in your /config directory under /ampathformstranslations. For example:

ampathformstranslations/
  ├── form1_translations_fr.json
  └── form2_translations_en.json

You will need a translation file for ALL languages you want to be able to switch between. For example, if you want to be able to switch between both French and English, you would need a file for BOTH those languages, as shown above. If you only had a fr.json file, then even when you set your language preference to English, you would still be seeing that form only in French.

Here is a JSON File example:

{
    "uuid": "c5bf3efe-3798-4052-8dcb-09aacfcbabdc",
    "form": "Form 1",
    "form_name_translation": "Formulaire 1",
    "description": "French Translations for Form 1",
    "language": "fr",
    "translations": {
      "Encounter": "Rencontre",
      "Other": "Autre",
      "Child": "Enfant"
    }
}

Here are two much more detailed examples form translation JSON files you can look at:

• English string file - Adult HIV Visit Form

• French string file - Adult HIV Visit form

NOTE:

• The form attribute must be provided with an existing form name for the translations to load successfully. The translations form resources get names following the following pattern <form_name>_translations_<language>.

• The form_name_translation attribute is treated as the localized name for the form in the translation locale.

Best practices for ensuring consistency and accuracy in form translations

1. Context: When you are translating the form, ensure you keep the form context in mind.

   1. For example, one implementer discovered she almost translated some Maternal Health question text wrong: It looked like “Time of Delivery”, which made her think it was talking about the time of delivery of a Baby; however, upon double-checking the original form, it was actually Time of Delivery of the Placenta.

2. Keep your Translations Up to Date: If you change some text in a Form, ensure you update the translation file as well!

Quality Assurance and Semantic Consistency in Translation

High-quality translations must accurately convey the intended meaning of the original content while preserving context and terminology.

Importance of Quality Assurance in Translations

• Translations that are inaccurate or inconsistent can confuse users and impact the overall usability of the system. For example, the word “Check-in” is mistranslated to the French "Enregistrer," which means "to register," it could confuse users who may assume it's referring to recording data, rather than a patient check-in process.

• Misunderstandings or mistranslations of medical terminology can lead to critical errors, especially when dealing with patient data and health information.

• High-quality translations help build trust among users and encourage wider adoption. A clear translation of health-related information in local languages helps users feel more comfortable using OpenMRS.

• Consistent translations reduce the need for rework and enable future updates to be applied smoothly across languages.

To achieve greater quality in the translations some things can be implemented to make the entire process easy, such as:

• Ensure consistent use of terms across the translation. Tools like glossary files or translation memory systems can help maintain this. For example, If “Patient Record” is translated as “Dossier du Patient” in one place, ensure the same term is used consistently throughout the system. Mixing in alternatives like “Fiche du Patient” could confuse users.

• Confirm that the translated text accurately reflects the meaning of the original string, especially in medical contexts.

• The translated content should be easy to read, free of jargon, and culturally appropriate for the target audience.

• Avoid word-for-word translations that may miss the context or alter the intended meaning. For example, Translating the word “Queue” as “File d’attente” in French (a literal translation meaning “waiting line”) may be appropriate in some contexts, but it may not fit in a hospital system context where "Queue" refers to patient triage. The term “Ordre d’attente” (waiting order) could be a better alternative.

General Translator Guidelines

• Check Context

  • If you are not already familiar with the OpenMRS EMR (Electronic Medical Record) especially the latest version (“O3” or v3) and would like to have a hands-on demo, a demonstration of this system is available at https://dev3.openmrs.org/openmrs/spa/login (username: admin, password: Admin123). Please use this demo site to help you (1) check the context of your translations and (2) double-check your translation work.

• Keep Sentences Short

  • Where possible, try to keep sentences short, without loosing the intended meaning. For example:

    • Too Long: Les files d'attente ont été vidées avec succès

    • Better: “Files d'attente vidées avec succès”

• Gendered Language:

  • Many languages have “grammatical gender”, where correct grammar requires masculine/feminine conjugations (examples here). Here are our guidelines we ask Translators to follow:

    1. Re-phrase in a grammatically gender-neutral way: E.g. instead of Êtes-vous sûr de vouloir supprimer cette visite? we could use Voulez-vous vraiment annuler cet visite? We can have a list of alternatives for common gendered nouns as well (e.g. “Consider “l’individu” instead of patient or client which would client(e) or patient(e)”)

    2. Use () if neutral phrasing is not possible: E.g. “Êtes-vous sûr(e) de vouloir indiquer ce(tte) patient(e) comme décédé(e)”

    3. Use / as a last resort if () is not possible: E.g. “sibling” in French = “Soeur/Frère”

  • If you have any feedback or suggestions, please share your thoughts in this Forum thread where we decided upon these guidelines!

• Abbreviations:

  • Some acronyms/abbreviations don’t make sense in another language (e.g. “AIDS” in English is “SIDA” in French, or “EPTB” is “TBEP” in French).

  • Handy Links for French Translation: These Medical abbreviation guides can help you identify what the abbreviation may stand for in that language:

    • French Medical Abbreviations: MSF Guide

    • English Medical Abbreviations: MSF Guide

Translator Guidelines specific to French

• Guide to common French words:

  • Visits: consultation. Not “visit” because in French that is informal, like you are going to see a friend.

  • Encounter:

  • Star (as in “Starred List” like a bookmark or a favorite): Liste de favoris

  • For “Location”, use “emplacement” instead of “site”, since “Site” can be used differently than “Location”

    • Visit = / = Encounter; instead use visite

    • Check-in = / = Register (“Enregistrer”: should this be used for Check-in or not?)

      • Then for Register, you’d use _____.

How to Use OCL, Especially for Concept Dictionary Translation

What is Open Concept Lab (OCL)?

OCL is a powerful open-source project that allows implementers to manage and share medical terminologies and other healthcare-related concepts. Specifically, the OCL TeamBrowser tool provides a central online repository where implementers can search, create, customize, and distribute Concept Dictionaries.

Why use OCL?

• Mass Concept Management: If you implement in many sites - e.g. more than 10, or even more than 100, or multiple regions or multiple countries or multiple languages - then you probably will have different combinations of codes needed. In the past, many implementers used an assortment of spreadsheets to manage these different combinations. OCL allows you to store all your different types of country-specific content in a single place where you can more easily mix and match what content you need.

  • A great example of this complexity is this public repository from Partners in Health (PIH). You can see how they have some shared config across their multiple countries, but they also need additional, different concepts for each of the different countries.

• Easy to Search for relevant terminology resources & search standards (e.g. you can search all of CIEL easily to find a standardized concept).

• Time-Savings: It is much faster to add concepts from standards (like CIEL) to your OCL collection than it is to manually re-create those standard concepts directly in your EMR distribution admin tools.

• Compare how other people are encoding something (e.g. you can compare what an ICD or CIEL concept looks like compared to what someone else has done in, say, Nigeria, Uganda, and more).

• Collaborate by loading your local codes to begin mapping and collaborating with the global community (e.g. you can compare your work to how other people have designed their concept collections). This promotes the reusability of existing terminology content.

• Map your data elements (concepts) to standards and align with common standards like ICD-10 and LOINC.

How do OpenMRS Implementations use OCL for Concept Management?

There are a few different ways to use OCL for concept management:

1. Custom: Create your custom concepts.

2. Use Standards: Find and re-use concepts from standardized kits like CIEL, LOINC, ICD, and more, so you do not have to re-create those yourself.

3. Use Peers' Work: Find concepts from other Implementing organizations (like PIH, MSF, NigeriaMRS, KenyaEMR, UgandaEMR, and others) and re-use those or model your custom concepts off of their work.

4. Your own created dictionary will usually consist of content from other organizations as well as content from your organization.

Introduction to Open Concept Lab (OCL)

To get started with OCL, you will need to be signed in if you already have an account or create one if you are joining as a first-time implementer.

• Sign Up/login - https://app.openconceptlab.org/

A successful sign-in will take you to your landing page, which for a new user will be a blank page with your details on the left side as shown below.

For a returning user, the homepage will look a bit different with sources you have worked on appearing on the homepage as well as pinned sources appearing on the top of the page.

Key Terms in OCL

• Owners - They own the terminology content. They include:

  • Organizations - There are groups of users that can collaboratively manage repositories and team permissions. For example: WHO, CIEL etc…

  • Users - Can create their own work or within an organization.

• Repositories - Where the terminology content is created. They include

  • Sources - These are versioned repositories of concepts and mappings. They are for content that you or your organization create.

  • Collections - These are logical groupings of concepts and mappings such as in a value set. They bring content together, from multiple places for a specific need. Concept and mapping must originate from a source and then they can be gathered into a collection. A collection is the only place you can gather content that is owned by other organizations.

In the world of Music, think of Sources like an Album that contains different songs (in this case concept and mappings in OCL) where if the album does not have a song you can record it yourself (in OCL create the concept yourself), and Collections like a Playlist where you gather up songs yours and other people's too, all songs originate from an album before being added to a playlist.

• Resources - This is held in the repositories. It can consist:

  • Concepts - Represent the names, definitions, and metadata for a single idea such as data or a definition indicator.

  • Mappings - Represents the relationship between two concepts.

Configuring Source and Collection in OCL

From the example above, the homepage contains a list of dictionaries created by you the user, and tabs including your organization's dictionaries, and different collections as well as an option for you to create your dictionary.

For you to get content from different organizations, from your home page select the User Collections tab and click on the + COLLECTION tab.

Content can be created under your user profile or any organization that you belong to. In the case that you are required to create content under your organization, you will need to create it first under the Organization membership tab, followed by adding an organization, this will make it easier for you to create a collection under an organization.

For status, if you don’t belong to any organization you can create the collection under your user profile. By default, this option is usually auto-selected. Next, you will be required to input a shortcode. A shortcode is a mnemonic used to identify the collection in the URL (usually an acronym e.g. Community-MCH).

Note: Once the shortcode is set, it can’t be changed later on.

Other field details necessary while creating a new collection include:

• Shortname - This is a shortname display of your collection such as a nickname or an abbreviation.

• Full Name - This is a fully specified descriptive name of your collection.

• Description: This is the About section, it should include details about the collection.

• Language - This option allows you to select the primary language of concepts of your collection as well as add other supported languages that might be used in the collection.

• Configuration - The configuration gives you different options on how you want your collection configured such as selecting:

  • the collection type, From the drop-down menu, you get to select what you are working on as shown below.

  • 

  • the validation schema, which dictates the format that your collection will follow. If specified OCL will validate your collection according to rules defined in the schema selected. By default, we have two listed, it advised you to select the OpenMRS Validation Schema as it will check if your concepts are formatted collect and won’t break OpeMRS when you import it. More information about these validation rules can be found here - https://talk.openmrs.org/t/defining-our-concept-validation-rules-for-ocl/33508/

  • 

• Advanced Settings - This section gives the option to further customize your collection to suit your needs and preferences.

With all the settings and configurations set, you can now create your collection with the help of CREATE COLLECTION at the bottom of the page.

Your newly created dictionary will automatically be listed under the User Collections tab. For more information about how to make and use collections in OCL, see our YouTube playlist.

Configuring the Source

When it comes to configuring a User Source the steps are the same as creating a collection with the same configuration, the only additional setting that should be incorporated is under the Advanced Settings where

• the ID Auto-Assignment under the first option Concept IDs needs to be set to Sequential

• the second section External IDs needs to be set to UUID for all the four options available.

Note:

• OpenMRS recommends that OCL sources use the following ID Auto-Assignment options.

• IDs (including Concept IDs and Mapping IDs) should be “Sequential”. With this option, OCL will automatically assign an ID when you create a concept or mapping, rather than requiring the user to specify one.

  • External IDs (both for concepts and mappings) should use the “UUID” option. This will tell OCL to automatically assign a unique UUID as the external ID when creating a concept or a mapping.

With these settings in place, you can proceed to creating your source, by clicking the CREATE SOURCE button at the bottom of the page.

Adding Concepts to Your Collection

You can find concepts using OCL’s global search feature, or even better, searching directly for a specific source. The CIEL source is the most preferred to work with. Use the “Add to Collection” button to start gathering up the concepts you need. By clicking the “Add to Collection” button, you get to choose which collection you want the source to be part of.

When you “Add to Collection”, you will get a prompt that asks if you would like to also include associated concepts and mappings. You can use the “OpenMRS-compatible Cascade” option if you want to pull in all the concepts from a Concept Set, a Lab Set, etc. This option will also include the Answers if you add a Question concept to your collection as well as any maps to standard codes like SNOMED CT or ICD.

Concept Best Practices

• When it comes to concept naming:

  • only use alphanumeric characters (letters and numbers) and simple punctuation sparingly – e.g., comma (","), parentheses ("(" and ")"), and forward-slash ("/").

  • descriptions may contain non-alphanumeric characters though sentence-case is recommended. This is either all lowercase or uppercase first letter.

  • Always work with your end users to ensure that your concept names make sense to them and match their workflows.

  • Avoid changing the names of concepts used to store clinical data.

• Every concept should have a description (at least within the system locale) that unambiguously describes the concept and, ideally, explains its intended use.

• Design for Re-use

  • Avoid making your symptoms & diagnoses concepts boolean; use datatype N/A for these and use them as answers (not questions).  This promotes the re-use of these concepts.