Health Terminology And Clinical Forms

Health terminology gives clinical meaning to forms, observations, orders, lab results, HMIS indicators, claims, and interoperability mappings.

Terminology Model

Layer	Purpose
Terminology repositories	OCL-style sources and collections that own/publish concepts, code systems, mappings, value sets, forms, and order sets.
Collection versions	Published dictionary snapshots used by clinics so runtime forms and reports stay stable across terminology updates.
Code systems	External or local namespaces such as ICD, LOINC, SNOMED, RxNorm, UCUM, national HMIS codes, or a hospital-local dictionary.
Concepts	Stable clinical ideas such as malaria diagnosis, systolic blood pressure, pregnancy status, medicine dose form, or visit type.
Concept names	Preferred, short, fully specified, synonym, and local-language labels.
Classes and datatypes	Clinical grouping and value behavior such as diagnosis, lab test, question, numeric, coded, text, date, or boolean.
Value sets	Allowed coded answers for a field, order reason, visit type, diagnosis group, result interpretation, or report indicator.
Mappings	Relationships between Pinkapple concepts and external concepts or codes.
Reference ranges and unit mappings	Numeric result ranges, critical thresholds, UCUM/unit relationships, sex/age-specific rules, and lab interpretation support.

OCL-Style Repository Model

Open Concept Lab is a collaborative terminology management platform for managing, publishing, versioning, and subscribing to concept dictionaries, sources, collections, concepts, and mappings. Pinkapple Health now follows the same source/collection pattern locally, while still acting as an HMIS runtime that executes clinical and ERP workflows.

Use OCL as an upstream terminology authority or source of dictionary content. Use Pinkapple Health to import, seed, or curate the repository content, then bind those concepts to patients, encounters, forms, order sets, billing items, stock items, claims, reports, audit trails, and interoperability messages.

Capability	OCL	Pinkapple Health
Collaborative cloud dictionary authoring	Primary focus.	Limited tenant-local setup.
Sources and collections	Primary versioned terminology repositories.	First-class Health terminology repositories, sources, collections, versions, and members.
Clinical workflow execution	Not the main purpose.	Primary purpose.
Patient chart, orders, billing, pharmacy, stock, GL	Out of scope.	Integrated through Pinkapple primitives.
Import from external dictionaries	Strong.	Supported through seed packs and future integration jobs.
Runtime validation in forms/orders	Not a care workflow engine.	Enforced by Health forms, order sets, observations, and service profiles.

Repository Types

Type	Use
Source	A terminology authority such as Pinkapple Local Health, ICD-10, LOINC, SNOMED CT, RxNorm, UCUM, or OCL.
Collection	A curated bundle such as Uganda Clinic Starter that includes selected concepts, value sets, forms, and order sets.

Each repository has a release status, sync mode, canonical URL, optional OCL owner/source/collection identifiers, and service scope. Runtime records such as code systems, concepts, concept maps, and value sets store repository references so the system can answer “where did this clinical meaning come from?”.

Starter Repositories

The Health seed pack includes these repository records as the baseline terminology model:

Repository	Type	Intended use
Pinkapple Local Health Source	Source	Tenant-local clinical concepts, forms, order sets, and runtime extensions.
ICD-10 Source	Source	Diagnosis and morbidity classification mappings.
LOINC Source	Source	Lab test, observation, and measurement mappings.
SNOMED CT Source	Source	Clinical finding, procedure, and terminology mappings where licensed.
RxNorm Source	Source	Medication terminology mappings where applicable.
UCUM Source	Source	Unit-of-measure mappings for coded observations and lab results.
FHIR R4 Source	Source	Interoperability resource/profile mappings.
HL7 v2 Source	Source	Message-segment and integration mappings.
DICOM Source	Source	Imaging modality, study, and report mappings.
OCL Import Staging	Source	Landing area for future OCL imports before publication into a collection.
Uganda Health Starter Collection	Collection	Curated Uganda clinic/health-centre concepts, forms, order sets, and reports.

This makes Pinkapple repository-based in the same architectural sense as OCL: content belongs to a source or collection, collection versions publish stable snapshots, and runtime records carry repository provenance.

Concept Governance

1. Create or import the terminology repository first.
2. Create or import the code system inside the relevant repository.
3. Create concepts with the correct repository, datatype, and class.
4. Add names and descriptions before publishing forms or order sets that use the concept.
5. Build value sets for fields that should only accept coded answers.
6. Publish collection versions for starter packs or national dictionaries.
7. Add mappings to national, OCL, OpenMRS, FHIR, ICD, LOINC, SNOMED, RxNorm, UCUM, or payer codes where needed.
8. Avoid changing the meaning of a concept after it has generated observations or submitted reports. Add a new concept or retired mapping instead.

OCL Import Pattern

Use OCL as an upstream authoring and distribution source where appropriate, then import into Pinkapple through a governed review repository.

