How to manage the OpenMRS concept dictionary with Open Concept Lab
This page explains how to manage the OpenMRS concept dictionary through Open Concept Lab (OCL), covering subscriptions, API tokens, offline zip imports, validation and local concepts kept alongside shared ones. Teams usually bring in a partner when they run or launch OpenMRS across several sites and need one set of concepts that stays consistent, including sites with unreliable connectivity. OpenMRS is a patient-based medical record system platform designed for resource-constrained environments, released under the MPL 2.0 with Healthcare Disclaimer. Its concept dictionary is the shared vocabulary for observations, diagnoses and orders. Forms, order configurations and interoperability interfaces all refer back to those definitions, so a duplicate or an unplanned change in the dictionary reaches every site that depends on it.
Open Concept Lab is the terminology module this page covers. It is where concept sources and collections are maintained, shared and drawn into OpenMRS instances, so it sits between the team that owns clinical content and the sites that consume it. The specific OCL features named above, including subscriptions, API tokens, zip imports and validation, change between releases and deployment patterns. Confirm each one against the current OCL documentation for the release your sites run before you design a process around it. Record the version you verified, because a process that relied on a feature in an older release may need rework after an upgrade.
The first decisions are about ownership and boundaries. Name who approves new shared concepts, who may create site-specific concepts, and how local concepts are named and identified so they do not collide with shared ones later. Decide which sites subscribe to which sources and who can rotate API tokens when staff leave. For disconnected sites, decide who produces each zip import, how the file is verified before transport, and how the site confirms which dictionary version it is running. As a first check, export the concept lists from every existing site and count duplicates and near-duplicates. That inventory shows how much reconciliation the import process will need.
Partner work usually covers the ownership model, the import and validation procedure, the site runbooks, reconciliation of existing concepts and training for the staff who maintain the dictionary. Cost and duration depend on the number of sites, how many concepts already exist in duplicate, how many sites are offline, and how many local concepts must be kept. Ongoing work recurs whenever new concepts are added, when OCL or OpenMRS is upgraded, and when a site's content changes. Ask any quote to name who performs each step, what validation evidence is delivered, which OCL and OpenMRS versions the design assumes, and how changes to shared concepts are tested before they reach live sites.
What the OpenMRS platform and Open Concept Lab give a dictionary team
OpenMRS provides the clinical record platform, and Open Concept Lab (OCL) is the terminology layer that feeds dictionary content into it. The cards separate what the platform documentation states from what your team must confirm in OCL documentation before designing a dictionary process around it.
Core platform and database support
OpenMRS core is written in Java and built with Maven. It runs on Tomcat or Jetty and supports MySQL, MariaDB and PostgreSQL. Your dictionary team should confirm which database engine and servlet container your target platform version and hosting standard support, because that choice also shapes backup, restore and replication work for concept data. Record the decision early, since it affects how you rehearse dictionary imports in a non-production environment.
Three deployment paths
The standalone package bundles an embedded database, so confirm whether that fits your production standard before choosing it. The WAR file deploys to Apache Tomcat against an existing MySQL database. The O3 Docker Compose stack runs four services: MariaDB, the OpenMRS backend, an Nginx frontend for the 3.x modules and an Nginx gateway, with an optional Certbot service for SSL certificates. Choose the path that matches how your dictionary staging environment will be built and refreshed.
O3 as the user frontend
The 3.x Reference Application, known as O3, is the current user-facing frontend. It is built on micro-frontend modules, and the latest O3 release listed on the download page is 3.7.1, dated July 13, 2026. Legacy HTML forms can be moved to the O3 form schema with a migration tool that Palladium Kenya built and the community adopted. Dictionary teams should confirm that every concept referenced by a migrated form exists in the target dictionary before cutover.
Subscriptions and API tokens
OCL documentation should describe how subscriptions link a local OpenMRS dictionary to upstream collections, and how API tokens authenticate imports and exports. Verify the scope each token grants, who can create and revoke tokens, how expiry and rotation work, and whether a token can be limited to a single collection. Keep tokens in your secrets manager and out of configuration files checked into source control.
Offline zip imports for disconnected sites
Sites without reliable connectivity may need dictionary updates delivered as zip files instead of through a live connection. Confirm the export format OCL produces, whether the zip carries versions and dependencies, and what the import reports when a concept already exists locally. Plan a dry run on a copy of the database, record the package version applied at each site, and agree who approves each drop.
Validation and local concepts
Validation rules determine whether an incoming concept is accepted, and local concepts let a site add terms that shared dictionaries do not cover. Verify in OCL documentation which validation checks run on import, how they report failures, and whether local concepts can coexist with shared ones without edits to shared records. Decide naming and ownership rules for local concepts before the first import, because later cleanup is harder.
Which dictionary sourcing model fits your sites
This table compares four ways to source the OpenMRS concept dictionary across sites, from connected subscriptions to fully local dictionaries. Read each row for the connectivity, governance, site count and data sharing conditions it suits, its main risk, and what to confirm in the Open Concept Lab and OpenMRS documentation before you commit. Multi-site programs often combine models, but the right choice depends on your network and on who owns terminology decisions.
| Sourcing model | Fit | Main risk | Confirm before choosing |
|---|---|---|---|
| Connected subscription | Sites with reliable connectivity, a single terminology owner, and data sharing rules that allow each site to pull shared content. | Every site depends on network access and token management, and a shared change can reach sites before local review. | Subscription setup, API token scope and rotation, and how updates to subscribed concepts are applied in OCL. |
| Offline zip import | Disconnected or low-bandwidth sites, with a central team that prepares and releases dictionary packages on a set schedule. | Sites fall behind releases, and manual import steps create version drift between sites. | Supported export format, compatible OpenMRS versions, and how re-imports handle updated or retired concepts. |
| Hybrid central import and distribution | Many sites with mixed connectivity, where one central instance validates shared content before passing it to sites. | The central instance becomes a bottleneck and a single point of failure for terminology updates. | Whether the central instance can package content for sites, and whether local additions survive a redistributed import. |
| Fully local dictionary | A single site, or programs with no shared terminology obligation and strict control over which external sources are used. | Concepts diverge between sites, which makes cross-site reporting and FHIR exchange harder to reconcile. | Whether OCL is needed at all, and which shared codes your reporting and exchange partners require. |
How subscriptions, API tokens and offline zip imports fit together
The choice between a subscription and an offline zip import starts with a question of where the OpenMRS instance can reach Open Concept Lab and who approves changes that reach production. With an online subscription, the OpenMRS site is linked to dictionaries in OCL and receives updates through that connection, so changes arrive without a manual transfer step. An offline import path works differently: a dictionary package is produced on a connected system, checked, moved on approved media and loaded into a site that cannot call OCL at all. Sites with unreliable connectivity need the offline path to be repeatable, meaning the same production steps, the same verification checks and a record of which package version each site holds. Without that record, two clinics can run the same nominal dictionary with different concepts, and support staff will struggle to explain why a form behaves differently between them.
API tokens are the credential that lets a system act on behalf of an OCL account, so they need the same handling as any other service secret. Start by listing every token in use and naming one accountable owner for each. Typical holders include the administrator who configures subscriptions, the person who produces offline packages, and any automation job that runs the export. Keep each token in a secrets manager or the platform's encrypted secret store, out of site configuration files, spreadsheets, tickets and chat channels. Confirm in current Open Concept Lab documentation how tokens are issued, what scope they carry, whether they expire, and whether they are bound to an individual user account or to an organization. Those answers decide whether a departing employee's token must be replaced individually or can sit under a shared service account, and they set what a stolen token could change.
Rotation and removal should be written into the operating procedure before the first subscription goes live. Set a rotation interval that your security policy requires, and rotate immediately after any suspected exposure, any change in the people who hold the token, or any change to the machine that uses it. Removal is the step most often missed. When an administrator or package producer leaves, the checklist should revoke the token in OCL, delete it from the secret store, remove any scheduled job that uses it, and confirm that no copy remains in the OpenMRS configuration or in offline package tooling. Confirm with the vendor whether revoking a token stops existing subscriptions from syncing, because that determines whether revocation can happen in a planned window or must be coordinated with clinical operations. Keep a dated log of each rotation and revocation so an auditor can trace who had access and when it ended.
An offline zip is a copy of dictionary content that leaves the connected network, so treat it as a controlled artifact with an owner, a checksum and a record of every site that receives it. Confirm whether the export carries any token or credential material (it should carry none) and document the file format, its packaging and its expected size for your deployment. Verify the package on the connected side before transfer, record its checksum, and repeat the same check after the file reaches the disconnected site. Decide who may load packages into production and whether that person must differ from the person who built the package. If current documentation describes a signing option for packages, confirm how the signing keys are generated and held. Finally, decide per site whether it runs as a subscription, an offline path or a mix of both, because a site that moves between connected and disconnected modes will need the same package controls in each direction.
Rollout sequence for OpenMRS concept dictionary management
This sequence moves OpenMRS concept dictionary management from ad hoc edits to a controlled process, with a named output and a sign-off at each step. The order matters because sourcing and validation decisions depend on the inventory, and production import should follow a tested pilot. Confirm the Open Concept Lab version and feature set with your team before you finalize the plan.
Inventory existing concepts and forms
The team lists the concepts, concept sets, answers and forms in use at each site, with a named owner for each and a note of where it is referenced, such as clinical forms, reports, order sets and data exports. Duplicate and unmapped local terms are flagged, and any legacy HTML forms that will need migration to the O3 form schema are marked. The step closes with a concept inventory that becomes the baseline for every later decision. Clinical informatics and the data manager sign off the inventory before sourcing choices begin.
Decide the sourcing model
The team decides which concepts come from shared dictionaries through a subscription, which arrive as offline zip imports for disconnected sites, and which stay local to the implementation. Each decision depends on connectivity, who holds the API tokens, and who approves changes to shared content. The output is a decision record that names the data flows, token owners and approval path. Confirm with your Open Concept Lab administrators which subscription and import options your deployment supports. The CIO or CMIO and the security lead sign off the record.
Set up a test OpenMRS instance
The platform team builds a non-production OpenMRS instance inside your infrastructure, using the deployment method your team has chosen from the options OpenMRS publishes, such as the WAR file for Tomcat with an existing database or the O3 Docker Compose stack. The database engine is confirmed against the supported list, and a copy of the current dictionary is loaded. The step closes when the build can be reproduced from documented steps and a backup and restore has been tested. The platform lead signs off the instance before any import runs.
Run a subscription or import pilot
The team runs one subscription or zip import against the test instance, limited to a single domain or form set so that results are easy to review. They record every concept created, updated or retired, along with any conflicts with local concepts and any form that renders differently afterward. The step closes with a pilot report that lists the changes and the conflicts that need a decision. The terminology owner signs off the report, and the team confirms whether the procedure can scale to the full dictionary.
Define and test validation rules
The team writes the validation rules that new and changed concepts must pass, such as required names in each locale, naming conventions, duplicate checks and handling of retired concepts. Each rule is tested with valid and invalid cases on the test instance, including edge cases from the pilot. The output is a rule catalogue and a test report with pass and fail results, plus the expected behavior for each failure. Confirm which rules Open Concept Lab enforces natively and which need local checks. Clinical informatics and QA sign off the report.
Establish local concept governance
The team sets up the rules for how local concepts are requested, reviewed, named, approved and retired alongside shared ones. The charter names the owners for each domain, the request workflow, the review cadence and the criteria for promoting a local concept to a shared one. The output is a written governance charter with a request template and a log of open decisions from the pilot. The steering group signs off the charter, since it sets who can change clinical vocabulary after go-live.
Import to production and cut over
The team runs the approved import procedure against the production instance inside a scheduled change window agreed with the client. Before the run, they confirm the backup, the rollback plan and the list of forms to check. After the run, they verify key concepts, form rendering and the sync or import logs against the pilot report. The output is a change record with the import results and the post-import verification. The business owner and the change board give the go or no-go decision before the import starts.
Hand over runbooks and train operators
The team delivers runbooks for subscription sync, zip imports, API token rotation, validation rule updates, governance requests and incident response, and trains the operators who will run them. Each runbook is tested by an operator who did not write it. The output is the runbook set, a training record and a list of open items with owners. The client operations owner accepts the handover in writing, which closes the rollout.
What drives effort and cost in concept dictionary work
This table lists the factors that most change how much work a concept dictionary project takes, and how each one moves effort up or down. Read each row as a lever: the driver explains the mechanism, and the last column names what the buyer can do before work starts. Most of the cost sits in the drivers that touch local concepts, legacy forms and approvals, so those rows deserve the most attention in scoping.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Number of sites and connectivity | Sites with reliable connections can use live subscriptions and API tokens, while disconnected sites need offline zip imports, extra packaging and reconciliation of each batch. | Group sites by connectivity early, standardize one import route per group, and confirm which sites will need offline handling. |
| Number and quality of existing local concepts | Local concepts that duplicate shared ones, use inconsistent names or lack datatypes must be mapped, merged or retired one by one before import. | Run a duplicate and naming review on a sample before scoping, and agree a rule for when a local concept is kept. |
| Legacy forms and reports that reference concepts | Every form, report and obs-based query that points to a concept UUID or name must be found and retested when a concept changes or is retired. | Inventory forms and reports that use concepts, and prioritize the ones used in daily clinical work. |
| Number of OpenMRS environments | Each environment (test, staging, production) needs its own dictionary state, import run and verification, and drift between them creates rework. | Keep the number of environments that receive dictionary changes small, and promote the same tested package through each one. |
| Validation rule complexity | Rules that depend on other concepts, answer sets or conditional logic take longer to design, test with real edge cases and document. | Keep rules simple where clinical need allows, and ask for a test case list for each rule before build. |
| Governance and approval workflow | Each concept change needs a named owner, a review step and a recorded decision, and slow or unclear approvers add waiting time to every batch. | Name the approvers and a decision deadline per change type, and agree which changes are routine and which need clinical sign-off. |
| Staff training | Clinical informaticians and local administrators must learn how subscriptions, imports, reviews and rollbacks work, and new staff need repeat training. | Budget for role-based training with a written procedure, and record who is trained on each step. |
| Ongoing change volume | A stable dictionary needs occasional updates, while a program that adds concepts for each new form or donor requirement needs a continuing review cycle. | Batch changes into scheduled release windows, and ask the partner to quote ongoing support separately from the one-time build. |
How the concept dictionary connects to FHIR2, SMART and identity
Concepts that Open Concept Lab imports are read by other parts of the OpenMRS stack, so the dictionary has to be coded consistently before anything else depends on it. The cards below cover the API layer, the SMART and identity modules, the Docker Compose environment where imports run, and the role mapping that controls who can change concepts.
FHIR2 as the REST API layer
The FHIR2 module exposes OpenMRS data through a FHIR REST API focused on R4, with translation support for R3. Resources such as Observation and Condition carry concept codes, so a concept that is duplicated, mis-mapped or missing a code will appear incorrectly to every FHIR consumer. Before go-live, check which FHIR resources your partners request and confirm that each one resolves to the concept codes you expect.
SMART on FHIR and Keycloak
The SMART on FHIR module supports the SMART App Launch Framework on top of FHIR2 and uses Keycloak as its default authorization server. Third-party apps that read or write clinical data depend on the scopes granted at launch, not on the concept dictionary itself. Confirm which scopes each app requests and whether any of them can alter concept-related data.
OAuth2 Login replacing basic authentication
The OAuth2 Login module replaces OpenMRS basic authentication with an OAuth 2.0 provider, and it documents Keycloak and Google configurations. It creates users on first login and maps names, email and roles from the identity provider. Decide whether your deployment will accept Google accounts for staff who administer concepts, because that choice determines how strongly those accounts are controlled.
Mapping concept administration roles
Concept administration rights in OpenMRS are granted through roles, so those roles need a matching group or role in the identity provider. Map only the roles that can import, edit or retire concepts to the small group of terminology administrators. Review the mapping after each identity change, because a broad mapping lets any authenticated user alter the shared dictionary.
Docker Compose services where imports run
The O3 Reference Application Docker Compose setup runs a MariaDB database, the OpenMRS backend, an Nginx frontend serving the 3.x modules, an Nginx gateway, and an optional Certbot service for SSL certificates. Concept imports run against this stack, so the backend and database must be reachable and backed up before an import starts. Confirm which services your environment will expose publicly and where Certbot certificates are stored.
Detail in the FHIR2 and SMART topic
This page covers only how the concept dictionary depends on FHIR2, SMART and identity. The sibling topic on the FHIR2 module and SMART on FHIR covers resource configuration, app launch and exchange with national health information systems in full. Read it before you finalize scopes, FHIR resource profiles or external exchange requirements, because those decisions change what the concept data must contain.
What buyers ask before bringing in an OpenMRS dictionary partner
How much does OpenMRS concept dictionary management cost?
The cost is almost entirely people and time, because OpenMRS has no paid edition and Open Concept Lab is used within the OpenMRS ecosystem. Cost drivers include the size of your concept inventory, how many sources you are reconciling, the amount of mapping and clinical review, the number of sites, and the testing needed before cutover. One-time costs cover the initial inventory, mapping, validation rule design, import testing and training. Recurring costs cover subscription review, governance of new concepts, token rotation, upgrade testing and any support retainer. Ask any partner for a quote that separates these items, names who performs each task, and states what is excluded. DeployOpen issues quotes from a written, fixed scope, so the scope document is where cost is controlled.
How long does a concept dictionary project take to complete?
Duration depends on the state of your existing terminology and how quickly decisions are made, not on the import tool alone. The main drivers are the volume of local concepts that need mapping to shared concepts, the number of clinical owners who must review and approve changes, how many environments must be validated, and whether offline sites need packaged imports tested on their own hardware. Duplicate or inconsistent concept names add review cycles. Schedule risk also rises when test environments are not available early. Ask a prospective partner to show the work breakdown behind its timeline, including which tasks depend on your clinicians and which depend on access to your systems.
What must our team provide before a dictionary engagement starts?
Your team supplies the inputs that the partner cannot create alone. Required inputs include a concept inventory export from each existing system, a list of clinical owners for each domain with named approvers, access to non-production OpenMRS and Open Concept Lab environments, and the decision makers who can settle naming and mapping conflicts. You should also provide your current data standards, any national or program terminology you must use, and the list of sites that run disconnected. Without named approvers and a decision path, review cycles tend to stretch. Confirm these responsibilities in the written scope so that each side knows what it owes and when.
Can our own team manage OpenMRS concept dictionary imports without a partner?
Yes, if the team has the right skills and enough time allocated. The work needs people who understand the OpenMRS concept model, including concept classes, datatypes, answers and set members, and who can review terminology with clinical staff. Operations skills matter too: administering Tomcat and the database, managing Open Concept Lab subscriptions and API tokens securely, and running repeatable import tests. A partner is most useful for the first build, for validation rule design and for handling disconnected sites. Many organizations combine an internal governance owner with an external partner for the initial build, then move maintenance in-house once the process is documented.
How do offline or disconnected sites receive dictionary updates?
Disconnected sites typically receive dictionary content through offline zip imports rather than live subscriptions. The general pattern is to prepare the package in a connected environment, transfer it to the site using media your security policy allows, import it into the local OpenMRS instance, and then verify the result against a checklist. Your design should record which package version each site runs, how conflicts with local concepts are resolved, and who approves each release for a site. Confirm in the Open Concept Lab documentation for your release how zip packages are generated, what happens to existing concepts during import, and how packages interact with subscriptions.
What happens to the concept dictionary after go-live?
After go-live the dictionary becomes an operating process. Recurring tasks include reviewing subscription updates from shared sources, approving new local concepts, rotating API tokens, checking that validation rules still match clinical practice, and testing each OpenMRS or Open Concept Lab change in a non-production environment before it reaches sites. Backups of the database and of the import packages should be tested, not just taken. Your team should also decide who owns the dictionary after the project closes. DeployOpen offers ongoing support, upgrades and testing as retainers, and those terms should be written with the same care as the build scope.
Which Open Concept Lab documentation points should we confirm for our release?
Confirm the points that change how the dictionary behaves in your environment. Check which OpenMRS platform or Reference Application release the Open Concept Lab documentation supports, because the latest supplied releases are the 3.x Reference Application 3.7.1 and the Platform 2.8.1, and your site may run another line. Confirm the zip import format and its behavior on conflicts, how API tokens are scoped and how long they last, how subscriptions are configured, which validation rules are available, and how locally created concepts are kept separate from shared ones. Record the answers in your design document and test each one before go-live.
Does OpenMRS have a paid edition, and who runs deployments?
OpenMRS has no paid edition. The platform is released under the Mozilla Public License 2.0 with a Healthcare Disclaimer, and OpenMRS Inc., a 501(c)(3) nonprofit, provides the fiscal and legal foundation for the project. Deployments are run by implementer organizations and partners, along with the volunteer community, and national distributions such as KenyaEMR run on the same platform. This means your costs come from the people who build, test, host and support your deployment, not from a license. When you evaluate a partner, ask who will operate the system after go-live and how that responsibility is documented.
How DeployOpen scopes and delivers OpenMRS dictionary work
DeployOpen treats OpenMRS concept dictionary management with Open Concept Lab as a defined piece of work inside your own infrastructure. We agree the dictionary scope, subscription and token setup, import path and validation rules in writing before build starts, then hand over documentation and a working process your team can run.
How we scope
- Engagements are fixed-scope, with the dictionary sources, subscriptions and import paths agreed in writing first.
- Scope records which concept sets are shared from Open Concept Lab and which are maintained as local concepts.
- Scope names the sites that need offline zip imports and the network constraints each site has.
- Scope lists the validation rules and naming conventions that concept changes must pass before they reach production.
How we build
- We configure Open Concept Lab subscriptions and API tokens in the environment you control, with access limited to named service accounts.
- We test imports first on a non-production OpenMRS instance, checking how shared and local concepts behave side by side.
- We build the offline zip import procedure for disconnected sites and test it end to end on a representative instance.
- We document each validation rule with its expected result so reviewers can repeat the checks.
How we hand over
- You receive written runbooks covering subscription renewal, token rotation, import steps and rollback for concept sets.
- Handover includes a record of the local concept catalog, its owners and the rules that govern changes to it.
- We walk your administrators through a test import and a validation failure so they can recognize and resolve common errors.
- Handover documents list the OpenMRS version and Open Concept Lab settings in use, so later upgrades start from a known baseline.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer that covers the dictionary workflow.
- Support can cover reviewing new shared concept releases before they are imported into your production instance.
- Ask any support provider how they will confirm concept changes against your validation rules before go-live.
- Confirm with us in the quote how token rotation, offline import support and version upgrades will be handled.
