Concept dictionary

What it does

The concept dictionary is the shared vocabulary of the platform — the diagnoses, tests, questions, and answer options used across forms and records. Using one dictionary keeps data consistent and reportable everywhere it's captured.

Where to find it

Choose Concepts from the navigation (/concepts). You'll see a searchable list of concepts.

📸 Screenshot: the Concepts list (concepts-list).

Common tasks

Find a concept

Type a name or code into the search box in Concepts and open a result to see its details — its class, data type, and any answers or mappings.

Add a concept

1. In Concepts, select New (/concepts/new).
2. Give it a name, pick its class (what kind of thing it is) and data type (the kind of value it holds — a number, a date, text, or a coded answer).
3. For coded concepts, add the allowed answers. Select Save.

Group concepts into a set

Open Sets (/concepts/sets) to build a concept that contains other concepts — useful for panels and grouped questions.

Map to external code systems

Open Mappings (/concepts/mappings) to link a concept to standard codes (for example ICD or LOINC) so data can be shared and reported against those systems.

Set units and ranges for a numeric concept

1. Open a concept whose data type is Numeric.
2. In Numeric metadata, search the Unit of measure picker and choose a UCUM code (for example kg or mm[Hg]).
3. Optionally set normal, critical, and absolute ranges, display precision, and whether decimals are allowed. Select Save numeric metadata.

The unit list is the platform's UCUM dictionary — you cannot type a free-text unit. Codes are exact and case-sensitive (mg is milligram; Mg is megagram). Common spellings that are not registered (mcg, IU, mmHg) are refused; use the listed codes (ug, [IU], mm[Hg]). Leave the unit empty for unitless scores (for example Apgar or pain scores).

If the server refuses a choice, the page shows its message (for example that a term belongs to LOINC rather than UCUM) instead of a generic failure.

Triage unmapped terms

Open Terminology → Unmapped terms (/admin/terminology/term-triage). This is the queue of free text clinicians recorded when the dictionary had no concept for what they met, together with the Other, specify answers they typed. It is scoped to your tenant — a term means what your clinicians meant by it, and is never mapped across tenants.

The screen shows two backlogs, and they are deliberately not one list, because the fix differs:

Backlog	What it means	Who fixes it	How
Dictionary backlog (unmapped terms)	The dictionary was missing a concept	Terminology steward	Map to an existing concept, create the concept and map, or dismiss as noise
"Other, specify" answers	One question's answer set is missing a value	Form author	Extend the parent question's answers in the form builder; the row names the question (Extend question #…)

An Other, specify phrase cannot be mapped, and the screen offers no mapping action for one. The clinician already chose a coded answer — Other — so adding a concept would not change what was recorded; the question is what is wrong. Those rows can still be dismissed if the text is noise.

Each row carries the evidence to decide with: how many records used the phrase, when it was first and last recorded, the question it answered, and how many facilities and forms produced it. Rows are ranked by frequency, because the most common missing term is the most valuable dictionary work.

Actions on a dictionary-backlog row

1. Map to concept — search the dictionary and choose the concept. Every record in your tenant carrying that term is re-versioned to hold the concept and the original text, so the mapping stays reviewable, and the screen reports how many records were coded.
2. Create concept & map — when the dictionary genuinely lacks the entry. Name, code, class and data type are asked for; the entry is created through the ordinary concept-create path.
3. Dismiss — for typos and junk. A reason is required: an unexplained dismissal is indistinguishable from an item nobody has looked at. Nothing in the clinical record changes, and the phrase stays counted.

Select several rows to map near-duplicate spellings (HTN, hypertension, Hypertension) to one concept in a single action. The platform never merges spellings on its own — that is a human judgement, made here with the evidence in front of you.

Dictionary health counts sit at the top of the screen and on the dashboard: open unmapped terms, open Other, specify phrases, terms already mapped, and phrases dismissed. A dismissal is recorded rather than deleted, so "we have triaged 300 of 340" stays answerable. A rising open count is the signal this whole mechanism exists to produce.

If the platform refuses an action it says why — a term already mapped, a phrase already dismissed, an inactive target concept, or no records left carrying it. A refusal that says the records are not visible to you means the phrase came from patients you cannot read; hand the item to someone who can.

Tips & limitations

• Concepts are used widely, so changing one affects every form and record that references it. Prefer retiring an outdated concept over deleting it, to preserve history.
• A concept's data type determines how it behaves in forms — choose it carefully when creating.
• Numeric units come from UCUM only; do not invent synonyms when the picker has no match — ask for the missing code to be added under UCUM in the terminology registry.
• The triage queue is per tenant and shows no other tenant's terms. There is no platform-wide view.
• Mapping never hides the original text — the record keeps both, so the mapping can be reviewed.
• The dictionary-health counts are totals, not a trend over time; per-form filtering is not available.

---

When something looks wrong

What you see	What it usually is
A concept cannot be edited	It is Global-owned and shared with every tenant — create a local one instead
A local concept will not export to an outside system	It has no mapping to a standard code, so nothing says what it means externally
A search finds nothing	Concept search matches names in the active locale; try the code

For the causes common to every screen — a missing menu item, an empty list, a refusal — see Why a screen will not work.