/
📚 Concepts and Metadata Guide 📚

📚 Concepts and Metadata Guide 📚

Owned by Veronica Muthee
Last updated: about 2 hours ago
39 min read

In this guide, we will walk you through how to use OCL for OpenMRS.

There are 2 main ways to manage your concepts: using Admin Legacy UI or using OpenConceptLab (OCL), an open-source terminology management system. We will delve into these 2 approaches but the use of the OCL tool is highly recommended.

image-20250219-052936.png

About this Guide

Introduction:

The Concept and Metadata Guide provides a structured approach to managing concepts within an OpenMRS instance. The guide provides a comprehensive overview of managing healthcare terminologies within OpenMRS, covering key aspects such as terminology application, concept creation, and metadata organization. It explores two primary approaches:

  • Using the Admin Legacy UI for concept management tasks like setting up concept classes, defining data types, adding mappings, and

  • Leveraging the Open Concept Lab (OCL) tool for advanced metadata management, including creating collections, versioning, and mapping concepts across repositories.

The guide also outlines the process of importing concepts into an OpenMRS instance, offering step-by-step instructions for versioning, exporting, and integrating concepts. Additionally, it provides troubleshooting tips, best practices, and resources to facilitate efficient metadata management.

🟠 Terminology, Concepts, and Metadata

1. Terminology 

Terminology refers to the standardized set of medical terms and codes used to represent clinical information in a consistent and interoperable manner.

  • It provides a common language that healthcare systems and providers can use to ensure clear communication, accurate data capture, and seamless data exchange.

  • There are three main classes of terminology that are used differently within health information systems: Administrative, Reference, and Interface. It is important to know when to use each one.

    • Administrative terminologies are generally used to classify ideas and manage administrative tasks like generating bills, some form of reports, etc. 

      • Examples: ICD-10 or ICD-11 from the WHO, primarily used for diagnoses. 

    • Reference terminologies are usually based on ontologies and attempt to model the meaning of an idea. This allows for a sophisticated grouping of ideas based on relationships with other ideas. 

      • Examples:  SNOMED CT (which covers most domains), LOINC (primarily used for laboratories and clinical findings), and RxNORM (used for drugs).

    • Interface terminologies are primarily clinically friendly terms and phrases that users require for the documentation and treatment of patients and other healthcare activities. They make it easier for users to find target information. 

      • Examples: CIEL and IMO’s Core terminology which provide user-friendly terms mapped to many reference and administrative code systems

→ Terminology Application

  • Terminology standardizes the language used within clinical workflows, ensuring that all users, whether clinicians, administrators, or data entry staff, have a shared understanding of medical terms. It prevents ambiguity and errors by ensuring that terms like "hypertension" or "diabetes" mean the same across all systems.

  • Clinical decision support tools rely on accurate and standardized terminology to function effectively. Terminology defines groups of ideas that trigger alerts or reminders, such as drug interactions or critical lab results.

  • Terminology is essential for extracting meaningful insights from clinical data (Reporting/Analytics). Standardized terms enable the system to group and analyze data effectively, such as the number of patients diagnosed with "Type 2 diabetes” (or any more granular forms of Type 2 diabetes).

  • A robust terminology foundation allows seamless exchange of not just codes, but also meaning between systems, such as electronic medical records (EMRs) and laboratory information management systems (LIMS). This is called semantic interoperability.

2. Concepts

Concepts are the building blocks of clinical data within healthcare systems, representing specific entities, conditions, or observations. Each concept captures the meaning or definition behind clinical data. The actual definition of a concept may require a paragraph of text, so this means that the definitions can’t be used in EMRs. 

Terms, on the other hand, are the labels or names assigned to concepts to ensure they are clearly understood and easily referenced. Terms have different roles, so there usually is one FULLY SPECIFIED term that unambiguously identifies the concept in a particular locale. There can be other ones that are in preferred use, or synonyms which help find the concept, but the FULLY SPECIFIED name should always be confirmed as the correct concept.

It's important to note that while the concept is universal, the terms can be localized (i.e., translated into different languages).

  • The purpose of concepts is to provide structured and precise definitions for clinical items (e.g., "Body Temperature", "HIV Positive", "Blood Pressure").

    • A concept represents individual pieces of data collected from a patient → questions/answers, diagnoses, procedures, medications, laboratory tests, etc that need to be captured.

  • A concept may include a name, description, class, datatype (numeric, text, coded), and mappings to standardized terminologies (e.g., SNOMED or ICD codes).

  • Concepts often derive their definition, context, and structure from established terminologies or classification systems. For instance, a concept like "Hypertension" can be associated with a specific meaning and coding system such as the ICD-10 code This mapping to a standard code ensures a universal understanding of the concept, aligns with clinical standards, and supports interoperability, reporting, and accurate data exchange across healthcare systems.  

3. Metadata

Metadata refers to the descriptive information about concepts or terminology that provides context, structure, and rules for their use.

  • Metadata aims to manage how concepts and terminologies are implemented in a system, ensuring data integrity, interoperability, and usability.

  • Examples:

    • Data type (e.g., numeric, coded, text).

    • Validation rules (e.g., a temperature must be between 35–42°C).

    • Mappings to external terminologies.

    • Localization information (translations, regional adaptations).

Let’s use the CIEL dictionary (the Columbia International eHealth Laboratory dictionary) to illustrate the relationship between terminology, concept, and metadata using "Body Temperature as an example."

Terminology refers to the standard codes and vocabulary used to describe "Body Temperature" in a consistent, interoperable way.

  • CIEL Code for Body Temperature: CIEL 5088

  • Mappings: CIEL maps this concept to external terminologies such as:

    • LOINC: 8310-5 Body temperature

    • SNOMED CT: 386725007 Body temperature (observable entity)

  • Purpose: These mappings ensure that "Body Temperature" is recognized consistently in external systems, supporting interoperability and standardization.

