Code Mapper
Category: Transform
Node id: code-mapper
Maturity: beta
Risk tier: C
Maps codes between systems (local → SNOMED CT, CIE-10-ES, LOINC; ICD-10-CM → SNOMED CT) against a crosswalk table in a saved SQL connector or the UMLS service. One target = mapped, several = ambiguous, none = unmapped; every mapping records its source. No guessing, no local fallback.
What it does
- Crosswalk backend: compiled, parameterised, read-only lookup in any saved SQL connector
- UMLS backend: code → CUI → target vocabulary through tietai-umls-service
- Exact status per code: mapped (one target), ambiguous (several, none chosen), unmapped (with reason)
- Mapping provenance on every result (crosswalk table + map_source column, UMLS CUI, identity)
- Batch input straight from connector rows (code_field / system_field), mapping rate and unmapped list
Use cases
- Harmonise a hospital's local diagnosis, procedure and lab codes to SNOMED CT, CIE-10-ES and LOINC through a terminology team's crosswalk
- Translate ICD-10-CM diagnosis codes to SNOMED CT through UMLS
- Verify that every target code of a crosswalk exists in the UMLS release
Runtime
- Performance tier:
variable - Effect:
read
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
code | text | No | Single code (translate, lookup, validate) |
system | text | No | Source system of the single code (overrides source_system) |
codes | json | No | Codes for a batch: strings, {code, system} objects, or connector rows read through code_field / system_field |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
status | text | No | Single translate: mapped, unmapped or ambiguous |
target_code | text | No | Single translate: the target code when mapped |
map_source | text | No | Single translate: where the mapping comes from (crosswalk table and its map_source, umls:<CUI>, identity) |
mappings | json | No | Single translate: every candidate (target_code, target_display, target_system, map_source, equivalence, cui) |
mapped | boolean | No | Single translate: status is mapped |
results | json | No | Batch: one result per distinct code, same shape as a single translate (lookup/validate: code, system, found, valid, display, cuis) |
unmapped | json | No | Batch: codes with no target, with the reason |
ambiguous | json | No | Batch: codes with several candidate targets (none chosen) |
total | number | No | Batch: distinct codes processed |
translated | number | No | Batch: codes mapped to exactly one target |
mapping_rate_pct | number | No | Batch: translated / total, percent, one decimal |
success | boolean | No | The backend answered for every code |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Operation | operation | enum | Yes | translate | translate, batch_translate, lookup, validate | translate / batch_translate map codes; lookup / validate check a code exists in its system (umls backend) |
| Backend | backend | enum | Yes | umls | crosswalk, umls | crosswalk: a mapping table in a saved SQL connector; umls: the UMLS service (UMLS_SERVICE_URL on the server) |
| Source System | source_system | string | No | System of the input codes when they do not carry one: the crosswalk's source_system value (e.g. LOCAL-DX) or a UMLS SAB / alias (ICD-10-CM, SNOMED-CT, LOINC) | ||
| Target System | target_system | string | No | System to map to: the crosswalk's target_system value (e.g. SNOMEDCT) or a UMLS SAB / alias (SNOMEDCT_US, LNC, ICD10CM) | ||
| Code Field | code_field | string | No | code | Field holding the code when codes are objects or connector rows | |
| System Field | system_field | string | No | system | Field holding each code's source system when codes are objects or rows (falls back to source_system) |
Crosswalk
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Crosswalk Connector | connector_id | string | No | Saved SQL connector (postgres, mssql, oracle, mysql, …) holding the crosswalk table; backend crosswalk only | ||
| Crosswalk Table | crosswalk_table | string | No | table or schema.table with one row per source code → target code | ||
| Source System Column | source_system_column | string | No | source_system | Column holding the source system | |
| Source Code Column | source_code_column | string | No | source_code | Column holding the source code | |
| Target System Column | target_system_column | string | No | target_system | Column holding the target system | |
| Target Code Column | target_code_column | string | No | target_code | Column holding the target code | |
| Target Display Column | target_display_column | string | No | Optional column with the target code's display | ||
| Map Source Column | map_source_column | string | No | Optional column naming who asserted each mapping; recorded in map_source | ||
| Equivalence Column | equivalence_column | string | No | Optional column with the mapping equivalence (equivalent, wider, narrower…) |
Errors
| Code | Description |
|---|---|
MISSING_CODE | Neither code nor codes is wired |
NO_BACKEND | The crosswalk connector cannot be resolved, or UMLS_SERVICE_URL is not set |
TERMINOLOGY_SERVICE_ERROR | The UMLS service or the crosswalk database returned an error |
TRUNCATED | A crosswalk chunk reached the row cap |
Runtime notes
- status is mapped only for exactly one distinct target code; several candidates are ambiguous and none is chosen; unmapped carries a reason
- A code whose source system equals target_system maps to itself with map_source identity
- Codes are matched exactly (no case folding, no prefix or parent-code fallback)
- UMLS mapping goes through shared concepts (CUIs): equivalence is "same UMLS concept", not a curated map; obsolete/suppressed atoms are ignored
- Without a reachable backend the node fails; there is no local fallback and no format-only validation
- The crosswalk query is read-only by construction and binds every value; a chunk reaching the row cap fails rather than returning a truncated answer
- Wire connector rows to codes and set code_field / system_field to their column names
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.