1. Pull or receive content into OCL_IMPORT_STAGING.
2. Validate duplicate concepts, names, mappings, datatypes, and classes.
3. Curate the accepted content into a local source or a Health collection.
4. Publish a collection version.
5. Bind concepts to forms, order sets, service profiles, HMIS indicators, reports, Billing, Stock, Claims, and interoperability mappings.
6. Keep historical collection versions available so old observations, submitted forms, reports, and claims remain reproducible.

Importing From OCL

Use Healthcare -> Setup -> Clinical Terminology -> Import Review to bring source-backed terminology into Pinkapple.

Pinkapple supports two user workflows:

Workflow	When to use it
Fetch from OCL	The source is available from the OCL API and the system administrator has connected OCL API access for the tenant.
Paste JSON	You received an approved OCL, OpenMRS, FHIR CodeSystem, or FHIR ValueSet payload outside the live API flow.

Before live OCL import, a system administrator should prepare Integration/ETL:

1. Open Administration -> Integration/ETL -> Credential References.
2. Create a credential reference for the OCL API token.
3. Use a governed provider such as AWS Secrets Manager or a facility-approved HTTPS external secret store.
4. Use Environment Variable only for local or controlled test smoke. Production tenants should not depend on server .env tokens.
5. Open Connections and create or edit an OCL/OpenConceptLab connection that points to https://api.openconceptlab.org.
6. Link the OCL connection to the credential reference, then run the connection test or preflight check.

Runtime support currently resolves AWS Secrets Manager references such as arn:aws:secretsmanager:... or aws-sm:secret-name, and HTTPS external secret-store endpoints. GCP Secret Manager, Azure Key Vault, and HashiCorp Vault references can be registered for governance, but they require the corresponding provider client to be enabled before live imports can use them.

For live OCL import:

1. Select Import Source Payload.
2. Keep Dry-run Review Only enabled.
3. Enable Fetch From OCL.
4. Select the tenant OCL Integration Connection created in Administration > Integration/ETL.
5. Choose the source format, usually OCL.
6. Select the source repository, such as CIEL Source, LOINC Source, RxNorm Source, or OCL Import Staging.
7. Enter either a full OCL API URL or the OCL owner/source fields. For example, owner CIEL, source CIEL, and an optional concept code or search term.
8. Keep Include Mappings enabled when you want Pinkapple to import source mappings with the concepts.
9. Submit the dry-run and review the normalized concepts, names, mappings, and value sets.
10. If the dry-run is correct, rerun the import with dry-run disabled.
11. Open Binding Assistant to bind imported concepts to operational items, stock items, Health profiles, and Pricing targets.

Useful OCL resources:

• OCL documentation
• OCL API concepts reference
• OCL sources and collections
• OCL web application

OCL imports may require API access. If a live fetch fails with an authentication message, ask the system administrator to configure a tenant-owned OCL credential reference and OCL Integration/ETL connection before retrying. Users should not paste API tokens into terminology forms.

Country Packs And Local Content

Country packs such as Uganda, Kenya, Rwanda, Burundi, or facility-specific starter collections should not become separate local clinical dictionaries. Treat them as curated implementation collections that point back to authoritative terminology where possible.

Content type	Preferred authority path
Medicines	RxNorm, CIEL/OpenMRS, approved national formulary, or another reviewed drug dictionary.
Lab and observation concepts	LOINC, CIEL/OpenMRS, UCUM for units, and local reference-range governance where needed.
Diagnoses and conditions	ICD-10, SNOMED CT where licensed, CIEL/OpenMRS, and national reporting mappings.
Forms and value sets	OCL/OpenMRS-style metadata, national HMIS forms, or approved facility clinical-governance collections.
Facility tariffs, items, and stock	Pinkapple ERP operational items, stock items, Billing, Pricing, POS/Teller, and GL setup.
National reports and payer mappings	National HMIS/payer code systems plus Pinkapple report and claim mappings.

The country pack should help users start faster, but clinical meaning should remain source-backed. Pinkapple owns the operational execution layer: which item is sold, stocked, billed, priced, claimed, posted to GL, or shown on a workflow screen.

Import Review Outcomes

Result	Meaning	User action
Concepts normalized	Pinkapple recognized source concepts and names.	Review class, datatype, source, and preferred name before applying.
Mappings normalized	Source mappings such as CIEL, LOINC, RxNorm, SNOMED, ICD, UCUM, or national codes were detected.	Confirm the mapping type and confidence before using the concept in live care.
Value sets normalized	Allowed coded answers were detected from the source payload.	Review the member list and publish only clinically approved sets.
Needs source mapping	A concept exists locally but is not yet backed by an authoritative source.	Add or import a verified SAME_AS mapping before activating ERP bindings.
Ready for ERP binding	Source authority and required ERP pieces are present.	Use Finalize Activation only after clinical and operational review.
Blocked binding suggestion	Missing source mapping, operational item, stock item, profile, or price target.	Use guided actions to create or bind the missing primitive records, then rerun the binding check.

Binding Imported Concepts To ERP Records