Concept Mapping Example

  • Concept ID in OpenMRS: CIEL 5088

    • It’s good to note that, in OpenMRS, the concept ID can vary across different installations. However, in the CIEL dictionary, the concept is referenced as "CIEL:5088," where 5088 is the unique concept ID within the Open Concept Lab (OCL) or the authoritative "golden" server where the concept dictionary is managed. Once the CIEL dictionary is installed in an OpenMRS system, the local concept ID assigned may differ from 5088.

  • Name:

    • Preferred: "Body Temperature (°C)"

    • Synonyms: "Temperature," "Temp" (may include translations, such as French: "Température (°C)".

  • Data Type: Numeric (to capture measurable values).

  • Class: Finding (indicating it is a result or observation from a test).

  • Units: Celsius (°C) OR Fahrenheit (°F), but not both. If the concept name has °C, then units must match

  • Description (this is a definition in words):

    • Patient temperature in degrees centigrade (°C).

  • UUID: Unique identifier for each concept which is maintained for every implementation. 

  • Mappings to Terminologies:

    • These are relationships between the concept and other codes or terms e.g. body temperature is mapped to LOINC 8310-5 (which ensures global compatibility).

    • LOINC is an example of a reference source or the origin or authority from which the terminology or concept is derived. Others include SNOMED CT, etc.

→ Common Mappings

  1. SAME-AS∞: Indicates a mapping relationship in which the concept is considered identical or synonymous to the concept specified. This is sometimes called “Self-mapping” or “Gold Mapping” – e.g. when CIEL:5088 is SAME-AS CIEL:5088. The reason these exist is to persist a source’s official concept ID (the concept ID used in OCL) and also as a mapping for cases where local ID assignment is arbitrary (e.g., importing concepts into a database with auto-assign concept IDs), where the concept ID gets changed arbitrarily during import. In cases where OCL’s concept ID is reliably preserved during imports to implementing systems, these self-mappings are unnecessary.

  2. same-as: A standard mapping relationship that identifies the concept as exactly equivalent to another concept in a different dictionary or terminology set. For example, the “Malaria” concept is the same as “unspecified Malaria” in ICD-10-WHO.

  3. NARROWER-THANThis mapping means that the concept is more specific than the referenced concept. For instance, “Malaria caused by P. falciparum” is narrower than the broader term “Malaria”.

  4. BROADER-THAN: This mapping indicates that the concept is more general than the referenced concept. For example, “Malaria” is broader than the more specific concept “Malaria caused by P. falciparum.”

💡 Note:

It's important to note that SAME-AS mappings offer the most utility compared to Narrower-than and Broader-than mappings. Due to their broader established use, SAME-AS mappings are typically the preferred choice when creating mappings.

  1. q-and-a: Represent a Question-and-Answer relationship where a concept (e.g., “Malaria”) is used as an answer to a predefined question (e.g., “What was the medical cause of death?”, “Primary reason for referral” etc). 

  2. concept-set: Refers to a specific collection of related concepts grouped for organizational purposes. Concept sets are often used to group similar medical terms or conditions for easier management and reference. Some examples include:

  • Vital Signs Concept Set → may include Temperature, Pulse, Respiratory Rate, Blood Pressure, and Oxygen Saturation. 

  • Cause of death Concept Set → may include Malaria, HIV/AIDS, Heart Failure, and Road Traffic Accidents.

  • Common examples of Concept sets include ConvSet, LabSet, and MedSet.

📌 Convenience Set (ConvSet):

  • A convenient set is designed to group commonly used concepts that are frequently referenced together for convenience.

    • Diagnoses easily accessible for clinicians during patient visits → may include concepts in the set like Malaria, Hypertension, Diabetes mellitus, Pneumonia, and Gastroenteritis.   

  • A convenient set is used to show or report on a subset of concepts.  

    • Examples of these sets → include oncology, pediatric, or NCD diagnosis.

  • They can also be used in forms to reference a group of answers or to filter a database query.

  • Used to group related concepts.

    • For example, intravenous fluids → include the name of the fluid, volume, and location of the IV.  In OpenMRS, these are stored in the database as an obsgroup with multiple obs.

📌 MedSet:

  • A concept set for a collection of drugs that are related → for example, Antiretroviral drugs or TB medication.

📌 LabSet:

  • A concept set for a collection of laboratory tests that are related → for example, Hematogram or Liver Function Panel lab tests.

OpenMRS Concept Tables Data Model

i) Data Type Metadata:

  • Metadata establishes whether the concept value is a number (e.g., 37°C), a range (e.g., 36–38°C), or a coded value (e.g., "Low," "Normal," "High").

  • Numeric Ranges:

    • Normal:  between 35.0°C and 37.7°C

    • Critical:  maximum: 39.0°C

    • Absolute: between 25.0°C and 47.0°C

  • Units of measurement: Degrees Celsius (OpenMRS can support conversion to Fahrenheit units)

ii) Validation Rules:

  • Value Constraints: Metadata enforces rules for valid entries. For example:

  • Minimum and maximum values (e.g., 30°C to 45°C).

  • Disallowing text or invalid ranges (e.g., "400").

iii) Date and Time Context: Metadata can link the temperature reading to a specific encounter or time period for trend analysis.

iv) Error Handling: Metadata defines error messages or flags for invalid inputs, ensuring data integrity (e.g., "Entered value is out of the acceptable range").

v) Display Information:

  • Grouped under the "Vitals" section in forms.

    • Can be set as required in specific forms (e.g., "Vitals Signs Form").

vi) Data Capture Metadata:

  • Input method: Numeric entry.

