Skip to main content

OMOP Vocabulary

Category: Data
Node id: omop-vocabulary

Standards: OMOP-CDM-5.4

Resolves OMOP concept_id=0 values using a 3-tier lookup: local crosswalk, in-memory cache, and optional remote vocabulary service

What it does​

  • 3-tier concept resolution: local crosswalk, in-memory cache, remote vocabulary service
  • Batch resolution of concept_id=0 values across all OMOP tables
  • Single concept lookup by code and vocabulary system
  • Concept ID validation against known vocabularies
  • Thread-safe in-memory LRU cache for repeated lookups
  • Support for ICD-10, SNOMED, LOINC, RxNorm vocabularies

Use cases​

  • Resolve unmapped concept IDs after FHIR-to-OMOP conversion
  • Look up OMOP standard concept IDs for medical codes
  • Validate concept IDs before loading into OMOP CDM
  • Enrich OMOP tables with proper vocabulary mappings

Runtime​

  • Performance tier: variable

Input ports​

NameTypeRequiredDescription
omop_tablesjsonNoOMOP table map with concept_id fields to resolve (for resolve operation)
datajsonNoAlternative input: OMOP table map
inputjsonNoAlternative input: OMOP table map

Output ports​

NameTypeRequiredDescription
resultjsonNoOperation result: resolved omop_tables + resolution_stats (resolve), or concept_id/concept_name/domain_id/vocabulary_id/found (lookup), or valid/concept_name/domain_id (validate)
successbooleanNoWhether the operation succeeded

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
OperationoperationenumYesresolveresolve, lookup, validateVocabulary operation
CodecodestringNoMedical code to look up (for lookup operation)
Vocabulary SystemsystemstringNoVocabulary system (e.g., ICD10CM, SNOMED, LOINC, RxNorm) for lookup
Concept IDconcept_idnumberNoOMOP concept_id to validate (for validate operation)

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Vocabulary Endpointvocabulary_endpointstringNoBase URL of the OMOP vocabulary service (tietai-cie10-es-service) for Tier-3 "Maps to" lookups; a failed call fails the node
Timeout (seconds)timeout_secondsnumberNo30min 1Timeout for each remote vocabulary lookup
Remote Concurrencyremote_concurrencynumberNo8min 1; max 32resolve: Tier-3 lookups run at once against vocabulary_endpoint (one per distinct vocabulary and code)
Remote Total Timeout (seconds)remote_total_timeout_secondsnumberNo300min 1; max 3600resolve: time budget for all Tier-3 lookups; running out of it fails the node

Errors​

CodeDescription
NO_OMOP_TABLESNo OMOP tables found in inputs
CODE_SYSTEM_REQUIREDCode and system required for lookup operation
CONCEPT_ID_REQUIREDNon-zero concept_id required for validate operation
REMOTE_LOOKUP_FAILEDvocabulary_endpoint was unreachable or answered with a non-200 status or a body that is not the OMOP vocabulary response; the node fails
UNSUPPORTED_OPERATIONOperation not recognized

Runtime notes​

  • Resolve operation mutates _concept_id fields in-place on the input OMOP tables and returns the updated tables
  • Three-tier lookup order: local crosswalk (ICD10CM/SNOMED/LOINC/RxNorm), in-memory cache, then remote service
  • Result shape varies by operation: resolve returns {omop_tables, resolution_stats}; lookup returns {concept_id, found, ...}; validate returns {valid, ...}
  • vocabulary_endpoint is optional; without it, only local crosswalk and cache lookups are available
  • Tier 3 calls GET {vocabulary_endpoint}/api/v1/omop/vocabulary/{vocabulary}/relationships/{code}?relationship_id=Maps to (tietai-cie10-es-service): exactly one target concept resolves; several are listed under ambiguous and left at 0; none stays unresolved
  • Tier-3 lookups run on a pool of remote_concurrency workers, one call per distinct (vocabulary, code), within remote_total_timeout_seconds; the ambiguous list is ordered by vocabulary then code
  • Any transport error, non-200 status or non-JSON answer from vocabulary_endpoint fails the node naming the URL and status — it is never counted as unresolved; the first failure cancels the lookups still running
  • validate with vocabulary_endpoint calls GET {vocabulary_endpoint}/api/v1/omop/concept/{concept_id}; 404 means invalid

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Something unclear? Send documentation feedback by email.