Clinical terminology does not replace ERP setup. After import, use Binding Assistant to connect the concept to runtime records:

Clinical concept type	Typical Pinkapple binding
Medication concept	Medication profile, operational item, stock item, Pricing target, batch/expiry and controlled-drug rules.
Lab test concept	Lab test profile, operational item/service, specimen rules, result concept, Billing item, Pricing target.
Imaging concept	Imaging profile, operational item/service, modality context, Billing item, Pricing target, DICOM mapping.
Procedure concept	Procedure/theatre profile, operational item/service, consumables/implants where used, Billing and Pricing.
Observation concept	Form field, observation datatype, unit concept, value set, reference range, chart graph, and report mapping.
Diagnosis concept	Condition/problem entry, ICD/SNOMED mapping, claim coding, reporting, and decision-support rules.

This separation is intentional. OCL or another terminology authority defines the clinical meaning. Pinkapple binds that meaning to items, stock, prices, forms, claims, reports, and accounting workflows.

What Pinkapple Can Bind Automatically

Pinkapple assists the steward by checking whether a concept is source-backed and whether matching ERP records already exist.

Binding status	Meaning	User action
Auto ready	The concept has a verified source map, a matching Health profile, an item/stock record, and a pricing target.	Review the suggested binding and finalize it if it matches the facility’s clinical catalog.
Needs review	The system found a weaker match, such as a name-only item match.	Confirm the item/profile/price before activation.
Blocked	A required piece is missing, usually source mapping, operational item, stock item, Health profile, or pricing.	Import or create the missing piece, then rerun Binding Assistant.

For example, a medicine concept with a verified RxNorm mapping can be bound to a medication profile, stock item, and price target. A medicine without a verified source map remains blocked even when a matching stock item and price exist, because clinical meaning has not been confirmed.

Terminology Stewardship Workflow

Use this workflow when a facility adds a new clinical concept, lab test, medicine, form field, or national-reporting code.

1. Search existing concepts first so the same clinical meaning is not duplicated.
2. Confirm the concept class and datatype. For example, a coded question, numeric observation, diagnosis, drug, lab test, procedure, or answer concept.
3. Add preferred names and synonyms that users will recognize in clinical forms and lookups.
4. Add mappings to ICD, LOINC, SNOMED, RxNorm, UCUM, national HMIS, payer, or local codes where available.
5. Add the concept to the correct value set or concept set.
6. Review the concept in a draft form, order set, or service profile.
7. Publish the collection version only after clinical and reporting owners approve the meaning.
8. Use the published version in live patient care.

Do not change a concept meaning after it is used on patient records. If the clinical meaning changes, retire or supersede the old concept and create a new one.

Common Uganda Starter Bindings

User task	Terminology binding
Register an OPD visit	Visit type and encounter concepts, plus facility and service context.
Record triage	Numeric vital concepts, unit concepts, acuity value set, and danger-sign coded answers.
Submit a consultation form	Symptom, diagnosis, assessment, plan, and disposition concepts.
Order a malaria test	Malaria RDT order concept, lab test profile, specimen rules, result value set, and Billing/price link.
Dispense paracetamol	Medication concept, medication profile, stock item, batch/expiry, route/frequency concepts, and price.
Report HIV or TB indicators	Program concepts, result concepts, HMIS indicator mappings, and reporting-period rules.
Bill a consultation or bed-night	Health charge default, Billing item, pricing target, branch scope, payer context, and GL rule.

Clinical Forms

Clinical forms are OpenMRS-style structured forms, but they run through the Pinkapple form engine.

Form part	Meaning
Form definition	Form code, name, lifecycle status, visit context, version, and publication state.
Sections	Logical groups such as vitals, symptoms, examination, diagnosis, plan, or follow-up.
Nested sections	Repeating or grouped sub-sections, such as obstetric history or medication history.
Fields	Questions bound to concepts, datatypes, value sets, required rules, units, and display behavior.
Submission	Immutable clinical payload linked to patient, encounter, provider, location, and form version.
Generated observations	Coded facts created from submitted concept-bound fields.
Amend and void	Corrections are audited; finalized clinical facts are not silently overwritten.

Value-Set-Aware Lookups

When a field expects a coded value, use a concept lookup scoped by value set. Examples:

Workflow	Concept filter
Open visit	Visit type concepts only.
Diagnosis	Diagnosis/problem concepts only.
Lab result interpretation	Interpretation concepts only.
Allergy severity	Allergy severity value set only.
Medication route	Route of administration value set only.
Discharge disposition	Discharge outcome/disposition value set only.

Practical Rules

• Do not create free-text fields when a coded concept is needed for reports, claims, decision support, or interoperability.
• Do not put concept codes in user-facing forms as internal IDs. Show names, codes, and source where useful.
• Do not duplicate billing or inventory classification in terminology. Bind clinical concepts to Billing and Inventory profiles instead.
• Do not delete used concepts. Retire or supersede them through controlled metadata.

Related Guides

• Health Setup
• Patient Chart And Visits
• Uganda Starter Pack