vii) Behavior in Analytics:

  • Metadata provides the clinical context of "Body Temperature," such as its role in diagnosing conditions (e.g., fever detection or hypothermia monitoring).

    • Is Parent Of/Child Of: Ensures hierarchical relationships are maintained for clinical clarity and analytical inclusiveness.

    • Groupings and Hierarchies:

      • Parent-Child Relationships: Metadata determines if "Body Temperature" is part of a broader group like "Vital Signs" and includes descendant concepts like "Axillary Temperature" or "Oral Temperature."

      • Ancestor/Descendant Inclusion: When querying data, metadata ensures that selecting "Body Temperature" automatically includes relevant subcategories like "Rectal Temperature" or excludes unrelated data.

    • Query Behavior: When running a query for "Body Temperature," the metadata determines:

→ Which related concepts (like "Axillary Temperature" or "Rectal Temperature") should be included based on relationships?

→ Whether synonyms (e.g., "Temperature Measurement") are considered equivalent.

viii) Aggregation Rules: Metadata controls how data is grouped for analysis:

  • By unit (e.g., Celsius vs. Fahrenheit).

    • By time (e.g., daily averages).

    • By location (e.g., body site of measurement).

ix) Trend Analysis: Metadata ensures "Body Temperature" can be tracked over time and across patient populations for trends (e.g., identifying fever outbreaks).

x) Filtering and Sorting: Allows users to filter data by attributes (e.g., only oral temperature readings) or sort by values.

xi) Integration with Other Data: Metadata links "Body Temperature" to other vitals (e.g., blood pressure, pulse) to provide a comprehensive clinical picture.

xii) Decision Support: Metadata enables alerts, such as flagging a temperature of 39°C as indicative of a possible fever, prompting further investigation.

🔵 Metadata Management in OpenMRS

In OpenMRS, metadata management is essential for structuring and standardizing medical and administrative data to ensure seamless system functionality and interoperability. Here are several types of metadata managed within OpenMRS:

1. Concepts

These are foundational elements in OpenMRS, representing clinical ideas like diagnoses, symptoms, drugs, laboratory tests, and procedures. Concepts must be carefully curated and managed, including their names, data classes, datatypes, and mappings to external vocabularies like ICD-10, ICD-11, SNOMED, RxNORM, or LOINC. Concepts can be shared between different OpenMRS installations through the OpenConceptLab (OCL).

2. Locations

Metadata for locations includes both physical and administrative locations within a healthcare system, which is crucial for patient tracking, reporting, and resource allocation. This involves managing names, descriptions, and hierarchies of locations.

3. Encounter Types

These categorize patient visits and or interactions, such as outpatient visits, inpatient admissions, emergency room visits, vitals, labs, immunizations, etc. Metadata management for encounter types includes defining the type, its description, and any associated forms or workflows.

4. Order Types

Metadata related to orders includes the types of orders that can be placed within the system, like lab orders, drug orders, radiology orders, or procedure orders. Managing these involves setting up order types with their attributes, handling units, and linking to concepts or drugs.

5. Patient Identifier Types

This includes metadata defining how patient identifiers are structured and validated within the system, such as medical record numbers, national IDs, or other unique identifiers. This involves specifying the format, validators like Luhn CheckDigit, and rules for uniqueness.

6. Programs

Metadata for programs helps in organizing patient care under specific health programs, like HIV care, Pregnancy, or diabetes management. This includes program names, enrollment dates, workflow/states, and outcomes.

7. Roles and Privileges

Administrative metadata that manages user access and permissions within OpenMRS, defining what users can do based on their roles. This is crucial for security and governance. Depending on roles, users are restricted from access to information that does not match their responsibilities. Roles also limit the actions and information displayed.

8. Forms

These are used for data entry and need management of form structure, associated concepts, and dependencies. Forms are used in various clinical areas e.g. vital signs, consultation, lab test/results, antenatal visit, HIV enrollment, etc)

9. Relationship Types

Metadata about how patients or users are related to each other or to the system, which is vital for family or caregiver information management. Relationships can include child-mother, patient-clinician, spouse, and siblings.

10. Drugs

Metadata for managing drugs, including brand drug names, strengths, and formulations. Also ensuring they link correctly with the related drug concept in the concept table. 

⓵ The drug table exists to manage medication prescriptions more precisely by storing drug formulations including drug name, strength and form (e.g., tablet, syrup or capsule). This structure allows for accurate prescribing and dispensing of medications.  

⓶ Brand and generic drug names help differentiate between multiple products containing the same active ingredient.

⓷ Strength defines the concentration of the active ingredient (e.g., 500 mg, 10 mg/mL).

⓸ Form specifies the physical presentation of the drug (e.g., tablet, capsule, syrup, injection).

11. Address Hierarchy 

Metadata that matches the country’s home addresses for patients. A description of the format (street, village, state, country) along with every possible variation for the country.

🟣 Best Practices Examples

  • Organizations can either create a set of concepts manually (using Admin Legacy UI) or use tools like OpenConceptLab (OCL) which is an open-source terminology management system. The use of the OCL tool is highly recommended because:

    • OCL provides real-time electronic access to terminological resources and straightforward integration with independent software platforms.

    • OCL Online helps you to collaboratively manage, publish, and use terminology in the cloud alongside the global community.

    • OCL advantages include:

      • It allows you to quickly get startup concepts from CIEL or another trusted source.

      • Facilitates the establishment of a “baseline” source using a trusted dictionary.

      • Minimizes duplication of effort both within and across organizations.

      • Allows content management independent of the OpenMRS version.

      • Promotes a transparent and accessible concept dictionary.

      • Enables public sharing of concepts.

  • Concepts naming conventions:

    • Use only alphanumeric characters (letters and numbers), with simple punctuation, such as commas (“,”), parentheses (“( )”), and forward slashes (“/”).

    • Descriptions may include non-alphanumeric characters, but sentence case is recommended – with the first letter capitalized unless acronym (e.g., HIV).

    • Collaborate with end users to ensure concept names are clear, meaningful, and aligned with their workflows.

    • Avoid renaming concepts that are already used for storing clinical data, as this may impact data consistency and reporting.

  • Concepts should include a clear and unambiguous description (at least in the system's default locale) that defines its meaning and, ideally, outlines its intended use.

  • Design for Re-use:

    • Avoid boolean datatype for symptom & diagnosis concepts → Use datatype N/A for these and use them as answers (not questions

🟢 Managing Concepts and Metadata using the Open Concept Lab (OCL) Tool

Open Concept Lab (OCL) is a terminology service that allows for the creation, editing, and management of medical concepts, including those from Columbia International eHealth Laboratory (CIEL). These concepts include diagnoses, procedures, medications, and other healthcare terminologies. Both OCL and CIEL aim to improve healthcare informatics by offering tools that make health data more standardized and accessible.

The CIEL concepts are available within OCL, allowing users to subscribe to, update, or customize these concepts for their specific needs. If an organization or an individual wants to create a dictionary using the Open Concept Lab (OCL) tool, there are several steps involved. Here's a step-by-step guide focusing on the OCL TermBrowser:

Steps for creating a new collection or repository for content

The steps for creating a dictionary using the Open Concept Lab (OCL) include:

1. Accessing OCL TermBrowser

You'll need an account to contribute to or manage terminologies. To access OCL:

Visit the OCL Website:
Navigate to the Open Concept Lab website at app.openconceptlab.org.

Log In or Create an Account:

  • If you already have an account:

    • Click the "Sign In" button at the top right of the page.

    • Enter your login credentials and proceed.

  • If you're new to OCL:

    • Click the "Sign In" button.

    • Select "Register" to create a new account.

    • Enter your email address and set up your account by following the instructions.

    • Check your email inbox for a verification email, and click the link provided to confirm your email address.

Access and Navigate OCL:

  • Once logged in, you'll have access to OCL's features.

2. Creating an Organization

  1. Log in to OCL

  2. Navigate to Organizations

  3. Create a New Organization

  • Click the "Create Organization" button.

  • Fill out the necessary details:

  • Name: A unique name for the organization.

  • Description: A brief summary of the organization’s purpose.

  • Add organization website e.g., https://openmrs.org

  • Add company name e.g., OpenMRS

  • Add “About Org” e.g., Learn more at https://openmrs.org

  • Click "Save" to create the organization.

 

3. Adding Members to the Organization

  • Access the Organization

    • From the Organizations page, click on the name of the organization you just created.

  • Manage Members

  • In the organization’s dashboard, locate and select the "Members" tab

  • Edit Membership

    • Add new members 

    • Once done, click UPDATE

4. Creating Repositories (Sources and Collections)

📌 Sources serve as repositories for original content, storing the concepts you create as well as any concepts you adapt from other sources. In the case of adapting, what usually happens is that you come across a concept that closely aligns with your requirements but isn’t an exact match. You can ‘Clone’ it → copy it into your source and modify it to better suit your needs. This process allows you to develop new concepts that may not be available in existing libraries.

📌 Collections are for organizing concepts from one or more sources, often for specific use cases or subsets of data.

→ Creating a New Source (Optional)

For New Concepts (Source):

  1. Set up the source:

    • Navigate to "Sources" and click + Source.

    • Add the short code, short name, full name,  description, language, and source type, and then select OpenMRS Validation Schema under the schema type.

      • Ensure the short code is descriptive and unique as it cannot be changed later.

    • For OpenMRS users, additional steps under Advanced Settings are:

      • Enable ID auto-assignment: Set IDs to sequential numbers.

      • Use UUID for external IDs.

  2. Save the source:

    • Create the source, although you may not use it immediately.

→ Creating a New Collection

For Organizing Existing Concepts (Collection):

 

1. Start a new collection:

  • Navigate to "User Collections" and click on the + Collection button.

2. Configure collection details:

  • Short Code: Provide a unique short code (e.g., OpenMRS_Demo, mini-demo etc).

    • Ensure it is descriptive and unique as it cannot be changed later.

    • Name and Description: Add a descriptive name and an optional detailed description.

    • Languages: Select the default and supported languages for the collection.

    • Validation Schema: For OpenMRS users, select the OpenMRS Validation Schema to ensure compatibility.

    • Optional Settings: You may add custom attributes, FHIR settings, or an about page.

3. Save the collection:

  • Click the Create Collection button. Your new collection will now appear in your profile.

 

5. Adding Concepts to the Collection

i) Search for concepts:

  • Use the Global Search feature to find concepts (e.g., “Routine Blood Panel” or “Malaria” or “HIV Test Performed” etc).

  • Apply filters to narrow results by:

    • Source (e.g., CIEL, LOINC, PIH).

    • Class (e.g., Lab Test, Diagnosis, Procedure, Finding).

    • Data types (e.g. numeric, text, coded).

ii) Review and verify the concept:

  • Click on a concept to view details like mappings, associations, and usage (e.g., what questions it answers or sets it belongs to). This step is crucial to ensure that the concept fits your needs in terms of definition, scope, and applicability.

iii) Add to the collection:

  • Click Add to Collection and choose your target collection.

  • Use the OpenMRS Compatible Cascade option to include mappings and set members. This ensures that related metadata or mappings are also added in a way that's compatible with OpenMRS systems.

  • Confirm and wait for the references to be added (this might take a few seconds). Ensure there are no conflicts.

  • If successful, you'll see a green message indicating that "references added successfully", showing both concepts and mappings.

  • If there are messages in red, it means the concepts (or their mappings) are already in your collection.

iv) Verification of Addition:

  • Go back to your collection to verify that the concept, including any answers or mappings, has been added correctly. Check for the presence of the concept and any associated data like answers to questions (e.g., Yes/No for an HIV test Performed).

 

Malaria Concept Diagnosis Example

  • Search malaria concept under global search

  • You can see what other organizations are using it for example, PIH has used the same concept

  • Check the CIEL concept since that is what you want to use to build your dictionary and on the right, you will find some mappings used i.e. SAME-AS, CONCEPT-SET-1, Q-AND-A-1

