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!
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
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.
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.
Documentation and Guides
There are some already available guides, 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.
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 a language you want to work on and it 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:
first, select a project
select a resource file, and lastly
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.
Shows a list of all strings both translated and untranslated.
Shows the number of untranslated strings only.
Shows a list of the translated strings that are yet to be reviewed/approved.
This shows the strings tab that is free to be selected by translators under this particular project.
This is the editor pane, that shows the selected string to be translated.
This is the editor pane, where you may write your proposed translation for the selected string.
This button allows you to save the proposed translation.
A new feature in the editor that allows you to use AI to enhance the translations of the strings.
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.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
Unreviewedtab.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.
| Code Block | ||
|---|---|---|
| ||
<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 comes in handy 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
yarnNow proceed to add a new language locale code.
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.
(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.
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
There are several options:
Manage your concepts directly in your EMR distribution using the Admin User Interface
Manage your concepts with a CSV file like this one: https://github.com/mekomsolutions/openmrs-module-initializer/blob/main/readme/concepts.md
Use Open Concept Lab (OCL)
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!
Do you have all of the information ready? Then it's time to walk through a primary concept definition and the basic attributes this includes.
Primary Name
The name should be completely specific. It is "Hepatitis B immunization", not "Immunization, Hepatitis B".
Use sentence case (Malignant cancer) or title case (Malignant Cancer)
Use only alphanumeric characters! (If this was a concept, there would be no exclamation point.)
NO ACRONYMS – Abbreviations and acronyms are only used as synonyms!!
When necessary, always refer to the generic form (e.g. Ibuprofen, not Advil ©)
When referring to an organism or virus, the full taxonomic name is used (e.g. Human Immunodeficiency Virus, not HIV)
Adhere to complete granularity! "Right upper quadrant abdominal pain" refers to too many observations. This can be tricky in practice – if you’re unsure, refer to a geek or someone who can identify mini-clauses within your proposed primary name.
Short Name
Use alphanumeric characters, and avoid long phrases, and acronyms that may have several meanings
Synonym
Use any other phrases or acronyms that people within your organization may search for when attempting to use this concept. If you’re at a loss, survey possible end users.
Description
Without question, at the end of reading this statement, a layperson should have a decent idea of the concept’s meaning. This is always REQUIRED – no exceptions.
Data Class
Is the concept a question that requires responses? If so – label it as a question!
Is it a list of questions that are related? If so – label it as a CONVSET!
Is it a list of lab procedures that are related? If so - label it as LABSET!
Is it a list of medications that are related (e.g. Antiretrovirals)? If so – label it as a MEDSET!
If you’ve gotten through the above questions, be smart, and choose the best fitting of the remaining classes.
Is it a set?
If you answered yes to either questions 2,3, or 4 above, check this box! Otherwise, you won’t be getting much functionality out of the concept.
Datatype
Is your concept a question that requires responses?
If yes, select the type that best represents the form that you wish to view your data.
If yes, and there are only a few possible answers, select CODED, and choose those possible answers.
If yes, and the class is numeric, make sure you enter any critical values. Also, select PRECISE if you desire decimal answers.
If no, select N/A.
More on concept dictionaries and how to create them is discussed in detail below.
Metadata Part 2: Other Non-Concept Metadata
TODO:
Elaborate more on
(Step 4) Translating Forms and Content
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:
| Code Block |
|---|
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:
| Code Block |
|---|
{
"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 example form translation JSON files you can look at:
NOTE:
The
formattribute 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_translationattribute is treated as the localized name for the form in the translation locale.
Best practices for ensuring consistency and accuracy in form translations
Context: When you are translating the form, ensure you keep the form context in mind.
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.
Keep your Translations Up to Date: If you change some text in a Form, ensure you update the translation file as well!
Right to Left Languages
(The systems detects and configures them automatically)
TODO:
How to configure a language to tell the OpenMRS system to render it Right to Left
Yes, OpenMRS v3 supports Right to Left (RTL) Language display!
Quality Assurance and Semantic Consistency in Translation
At OpenMRS we believe in proactive quality assurance over-reactive quality assurance, but acknowledge that in software delivery both are required at different times. As a community-developed codebase, Quality is a shared responsibility between the developers, the quality assurance team, the release manager, the product managers and business analysts, and our partners and their users.
Our Principles
Promote a Culture of Shared Quality Responsibility
Embed quality practices early in the development process.
Incorporate quality checkpoints throughout the development and release lifecycle.
Include the voice of our users, ensuring their feedback informs product improvements.
Advocate for strong software design, rigorous testing practices, and proactive bug prevention.
Enhance and Optimize Test Coverage
Ensure all tests are executed at the most impactful stages.
Provide clear and actionable test coverage reports to teams.
Continuously refine our testing processes to eliminate redundancies, address gaps, and improve stability.
Increase Team Efficiency and Engagement
Develop automated solutions to streamline core workflows and boost productivity, but acknowledge that not everything can or should be automated to preserve the maintainability of our QA processes & solutions.
Maintain reliable tools and tests to support continuous integration and delivery.
Ensure our CI pipelines are efficient and stable, and provide comprehensive coverage.
Data-Driven Decision Making
Provide insights into defects, test stability, efficiency, and team performance through data.
Make actionable data transparently available to the team and community.
Use metrics to inform decision-making and drive continuous improvement.
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:
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)”)
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)”
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:
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 _____.
Deployment and Maintenance
Integrating Translations into OpenMRS
Configuring OpenMRS to use the new language settings
Best practices for maintaining translations over time.
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:
Custom: Create your custom concepts.
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.
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.
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 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-Assignmentunder the first option Concept IDs needs to be set toSequentialthe second section External IDs needs to be set to
UUIDfor 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 that have been 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 how it is intended to be used.
Design for Re-use
Avoid making your symptoms & diagnoses concepts boolean; rather, use datatype N/A for these and use them as answers (not questions). This promotes the re-use of these concepts.
TODO:
How implementers can use OCL to manage translations and terminology.
Other Useful Links: