Zum Hauptinhalt springen

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​

NameTypeRequiredDescription
codetextNoSingle code (translate, lookup, validate)
systemtextNoSource system of the single code (overrides source_system)
codesjsonNoCodes for a batch: strings, {code, system} objects, or connector rows read through code_field / system_field

Output ports​

NameTypeRequiredDescription
statustextNoSingle translate: mapped, unmapped or ambiguous
target_codetextNoSingle translate: the target code when mapped
map_sourcetextNoSingle translate: where the mapping comes from (crosswalk table and its map_source, umls:<CUI>, identity)
mappingsjsonNoSingle translate: every candidate (target_code, target_display, target_system, map_source, equivalence, cui)
mappedbooleanNoSingle translate: status is mapped
resultsjsonNoBatch: one result per distinct code, same shape as a single translate (lookup/validate: code, system, found, valid, display, cuis)
unmappedjsonNoBatch: codes with no target, with the reason
ambiguousjsonNoBatch: codes with several candidate targets (none chosen)
totalnumberNoBatch: distinct codes processed
translatednumberNoBatch: codes mapped to exactly one target
mapping_rate_pctnumberNoBatch: translated / total, percent, one decimal
successbooleanNoThe backend answered for every code

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
OperationoperationenumYestranslatetranslate, batch_translate, lookup, validatetranslate / batch_translate map codes; lookup / validate check a code exists in its system (umls backend)
BackendbackendenumYesumlscrosswalk, umlscrosswalk: a mapping table in a saved SQL connector; umls: the UMLS service (UMLS_SERVICE_URL on the server)
Source Systemsource_systemstringNoSystem 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 Systemtarget_systemstringNoSystem to map to: the crosswalk's target_system value (e.g. SNOMEDCT) or a UMLS SAB / alias (SNOMEDCT_US, LNC, ICD10CM)
Code Fieldcode_fieldstringNocodeField holding the code when codes are objects or connector rows
System Fieldsystem_fieldstringNosystemField holding each code's source system when codes are objects or rows (falls back to source_system)

Crosswalk​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Crosswalk Connectorconnector_idstringNoSaved SQL connector (postgres, mssql, oracle, mysql, …) holding the crosswalk table; backend crosswalk only
Crosswalk Tablecrosswalk_tablestringNotable or schema.table with one row per source code → target code
Source System Columnsource_system_columnstringNosource_systemColumn holding the source system
Source Code Columnsource_code_columnstringNosource_codeColumn holding the source code
Target System Columntarget_system_columnstringNotarget_systemColumn holding the target system
Target Code Columntarget_code_columnstringNotarget_codeColumn holding the target code
Target Display Columntarget_display_columnstringNoOptional column with the target code's display
Map Source Columnmap_source_columnstringNoOptional column naming who asserted each mapping; recorded in map_source
Equivalence Columnequivalence_columnstringNoOptional column with the mapping equivalence (equivalent, wider, narrower…)

Errors​

CodeDescription
MISSING_CODENeither code nor codes is wired
NO_BACKENDThe crosswalk connector cannot be resolved, or UMLS_SERVICE_URL is not set
TERMINOLOGY_SERVICE_ERRORThe UMLS service or the crosswalk database returned an error
TRUNCATEDA 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.

Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..