6. Using OCL Bulk Importer

For cases where there are many concepts and mappings (i.e. hundreds or thousands), OCL does offer a bulk import interface where a formatted CSV or JSON file can be used to create many concepts, mappings, sources, collections, etc. Be warned that this method is very powerful but may take time to learn for the first time. 

OCL’s bulk import page can be found in the Apps menu at the top-right of the screen on OCL Online when you are signed in.

7. Cloning to source

As stated earlier, when a concept is Close but Not Exact, you may need to tweak it to suit your needs. If for example, you find a concept in CIEL or another source that nearly fits your needs but requires some adjustments you can pick the option "Clone to Source" which will allow you to make a copy of this concept within your source.

📌 Cloning Process:

  • Copy with Mappings: "Clone to source" will not only copy the concept but also its mappings. This means all the connections or references to other terminologies or concepts are duplicated with the concept.

📌 Ownership and Independence:

  • Ownership: Once you clone a concept to your source, you become the owner of this new instance of the concept. This means:

    • Control: You can now modify this concept without affecting the original in CIEL or wherever it came from.

    • Disconnection: By cloning, you break the link to the original CIEL concept. This concept in your source will no longer receive automatic updates or changes from the source.

  • Let’s search for smoking status in the global search

  • Review the concept and its answers

  • Clone to source and select the source e.g Mini Demo Source

  • Select the source (e.g Mini Demo Source)

  • Then select ADD to add the concept selected

  • Preview to see the concepts and mappings that will be added

 

Back to the mini-demo-source

  • Verify that the concept (e.g., "smoking status") and its associated answers have been added.

  • Note that these are no longer CIEL concepts; they are owned by the organization or source that created them.

  • The advantage, however, is that you can customize the concept to suit your needs

Modifying the smoking status concept

  • Click “Edit Concept” action

  • Click “Edit Concept”

 

  • You can add another translation e.g. Swahili translation for Malaria.

    • Select the locale as sw.

    • Enter the description as Hali ya kuvuta sigara.

    • Set the type to Fully Specified.

    • Mark it as Preferred.

    • Update the comment to indicate Add new locale concept name.

8. Tweaking the concept to add a new mapping

For example, if you want to tweak to add missing answers, the steps are:-

  • Click “Add Concept”

  • Add Concept Details

    • Concept Class: Finding

    • Datatype: Coded

    • Locale: English

    • Name: Smokes 33 cigs per day (missing answer)

    • Type: Fully Specified

    • Preferred: Checked

  • After adding the concept, verify it by selecting Action → Edit Concept. You will see the details of the concept you added, along with the automatically generated external ID.

  • Add this mapping as an answer to the concept "Smoking Status".

    • Within the "Smoking Status" concept, there is currently no answer such as "Smokes 33 cigarettes per day"→ which is what you want to be added as an answer. 

    • To include this as an answer, click on the "Smoking Status" concept.

    • Click “Add New Mapping”

  • Add the details.

    • Set the relationship type to Q&A.

    • Select the source as Mini Demo Source.

    • For the concept, search for Smokes 33 cigarettes per day.

    • Click Save.

  • Set the relationship type to Q&A.

  • Select the source as Mini Demo Source.

  • For the concept, search for Smokes 33 cigarettes per day.

  • Click Save.

9. Versioning

i) Create a Version: 

  • Once you're satisfied with the initial dictionary setup, create a version of your source or collection.

  • This is crucial for maintaining historical data and ensuring you can reference specific states in your dictionary.

ii) Ensure Your Workspace is Ready:

  • Your "head version" or current workspace contains all the latest work such as the edits or additions to your dictionary or collection.

iii) Create a Version:

  • Click + (Manage content)

  • Select “Add Version”

iv) Add a Version Number:

  • Assign a version ID. For example, if this is your first version, you could label it "Version 1" or simply "1". Subsequent versions would increment from there (e.g., 1.1, 2, etc.).

v) Add a Description:

  • Provide a brief description of what this version includes or what changes were made. For instance: “Added socio-demographic concepts."

vi) Check Release:

  • Before finalizing, review your changes or check if this version is ready to be 'released' or made available for use or review by others, if applicable.

vii) Click Create:

  • Once you've verified everything, click the "Create" button to save this state as an official version. This action will record this point in the history of your project, allowing you to revert to or reference it later if needed.

 

10. Adding the cloned concept to the collection

After adding the newly cloned concept to your collection (mini-demo collection), you will notice that the owner and source of the added concept (smoking status) are no longer attributed to CIEL.

  • Remember to select OpenMRS-compatible cascade

11. Mapping to other Concepts (Optional)

Define Relationships

To enhance interoperability, you can map the new concept to others within your source or to external terminologies or standards like SNOMED CT or ICD-10:

  1. Open the newly created concept.

  2. Click the “Add New Mappings” option.

  3. Select existing concepts or input codes from external standards as needed.

  4. Click Save

12. Dictionary Sharing or Subscription

  • If you want others to use your dictionary, you can share it by providing access or making it public.

  • You can subscribe to your OCL source or collection to automatically update your system with these concepts.

Ongoing Maintenance

  • Regularly update your dictionary with new concepts, mappings, or changes in medical terminology.

  • Engage with the community for feedback, which might lead to further refinement of your work.

⚫️ Importing Concepts to an OpenMRS Instance

1. Version & Expansion

  • Click on "+ Add Version" in your concept source or collection.

    • Add Version ID: Enter the next sequential version number (e.g., start with 1 for your first version and then move sequentially to 2, 3, etc for the subsequent versions).

    • Description: Provide a brief description of what this version adds or changes (e.g., "Added Socio Demographic Concepts").

    • Release: Check "Release" (by default this is unchecked)

    • Create: Click "Create" to finalize the new version.

    • Verification: Refresh the page to check if the version and expansions match your input.

