Aller au contenu principal

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.

Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.