2. Subscription URL Test QA

  • Subscription URL: Copy the subscription URL for the new version.

  • OpenMRS Admin Page: Navigate to the OpenMRS Admin page (in your instance).

  • Open Concept Lab: Open the "Concept Lab" module in OpenMRS.

  • Paste Details:

    • Paste the copied subscription URL for the new version number in the appropriate field.

    • Paste the token or authentication if required.

  • Save: Save these changes.

  • Import: Click the import tab and then click the "Import" action to begin importing the concepts.

  • Check Errors: Review any errors from previous imports in the “Previous Imports” tab.

  • Refresh: Refresh the page to ensure the import was successful.

3. Export Version

  • Export: Export the new version from the OCL to get a file format that the OpenMRS Initializer can process.

    • Click Export Version Icon

    • Select “Export Version”

    • OCL will create a Zipped file and it will show you when the export version is completed for you. 

4. Upload the exported file to your repository

5. Create PR: Create a Pull Request (PR) for the changes 

This process ensures that new or updated concepts are systematically incorporated into your OpenMRS instance, leveraging version control and collaboration tools like GitHub for managing metadata changes.

6. Confirm the changes made

  • Check which files changed → Confirm Old File Deletion and New File Addition

🟡 Importing Concepts from OpenMRS into OCL

If you are using OpenMRS and already have your dictionary of concepts defined, you will need to import your concept dictionary into OCL. While OCL supports importing of concepts in several formats, the most robust, feature-rich format for importing is JSON. But how do you get your OpenMRS concepts into this JSON format? Well, it’s possible; however, it’s a manual process and there are some technical steps involved, so if you are unfamiliar with SQL or using the command line, you may want to ask a more technical friend for assistance.

1. Prepare for your content in OCL

In preparation for importing your dictionary to OCL, you need to make a space for it. This involves making sure you have an account in OCL Online, an organization under which you can import your dictionary, and you have created a target source for your dictionary.

When creating the source into which you import your dictionary on OCL Online, it’s important to make sure you include any locales supported by your dictionary and set the source’s custom validation schema “OpenMRS” (to make sure OpenMRS validation rules are enforced for the source). You will need the short name for both your organization and your target source when running the ocl_omrs script later.

2. Validating your concept dictionary

OCL supports an “OpenMRS schema” that enforces constraints on the dictionary (e.g., all concepts must have at least one fully-specified name, fully-specified names cannot be duplicated, etc.). A summary and discussion of OpenMRS concept validation rules can be found on OpenMRS Talk. OpenMRS enforces most of these rules, but it’s possible to accrue inconsistencies over time and, while it’s good to clean them up in any case, you will definitely want to clean them up before trying to import into OCL, since OCL will not allow you to import any concepts that break a validation rule.

Connect to your OpenMRS database and step through the Concept Validation Queries. Each of the validation queries should return an empty set (zero results). Note that these validation queries are read-only (they don’t change or try to fix anything). If you get any results from the validation queries, they represent concepts that break one or more validation rules and you will need to fix these concept(s) and repeat the validation queries until you can get through them successfully (empty result for each). Since these validation queries are used for CIEL, the locale checks are specific to the locales used by CIEL. If you are using locales not included in CIEL, then it’s possible you could get results on the locale check and can ignore those (the point of the locale validation step is to make sure you explicitly know all of the locales supported by your dictionary). Once you can run through all the validation queries successfully, you’re ready to export your dictionary.

3. Exporting your concept metadata from OpenMRS in SQL format

Assuming you are using MySQL, you can use mysqldump on the command line to export all concept-related table information in SQL format. This example uses the root user and will prompt you for that user’s database password (replace “YYYYMMDD” with today’s date):

mysqldump -u root -p --opt \ openmrs \ concept concept_answer concept_class concept_complex \ concept_datatype concept_description concept_map_type \ concept_name concept_name_tag concept_name_tag_map concept_numeric \ concept_reference_map concept_reference_source concept_reference_term \ concept_reference_term_map concept_set \ concept_stop_word > concepts-db-YYYYMMDD.sql

4. Transform the SQL format into OCL’s JSON format

There is a script on GitHub called ocl_omrs that can be used to convert your SQL dump into OCL’s JSON format for importing. To run the script, you will need to clone the repository locally and have git and Docker installed on your machine.

First you will need to clone the ocl_omrs script from GitHub. Open a terminal, navigate to a folder under which the ocl_omrs folder can go and use the following commands to clone the ocl_omrs script and change into its directory:

git clone https://github.com/OpenConceptLab/ocl_omrs cd ocl_omrs

Next, copy your SQL export into the local folder for the ocl_omrs script:

cp /path/to/concept-db-YYYYMMDD.sql local/

Once your dictionary SQL export is under the local subfolder, you can convert it to JSON using a command like this:

  • MYORG is the name of your organization in OCL

  • MYSOURCE is the name of your source in OCL for your dictionary.

The ocl_omrs script uses Docker to create a temporary OpenMRS database inside a docker container, import your SQL into that container, and then run a python script to write a JSON file from the contents of the concept tables.

If your dictionary references any sources unknown to OCL, the script will abort, reporting any missing sources. You will need to create these sources in OCL and you may need to add lines to the omrs/management/commands/__init__.py file to map from the reference in OpenMRS to the matching organization and source within OCL.

If all sources are found, the script will run for a while (may be minutes for a small dictionary, but can be 15+ minutes for large dictionaries). When the script finishes, there should be a JSON file in the local subfolder (alongside your SQL file) that contains the JSON you need to import into OCL.

5. Import the JSON to OCL

Use the Bulk Import tool within OCL to import your JSON file. When the import completes, be sure to download the report, since even if the import appears to be successful, you may sometimes find some non-fatal errors reported in the import report. The report is in JSON format and has a section that reports how many resources were created, updated, failed, etc. If all resources were created or updated with zero failures, you can be confident all of your concepts are now in OCL.

🔴 Managing Concepts and Metadata using Admin Legacy UI

1. Concept class

The concept class in OpenMRS (or any healthcare terminology system) is important because it helps categorize concepts based on their intended use and meaning within the system. Proper classification of concepts ensures consistency, data integrity, and efficient system functionality. Concept class is crucial in ensuring: 

📌 Organizational Clarity: Concept classes group related concepts together, making it easier to manage, search, and retrieve relevant concepts. Examples include classes like Diagnosis, Lab Test, Drug, Symptom, Procedure, etc. 

📌 Standardization and Interoperability: By assigning the correct concept class, data can be mapped to standard terminologies (e.g., SNOMED, LOINC), ensuring seamless integration with external systems. It facilitates accurate data exchange for national or global reporting. 

📌 Efficient Querying and Reporting: Concept classes help refine queries by filtering specific types of data, such as retrieving only lab test results or diagnosis codes for analysis. They ensure that reports pull relevant data for analytics dashboards and clinical decision support.

📌 Data Validation and Integrity: Certain operations may depend on concept class, such as restricting medications to the "Drug" class or ensuring only "Diagnosis" concepts are used in clinical workflows. This prevents data entry errors and maintains the integrity of stored health information. 

📌 Improved User Experience: When concepts are classified correctly, system users or healthcare providers can easily find and use the right concepts without confusion. This improves efficiency in workflows such as ordering tests, prescribing medications, and documenting conditions. 

📌 Decision Support and Alerts: Some clinical decision support rules may rely on concept class to trigger alerts or recommendations, such as flagging abnormal lab values or contraindications for certain drugs. 

Setting up Concept Classes

  1. The standard installation includes predefined concept classes. 

  2. To view them, navigate to the Legacy Admin > Administration > Concepts > Manage Concept Classes.

  3. To add a new Concept Class click the “Add Concept Class” link.

  4. To edit an existing Concept Class, click on the concept class itself.

  5. To delete, select checkboxes next to the concept names. 

    • Note that you cannot delete concept classes that are used in concepts already.

2. Concept datatype

  • Concept Datatypes define the format of data stored in concepts. They are predefined and read-only. 

  • You can view them under Legacy Admin > Administration > Concepts > Manage Concept Datatypes.

 

 

Viewing Concepts in your system

To view concepts available in your system, navigate to Administration > Concepts > View Concept To view concepts available in your system, navigate to Administration > Concepts > View Concept Dictionary or click “Dictionary” on the top main menu.

  • You can search for specific concepts using their name or ID or a code they are mapped to. Note there are 2 checkbox options to include retired concepts in the search and to show details of that concept. The retired concepts are no longer intended for use and may have been replaced with updated ones.

3. Concept Details

  • Fully-Specified Name: An unambiguous, unique label for the concept. All concepts must have at least one fully-specified name in English or in the primary language for the system.

  • Preferred Name: The preferred label to be used for the concept in a particular language.

  • Synonym: Other names for the concept which are not necessarily unique.

  • Short Name: A shortened version of the preferred name, which might be required for showing in a table where space is severely limited. These are not required to be unique.

  • Search Term: Alternate names that can be used to find the concepts but should not be used for display. Examples can be common misspellings, names of retired concepts replaced by this concept, barcode values to allow scanning to quickly find the concept.

  • Description: A clear and concise description/definition of the concept,  as agreed upon by the members of the organization or the most commonly referenced source.

  • Concept  Class: The classification of a concept. Currently, a concept can only have one class.

  • Concept Datatype: The structured format you desire the data to be represented as. Diagnoses and miscellaneous terms used as answers are given the datatype N/A (not applicable).

  • Version: A way to keep track of the number of updates applied to a specific concept. Best practice is to use a integer and increment it with each released version.

  • Answers: For questions with a coded datatype, these are the concepts representing all of the possible answers.

  • Set Members: For questions that are concept sets, the are the concepts that belong to the set.

  • Mappings: These are relationships between the concept and other codes or terms. These can be to standard or reference codes or to local codes or references such as modules.

 

An example of a PREGNANCY STATUS concept.

  • Fully specified name: Pregnancy Status 

  • Synonym: Patient Pregnant 

  • Preferred: Fully specified name

  • Short name: Optional

  • Description: Question on encounter form: "Is the patient pregnant?”

  • Class: Question

  • Datatype: Coded (which means that you will need to provide a predefined list of answers and these answers must also be defined as concepts). You can either create them in advance or add them later.

  • Add mappings e.g LOINC 11449-6, SNOMED CT 77386006, etc

4. Adding answers to a concept

To add answers to the PREGNANCY STATUS (above), 

  • First, we need to create or find three concepts (which are going to be answer concepts)

    • Yes

    • No

    • Unknown

  • Once the answer concepts are in place, choose and add them by editing the PREGNANCY STATUS concept.

5. Adding Concept mappings to a concept

Concept Mappings simplify the management of concept dictionaries by linking concepts with the same meaning. They are useful for integrating with external systems and allow users to define relationships between their system's concepts and standardized medical vocabularies (e.g., ICD, LOINC, SNOMED, etc.). They are often required by regulatory or reporting organizations.

To add mappings to a concept, look for the concept/s you intend to add the mapping and then click add mapping. Provide the mapping details as required e.g.,

📌 Relationship:- this is important to distinguish whether your concept is identical to the mapped concept, more specific, broader, only related, etc.

📌 Source:- this is the code system such as SNOMED, ICD-10, etc. and these need to be present in your Concept Sources table.

📌 Code:- this is the alphanumeric code used by the code system. The code source and code must be present in the Reference Term table in OpenMRS before you can map. If typing the code into the field does not find it, you may have to first create the reference term and then map it.

📌 Name:- this is the name of the code within the code system (not OpenMRS), it is optional but can help quality check the map if a reviewer does not know what the code is.

Here are examples of some mappings added to the Pregnancy Status concept showing various relationships (“SAME-AS”, BROADER THAN and NARROWER THAN)

6. Concept drug management

To view Concept Drugs, go to Administration > Concepts > Manage Concept Drugs. 

  • You can edit a concept drug by clicking its name to edit it, or 

  • You can create a new drug concept through the “Add Concept Drug” link. You must enter a name and choose one of the concepts of data type Drug to map the specific drug formulation to its generic ingredients. There are drug concepts for multi-ingredient drugs. For example, Septra as a brand name would be mapped to the Sulfamethoxazole/trimethoprim drug concept.

7. Patient identifier

A patient identifier is any unique number that can identify a patient. Examples are a Medical Record Number, a National ID, a Social Security number, a driver's license number, etc. A patient can have several identifiers. To see predefined identifier types, or to add a new one, go to Administration > Patients > Manage Patient Identifier Type.

 

OpenMRS Identification Number

  • The Regex Format and Description of Format fields are empty, but you could add a regular expression to validate each entered identifier. 

    • For example: \d{1,8}-\d would allow 1 to 8 digits followed by a dash and a single digit.

  • It is also possible to choose one of several predefined Identifier validators. 

    • Here Luhn CheckDigit Validator is used. 

    • The purpose of check digits is simple: to reduce errors when identifiers are manually entered via a keyboard. A check digit is a final digit calculated using a specific algorithm based on the preceding digits. This allows the system to immediately verify the accuracy of the entered number. If the check digit does not match, the number is flagged as invalid and rejected.

8. Internationalization

Concepts can be easily internationalized; i.e., you can enter different concept names for every allowed locale. For example, Yes is synonymous with Oui in French as shown below.

The list of allowed locales is stored in a setting locale.allowed.list as comma-separated language codes (for instance en, fr, order). 

⚪️ Troubleshooting Concept Import Errors

Common issues with metadata management:

Sample Error Messages

Possible Solution

Cannot import concept 1067AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA, tried: Retrying import of concept 1067AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA after failure due to ''Concept #178' failed to validate with reason: conceptMappings[3]: Cannot map a reference term multiple times to the same concept' [CAUSE]: 'Concept #178' failed to validate with reason: conceptMappings[3]: Cannot map a reference term multiple times to the same concept

The issue likely occurred because concept 1067 already existed in the system → You can verify this by checking the concept dictionary. 

Cannot import concept null, tried: Fixing duplicate names for concept null after failure due to 'Other faecal abnormalities' is a duplicate name in locale 'en' Changed name 'Other faecal abnormalities' in locale en to index term Done fixing duplicate names for concept null Retrying import of concept null after failure due to ''Concept #null' failed to validate with reason: No fully specified name for this concept' [CAUSE]: 'Other faecal abnormalities' is a duplicate name in locale 'en'

Try to resolve this by removing the ICD code for "Other Faecal abnormalities"l.

Cannot save mapping https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/mappings/317006/ [CAUSE]: Cannot create mapping from concept with URL https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/164924/, because the concept has not been imported

Check if the concept (164924) exists by searching for it in the concept dictionary. Then try importing the missing concept and also retry adding the mapping once the concept is successfully imported. 

Cannot save mapping https://api.openconceptlab.org/orgs/openmrs/sources/ExampleLabFilter/mappings/4660556/ [CAUSE]: Column 'uuid' cannot be null

The issue is likely because of a missing uuid. Try to resolve this by adding the concept uuid and then updating the collection.

Cannot save mapping https://api.openconceptlab.org/orgs/openmrs/sources/AllergyParentConcepts/mappings/3/ [CAUSE]: Column 'uuid' cannot be null

This issue may have been due to mappings missing their own External IDs. To resolve this, check the mapping configurations to ensure each mapping has a valid  External ID. Manually assign External IDs to the missing mappings if necessary. 

Cannot import concept 736e8771-e501-4615-bfa7-570c03f4bef5, tried: Retrying import of concept 736e8771-e501-4615-bfa7-570c03f4bef5 after failure due to 'could not execute statement' [CAUSE]: Column 'uuid' cannot be null

This issue can be resolved by Manually adding UUID to the concept Name UUID field.

Errors with reference mappings that do not have parent concepts.

Try to resolve this by first identifying the affected mappings. Then verify concept availability by checking if the referenced parents' concepts do exist. Try to import the parent concepts and ensure proper mapping relationships linked to an existing parent concept. Retry mapping process once the required concepts are available.  

 

⚪️ Additional Resources

  1. For more information about how to make and use collections in OCL, see our YouTube playlist.

  2. https://openmrs.slack.com/archives/D07KUSGM7T4/p1734382355997329

  3. PIH EMR Workshop Concepts (3)

  4. OpenMRS Academy_OpenMRS Technical Overview.pptx

  5. https://docs.openconceptlab.org/en/latest/oclapi/apireference/bulkimporting.html

  6. Migrating to OCL: PIH Use Case  

⚪️ Archives

This guide replaces the following old content:

⚪️ Step-by-Step Instructions

  1. Creating a New Collection in OCL

  2. Creating a New Source in OCL

  3. Adding Concepts to a Collection

  4. Cloning of Concepts and Adding Them to a Collection

  5. Adding a new Version for a Collection

  6. Subscription URL Test QA

  7. Importing Concepts from OCL to an OpeMRS Instance

 

Related content

Creating a New Collection in OCL
Creating a New Collection in OCL
Documentation
Read with this
Meta-Data and Terminology Lead
Meta-Data and Terminology Lead
Archives
More like this
Core Concepts
Core Concepts
Documentation
Read with this
Concept-Related Modules
Concept-Related Modules
Archives
More like this
Implementer Documentation
Implementer Documentation
Documentation
Read with this
Concept Dictionary Basics
Concept Dictionary Basics
Documentation
More like this