client.implementationGuides.implementationGuides.createVersion(name, request) -> ImplementationGuideVersionDetailclient.implementationGuides.implementationGuides.getVersion(name, version) -> ImplementationGuideVersionDetailclient.profiles.profiles.list() -> ProfileListResponseclient.lang2FhirBatch.list() -> JobListResponseclient.profiles.profiles.create(request) -> ProfileSummaryclient.lang2FhirBatch.create(request) -> BatchJobclient.profiles.profiles.get(id) -> ProfileGetResponseclient.lang2FhirBatch.uploadItem(jobId, request) -> UploadItemResponseclient.profiles.profiles.update(id, request) -> ProfileSummaryclient.lang2FhirBatch.finalize(jobId) -> BatchJobclient.profiles.profiles.delete(id)client.lang2FhirBatch.cancel(jobId) -> BatchJobclient.lang2FhirBatch.get(jobId) -> JobDetailResponseclient.lang2FhirBatch.getResults(jobId) -> ResultsPageResponseclient.lang2FhirBatch.getResult(jobId, itemId) -> Map<String, Object>client.profiles.profiles.list() -> ProfileListResponseclient.profiles.profiles.create(request) -> ProfileSummaryclient.profiles.profiles.get(id) -> ProfileGetResponseclient.profiles.profiles.update(id, request) -> ProfileSummaryclient.profiles.profiles.delete(id)client.profiles.versions.list(id) -> ProfileVersionListResponseclient.profiles.versions.create(id, request) -> ProfileSummaryclient.profiles.versions.get(id, version) -> ProfileGetResponseclient.profiles.versions.delete(id, version)
+ * In-flight calls are not cancelled or awaited, and any request issued after this method
+ * returns fails with a {@code RejectedExecutionException}. Options derived from this one via
+ * {@code Builder.from(...)} share the same dispatcher and connection pool, so closing either
+ * releases them for both. Calling this method more than once has no further effect.
+ */
+ public void close() {
+ if (!this.ownsHttpClient) {
+ return;
+ }
+ this.httpClient.dispatcher().executorService().shutdown();
+ this.httpClient.connectionPool().evictAll();
+ }
+
public Optional Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Extracts medical codes from natural language clinical text using phenocr. Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
* code system name and version are both required. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service. Resource support is intentionally limited to the OMOP tables returned by
- * this endpoint: Set Standards basis: FHIR R4 (v4.0.1) defines
+ * the accepted source elements and OMOP CDM
+ * v5.4 defines the
+ * output columns. The published Vulcan FHIR-to-OMOP IG
+ * v1.0.0 is an informative FHIR R5
+ * baseline; this endpoint documents and implements the equivalent R4
+ * source elements, rather than accepting R5-only fields. This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are Current resource coverage: Each resource's primary clinical coding is resolved to a standard OMOP
- * Patient demographics: Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric A standard OMOP A tables.
+ * vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
- *
- * Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
+ *
+ * gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ *
+ *
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
Resource support is intentionally limited to the OMOP tables returned by - * this endpoint:
+ * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, + * grouped by destination table intables.
+ * Set vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.
Standards basis: FHIR R4 (v4.0.1) defines + * the accepted source elements and OMOP CDM + * v5.4 defines the + * output columns. The published Vulcan FHIR-to-OMOP IG + * v1.0.0 is an informative FHIR R5 + * baseline; this endpoint documents and implements the equivalent R4 + * source elements, rather than accepting R5-only fields.
+ *This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.
Each resource's primary clinical coding is resolved to a standard OMOP
- * concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.
Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
Patient demographics:
+ *gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.
Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.
Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.
A standard OMOP concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.
A concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).
UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
+ * Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
Resource support is intentionally limited to the OMOP tables returned by - * this endpoint:
+ * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, + * grouped by destination table intables.
+ * Set vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.
Standards basis: FHIR R4 (v4.0.1) defines + * the accepted source elements and OMOP CDM + * v5.4 defines the + * output columns. The published Vulcan FHIR-to-OMOP IG + * v1.0.0 is an informative FHIR R5 + * baseline; this endpoint documents and implements the equivalent R4 + * source elements, rather than accepting R5-only fields.
+ *This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.
Each resource's primary clinical coding is resolved to a standard OMOP
- * concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.
Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
Patient demographics:
+ *gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.
Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.
Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.
A standard OMOP concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.
A concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).
UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
+ * Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
Resource support is intentionally limited to the OMOP tables returned by - * this endpoint:
+ * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, + * grouped by destination table intables.
+ * Set vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.
Standards basis: FHIR R4 (v4.0.1) defines + * the accepted source elements and OMOP CDM + * v5.4 defines the + * output columns. The published Vulcan FHIR-to-OMOP IG + * v1.0.0 is an informative FHIR R5 + * baseline; this endpoint documents and implements the equivalent R4 + * source elements, rather than accepting R5-only fields.
+ *This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.
Each resource's primary clinical coding is resolved to a standard OMOP
- * concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.
Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
Patient demographics:
+ *gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.
Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.
Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.
A standard OMOP concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.
A concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).
UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
+ * Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
Resource support is intentionally limited to the OMOP tables returned by - * this endpoint:
+ * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, + * grouped by destination table intables.
+ * Set vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.
Standards basis: FHIR R4 (v4.0.1) defines + * the accepted source elements and OMOP CDM + * v5.4 defines the + * output columns. The published Vulcan FHIR-to-OMOP IG + * v1.0.0 is an informative FHIR R5 + * baseline; this endpoint documents and implements the equivalent R4 + * source elements, rather than accepting R5-only fields.
+ *This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.
Each resource's primary clinical coding is resolved to a standard OMOP
- * concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.
Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
Patient demographics:
+ *gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.
Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.
Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.
A standard OMOP concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.
A concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).
UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
+ * Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
Resource support is intentionally limited to the OMOP tables returned by - * this endpoint:
+ * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, + * grouped by destination table intables.
+ * Set vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.
Standards basis: FHIR R4 (v4.0.1) defines + * the accepted source elements and OMOP CDM + * v5.4 defines the + * output columns. The published Vulcan FHIR-to-OMOP IG + * v1.0.0 is an informative FHIR R5 + * baseline; this endpoint documents and implements the equivalent R4 + * source elements, rather than accepting R5-only fields.
+ *This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.
Each resource's primary clinical coding is resolved to a standard OMOP
- * concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.
Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
Patient demographics:
+ *gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.
Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.
Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.
A standard OMOP concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.
A concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).
UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
+ * Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
Resource support is intentionally limited to the OMOP tables returned by - * this endpoint:
+ * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, + * grouped by destination table intables.
+ * Set vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.
Standards basis: FHIR R4 (v4.0.1) defines + * the accepted source elements and OMOP CDM + * v5.4 defines the + * output columns. The published Vulcan FHIR-to-OMOP IG + * v1.0.0 is an informative FHIR R5 + * baseline; this endpoint documents and implements the equivalent R4 + * source elements, rather than accepting R5-only fields.
+ *This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.
Each resource's primary clinical coding is resolved to a standard OMOP
- * concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.
Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
Patient demographics:
+ *gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.
Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.
Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.
A standard OMOP concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.
A concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).
UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
+ * Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
Resource support is intentionally limited to the OMOP tables returned by - * this endpoint:
+ * Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, + * grouped by destination table intables.
+ * Set vocab_version to select the OMOP vocabulary release used for coded
+ * concept resolution. If omitted or empty, the API uses its default
+ * release. The response's vocab_version, when present, identifies the
+ * release used. Specify a release explicitly when reproducibility matters.
Standards basis: FHIR R4 (v4.0.1) defines + * the accepted source elements and OMOP CDM + * v5.4 defines the + * output columns. The published Vulcan FHIR-to-OMOP IG + * v1.0.0 is an informative FHIR R5 + * baseline; this endpoint documents and implements the equivalent R4 + * source elements, rather than accepting R5-only fields.
+ *This response is a mapping result, not a complete CDM load pipeline.
+ * When a source cannot supply a field that CDM v5.4 requires, the row is
+ * still returned with that field unset; the value is not inferred. Common
+ * cases are year_of_birth without a usable birthDate,
+ * drug_exposure_end_date without an explicit end or single-event timing,
+ * and a required event date (such as condition_start_date,
+ * procedure_date, or death_date) whose source has no timing with at
+ * least day precision. Apply your own policy to such rows before loading
+ * them into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, the
+ * first address can produce location, and more than one supplied race
+ * produces observation race rows (see Patient demographics below)observation_period -> one request-local derived row per person,
+ * spanning the populated dates of that person's visit, clinical, and
+ * death rows; this is not enrollment or capture-completeness evidenceLocation -> location and care_siteOrganization -> care_site; its first address can produce locationHealthcareService -> care_sitePractitioner and PractitionerRole -> providerEncounter -> visit_occurrenceCondition -> condition_occurrenceProcedure -> procedure_occurrenceMedicationRequest, MedicationStatement, and
* MedicationAdministration -> drug_exposureImmunization -> drug_exposureObservation with a numeric valueQuantity, valueInteger, or
- * numeric-looking valueString (for example "<2") -> measurementObservation -> observationObservation -> measurement or observation. For coded
+ * Observations, the resolved OMOP concept domain selects the table; value
+ * form only breaks ties. For text-only Observations, numeric values route
+ * to measurement and nonnumeric values to observation.AllergyIntolerance -> observationMedication is supported only as reference data for medication
- * resources; it is not emitted as its own row because OMOP CDM has no
- * Medication table. Other reference/admin resources such as Practitioner,
- * Organization, Location, Coverage, and Claim, and clinical
- * workflow/document resources such as DiagnosticReport, ServiceRequest,
- * CarePlan, DocumentReference, Composition, Specimen, and
- * DeviceUseStatement, are currently accepted in a Bundle but are not
- * shaped into OMOP rows. Unsupported resource types are ignored rather than
- * listed under dropped; dropped is reserved for supported resource types
- * that were missing the subject/patient, code, or medication reference data
- * needed to produce a valid row.
Each resource's primary clinical coding is resolved to a standard OMOP
- * concept_id. Alongside the OMOP rows grouped by table (tables), the
- * response carries mappings (how each source coding resolved, linked back
- * to the row it produced), dropped (resources that could not be shaped
- * into a row), vocab_version (the OMOP vocabulary release codes were
- * resolved against), and a small summary of the resolution outcomes.
Medication is reference data for medication resources; it does not
+ * create its own row because OMOP CDM has no Medication table. Administrative
+ * linkages (provider, care site, and location) are best-effort and limited to
+ * references supplied in the request. Patient.managingOrganization is a
+ * record custodian, not a care-delivery site. Provider specialty is not
+ * mapped. Recorded Practitioner.gender is distinct from Person
+ * demographics: male and female resolve to validated OMOP Gender
+ * concepts in provider.gender_concept_id; other, unknown, and absent
+ * gender remain unmapped. Address.country is resolved to location.country_concept_id,
+ * and CMS Place of Service codings in Location.type are resolved to
+ * care_site.place_of_service_concept_id.
+ * A PractitionerRole that identifies one supplied Practitioner aliases
+ * that canonical provider: by a top-level structural reference, a
+ * parent-contained #id reference, or an exact identifier.system and
+ * identifier.value match against a top-level Practitioner. No remote
+ * identifier lookup is performed. When Reference.type is present it must
+ * be Practitioner; duplicate contained IDs and identifier matches are
+ * ambiguous. An explicit reference that is unresolved, ambiguous, or
+ * unsupported retains a role-fallback provider row and is returned in
+ * diagnostics. provider_role_contexts preserves role-specific
+ * specialty and care-site context that a canonical OMOP provider row cannot
+ * represent together.
Patient demographics:
+ *gender. Other extensions, including US
+ * Core sex and gender identity, are ignored.
+ * http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex
+ * (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-race-category)http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity
+ * (ombCategory from
+ * http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)gender_concept_id is sex at birth. A supplied birth sex always
+ * decides it: M and F are resolved; UNK, ASKU, OTH, a code
+ * outside the value set, conflicting values, and a birth sex without
+ * valueCode leave it 0, and Patient gender is not used.gender male or female is resolved
+ * under the OMOP convention that the supplied gender represents sex at
+ * birth; other and unknown keep concept 0.gender_source_value is the chosen source code (F for birth sex,
+ * female for Patient gender).UNK,
+ * ASKU) are ignored. One distinct standard race sets
+ * race_concept_id. More than one sets it to 1546847 (More than one
+ * race) and adds one observation row per race, with
+ * observation_concept_id 4013886 (Race), the race in
+ * value_as_concept_id, observation_type_concept_id 32817, the
+ * category code in value_source_value, and no
+ * observation_source_value or observation_date. A loading pipeline
+ * that requires observation_date must apply its own date policy.ethnicity_concept_id 0. Ethnicity is not derived from race, and
+ * no demographic is inferred from names, addresses, or other
+ * extensions.race_source_value and ethnicity_source_value list every supplied
+ * category and detailed code in source order, joined with |, or the
+ * extension text when no code is supplied. Detailed codes and text are
+ * not resolved.mappings entry whose note names its source and outcome. When a
+ * birth sex is supplied, Patient gender is reported unselected with
+ * the note FHIR administrative gender; not used, birth sex supplied.
+ * Conflicting values and a birth sex without valueCode are also
+ * returned in diagnostics with path extension:birthsex or
+ * extension:ethnicity. summary counts each demographic field once,
+ * as described under Summary.other and unknown to concepts, which stay 0
+ * here; more than one race follows the OHDSI THEMIS convention, also
+ * used by Vulcan, rather than the CDM 5.4 note that mixed races use
+ * 0; and Vulcan's suggested observation rows for multiple
+ * ethnicities are not produced.DiagnosticReport, ServiceRequest, CarePlan, DocumentReference,
+ * Composition, Specimen, DeviceUseStatement, Coverage, Claim, and
+ * other unsupported resource types are accepted in a Bundle but ignored: they
+ * create no row and no dropped entry. dropped is reserved for supported
+ * row-producing resources that cannot safely produce a positive OMOP row:
+ * required subject/patient, clinical code/text, or medication data may be
+ * unusable, or the resource may explicitly negate or fail the documented
+ * clinical-event eligibility policy. A single-Patient Bundle uses the sole
+ * Patient only when subject/patient is absent. An explicit subject/patient
+ * reference that is unresolved, ambiguous, or unsupported drops the clinical
+ * resource in every request scope.
Eligibility distinguishes clinical validity, performed/taken evidence, and
+ * administrative workflow state. Checks run before terminology resolution;
+ * entered-in-error and explicitly non-performed events never produce a positive
+ * clinical-event row, and an unrecognized required status fails closed. Condition
+ * requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a
+ * diagnosis-role mapping. Procedures accept completed or stopped events.
+ * Medication requests are prescription evidence only: doNotPerform, drafts,
+ * cancellations, and non-authorizing intents are dropped. Medication statements
+ * accept active, completed, stopped, or on-hold reported use; administrations
+ * accept completed, in-progress, on-hold, or stopped events. An on-hold
+ * administration also needs an effectiveDateTime or effectivePeriod.start
+ * that supplies start evidence; a valid partial date remains an undated row.
+ * An on-hold administration is started evidence that is temporarily paused and
+ * expected to continue. Immunizations require completed
+ * status. Observations require final,
+ * amended, or corrected status; registered,
+ * preliminary, cancelled, entered-in-error, unknown, and missing statuses are
+ * dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
+ * verificationStatus as a reported allergy, but drops refuted,
+ * entered-in-error, and unreadable supplied verification statuses. Encounter
+ * accepts arrived, triaged, in-progress, onleave, or finished status, but drops
+ * planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible
+ * encounter without Period.end remains a partial visit; no end date is invented.
Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric value[x] forms establish the preferred
+ * target only when the code is valid for both tables. A text-only
+ * Observation has no resolver target, so numeric values route to
+ * measurement and nonnumeric values to observation. Numeric values
+ * populate value_as_number in the selected row; other non-coded values
+ * populate value_as_string for an observation or value_source_value
+ * for a measurement. Coded valueCodeableConcept values are resolved
+ * against the selected row's value_as_concept_id and use the selected
+ * bare code in value_source_value, leaving an observation's
+ * value_as_string empty; unmapped or target-invalid coded values remain
+ * 0.
+ * Other unsupported value[x] forms and Observation components do not
+ * populate separate converted values. A
+ * numeric comparator (<, <=, >, >=) is represented only by a
+ * measurement's operator_concept_id; units remain source text and have
+ * unit_concept_id of 0.
A standard OMOP concept_id is selected for each eligible primary clinical coding
+ * after considering all of the resource's supplied codings. An unambiguous
+ * coded medication route is resolved independently to
+ * drug_exposure.route_concept_id. Alongside the OMOP rows grouped by
+ * table (tables), the response carries mappings (an entry for every
+ * supported source coding from a resource that shaped a row, linked back to
+ * that row; some, such
+ * as demographic null flavors, are reported without being resolved),
+ * provider_role_contexts (source role details linked to provider rows),
+ * dropped (resources that could not be shaped into a row),
+ * diagnostics (explicit references that could not safely create a link,
+ * and conflicting or unsupported Patient demographic extensions),
+ * vocab_version (the OMOP vocabulary release codes were resolved
+ * against), and a small summary of the resolution outcomes.
A concept_id of 0 is reported, not omitted (OMOP "no matching
* concept" semantics): it covers both a coding with no standard match
* (UNMAPPED) and an unverified suggestion for a text-only resource
- * (UNCHECKED). Only the primary clinical coding is resolved, so
- * gender/race/ethnicity/visit/value/unit concept_ids are
- * always 0; the one populated non-resolved concept is measurement
- * operator_concept_id, set from a value comparator (<, <=, >, >=)
- * rather than the resolver. Each *_source_value carries the verbatim FHIR
- * coding (system#code), and *_type_concept_id is set to 32817 (EHR).
UNCHECKED). Visit and unit concept fields currently remain 0;
+ * Person demographics and Provider recorded gender follow the policies
+ * above. Coded Observation values may populate value_as_concept_id.
+ * Concepts set by a fixed convention rather than terminology resolution
+ * are measurement operator_concept_id, set from a value comparator (<,
+ * <=, >, >=), and the multiple-race concepts described above. Clinical
+ * *_source_value fields contain the selected FHIR code (or source text
+ * for text-only resources).
+ * The corresponding selected mappings entry preserves the coding system
+ * and full source-coding provenance.
+ * Known OID-form coding systems are accepted as either FHIR OID URNs (for
+ * example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and
+ * are normalized to their canonical system URLs before terminology
+ * resolution. mappings[].source_system reports that canonical URL, so the
+ * OID and URL forms produce the same mapping. An unknown OID is not
+ * rewritten and may be UNMAPPED.
+ * Other *_source_value fields preserve row-specific raw source values,
+ * such as resource identifiers, names, units, or status codes.
+ * MedicationRequest uses 32838 (EHR prescription) for
+ * drug_type_concept_id; other current resources use 32817 (EHR). This
+ * is a coarse provenance policy: it does not infer patient-reported,
+ * medication-history, or other more-specific type concepts from FHIR
+ * status fields.
+ * Dates and datetimes:
+ **_date is the calendar date (YYYY-MM-DD) of a source value with
+ * at least day precision. A *_datetime is set only when that value
+ * has a time of day, as local time without a UTC offset
+ * (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when
+ * supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
+ * A datetime without a timezone is read as local time.2024 or 2024-03) leaves both columns unset. It
+ * still counts as that source's value, so later sources in the list
+ * below are not used.onsetString), Age and Range forms, and
+ * values that are not dates are ignored, so a later source in the list
+ * is used if there is one.Timing sources, in priority order where several are listed:
+ *Patient: birthDate sets year_of_birth, month_of_birth, and
+ * day_of_birth from the parts it supplies; birth_datetime is not
+ * set. deceasedDateTime sets the death dates.Practitioner: birthDate sets the provider's year_of_birth.Encounter: period.start and period.end.Condition: start from onsetDateTime or onsetPeriod.start, then
+ * recordedDate (when the condition was recorded, not when it began);
+ * end from abatementDateTime or abatementPeriod.end.Procedure: start from performedDateTime or
+ * performedPeriod.start; end from performedPeriod.end only.Observation: effectiveDateTime, effectivePeriod.start, or
+ * effectiveInstant.AllergyIntolerance: recordedDate, then onsetDateTime or
+ * onsetPeriod.start.MedicationStatement: start from effectiveDateTime or
+ * effectivePeriod.start; end and verbatim_end_date from
+ * effectivePeriod.end. dateAsserted records when the statement was
+ * made and is not used.MedicationAdministration: an effectiveDateTime is a single event
+ * that sets both start and end; an effectivePeriod sets the start
+ * and, when present, the end and verbatim_end_date.Immunization: occurrenceDateTime is a single event that sets both
+ * start and end; expirationDate is not used.MedicationRequest: authoredOn, the order date, sets the start; it
+ * is not evidence of administration. No end is set, and the validity
+ * period is not used as an exposure duration.birth_datetime is not set from
+ * birthDate, Condition also reads onsetPeriod.start, and
+ * AllergyIntolerance falls back to its onset when recordedDate is
+ * missing.Medication details:
+ *MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets
+ * refills and a whole-day expectedSupplyDuration sets days_supply.sig.Immunization.route are target-validated in
+ * the OMOP Route domain. Conflicting routes are left unset; route
+ * codings shared by every dosage instruction identify the same route.Immunization.lotNumber is preserved in lot_number.Medication codes are resolved whether they appear inline
* (medicationCodeableConcept) or via a medicationReference to a contained,
* relative (Type/id), or bundle-entry (urn:uuid) Medication resource.
+ * A reference that resolves to another resource type is dropped even when it
+ * supplies display text; an unresolved or display-only reference may use
+ * its display as text-only medication input.
* Resources that cannot be shaped into a row — a medication with no usable
- * code, resolvable reference, or display, or any clinical resource whose
- * subject/patient reference cannot be tied to a person — are reported under
- * dropped rather than emitted as blank rows. The
- * bundle must contain at least one Patient resource.
dropped rather than emitted as blank
+ * rows. The Bundle must contain at least one Patient resource.
+ * Structural references resolve only to top-level resources supplied in the
+ * request, by Type/id or an exactly matching Bundle fullUrl (including
+ * urn:uuid). Contained references are supported for medication code lookup
+ * and PractitionerRole.practitioner enrichment; the latter also supports
+ * exact request-local identifier matching without a remote lookup. Every
+ * nonzero structural foreign key targets a row in the same response. Missing
+ * optional links remain unset without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains unset and is returned in diagnostics
+ * with its source path and outcome.
All row IDs start at 1 for each request and are not stable or global.
+ * For clinical conversion rows whose resource supplies an id, mappings
+ * associates each row with that source FHIR resource ID. A person row
+ * retains the Patient ID or its first identifier value in
+ * person_source_value, when present; other reference and derived rows do
+ * not uniformly carry a FHIR resource ID. Input resources without those
+ * source identifiers cannot be correlated across responses from the
+ * returned rows alone. Consumers combining responses need to establish
+ * their own stable keys and remap every primary and foreign key together.
vocab_version, when present, identifies the release used.
+ */
+ @JsonProperty("vocab_version")
+ public OptionalOMOP vocabulary release to use for coded concept resolution. If
+ * omitted or empty, the API uses its default release. Specify a
+ * release explicitly when reproducibility matters. The response's
+ * vocab_version, when present, identifies the release used.
FHIR resources (single resource or Bundle). Must contain at least one * Patient resource. Supported row-producing resources are Patient, - * Encounter, Condition, Procedure, MedicationRequest, + * Location, Organization, HealthcareService, Practitioner, + * PractitionerRole, Encounter, Condition, Procedure, MedicationRequest, * MedicationStatement, MedicationAdministration, Immunization, * Observation, and AllergyIntolerance. Standalone Medication resources * are consumed by medication references rather than mapped to their own - * table. Other resource types are accepted but ignored.
+ * table. Unsupported resource types are accepted in a Bundle but ignored. */ @JsonSetter(value = "fhir_resources", nulls = Nulls.SKIP) public Builder fhirResources(MapDate from Condition.onsetDateTime or onsetPeriod.start, otherwise Condition.recordedDate.
+ */ @JsonSetter(value = "condition_start_date", nulls = Nulls.SKIP) public Builder conditionStartDate(OptionalDate from Condition.abatementDateTime or abatementPeriod.end.
+ */ @JsonSetter(value = "condition_end_date", nulls = Nulls.SKIP) public Builder conditionEndDate(Optionalobservation race row when the person has more than one race.
*/
@JsonProperty("mappings")
public Optionalreason codes;
+ * other shaping failures retain an explanatory reason string.
*/
@JsonProperty("dropped")
public OptionalPractitionerRole provider identity, or explicit
+ * subject/patient references that caused a clinical row to be dropped.
+ * Missing optional references are normal and do not produce a diagnostic.
+ * References resolve only against resources supplied in this request.
+ * Outcomes distinguish unresolved, ambiguous, conflicting, and unsupported
+ * references. Patient demographic extensions that conflict, or a birth
+ * sex without valueCode, are also reported here; their path is
+ * extension:birthsex or extension:ethnicity and they have no
+ * reference.
+ */
+ @JsonProperty("diagnostics")
+ public OptionalOne entry per source coding (or one entry for a text-only resource with no coding), describing how it resolved and linking back to the row it produced.
+ *One entry per supported source coding from a resource that shaped a row (or one entry for a text-only primary resource with no coding), describing how it resolved and linking back to the row it produced. A coded route or Observation valueCodeableConcept is a separate entry linked to its medication, vaccine, or observation row. A Patient demographic code links to its person row, or to its observation race row when the person has more than one race.
Additive FHIR provenance for every supplied PractitionerRole. Each + * context identifies the canonical or role-fallback provider row and + * preserves source role facts that OMOP's singular provider columns + * cannot represent together.
+ */ + @JsonSetter(value = "provider_role_contexts", nulls = Nulls.SKIP) + public Builder providerRoleContexts(OptionalSupported resource instances that could not be shaped into an OMOP - * row because required subject/patient, code, or medication reference - * data was missing. Unsupported resource types are ignored and do not - * appear here.
+ * row because the subject/patient, clinical code or text, or medication + * data was missing or unusable, including an explicit subject/patient + * reference that was unresolved, ambiguous, or unsupported, or because + * their clinical-event eligibility status excluded them. A resource that + * lacks only a date or another CDM-required field is returned as a row + * instead. Unsupported resource types are ignored and do not appear here. + * Eligibility exclusions use stable, resource-specificreason codes;
+ * other shaping failures retain an explanatory reason string.
*/
@JsonSetter(value = "dropped", nulls = Nulls.SKIP)
public Builder dropped(OptionalThe OMOP vocabulary release the clinical codes were resolved against - * (e.g. "v20240229"), for reproducibility. Present when at least one - * coded concept was resolved.
+ *Explanations for explicit references that could not safely produce
+ * an OMOP link or canonicalize a PractitionerRole provider identity, or explicit
+ * subject/patient references that caused a clinical row to be dropped.
+ * Missing optional references are normal and do not produce a diagnostic.
+ * References resolve only against resources supplied in this request.
+ * Outcomes distinguish unresolved, ambiguous, conflicting, and unsupported
+ * references. Patient demographic extensions that conflict, or a birth
+ * sex without valueCode, are also reported here; their path is
+ * extension:birthsex or extension:ethnicity and they have no
+ * reference.
The OMOP vocabulary release used for coded concept resolution + * (for example, "v20260227"), for reproducibility. Omitted when no + * vocabulary resolution was performed.
*/ @JsonSetter(value = "vocab_version", nulls = Nulls.SKIP) public Builder vocabVersion(OptionalDate from Patient.deceasedDateTime; unset for a boolean-only or partial value.
+ */ @JsonSetter(value = "death_date", nulls = Nulls.SKIP) public Builder deathDate(Optional0 for an unmapped coded route, omitted for absent, text-only, or conflicting routes.
+ */
+ @JsonProperty("route_concept_id")
+ public OptionalDate from the resource's timing source, such as effective[x], occurrenceDateTime, or MedicationRequest.authoredOn.
+ */ @JsonSetter(value = "drug_exposure_start_date", nulls = Nulls.SKIP) public Builder drugExposureStartDate(OptionalDate from an explicit FHIR Period end, or the same day as the start for a single-event administration or immunization. Unset when the source supplies neither.
+ */ @JsonSetter(value = "drug_exposure_end_date", nulls = Nulls.SKIP) public Builder drugExposureEndDate(OptionalDate from an explicit FHIR Period.end only; inferred same-day ends are not verbatim source values.
+ */ + @JsonSetter(value = "verbatim_end_date", nulls = Nulls.SKIP) + public Builder verbatimEndDate(OptionalDirect MedicationRequest.dispenseRequest.numberOfRepeatsAllowed value, when supplied.
+ */ + @JsonSetter(value = "refills", nulls = Nulls.SKIP) + public Builder refills(OptionalDirect positive whole-day MedicationRequest.dispenseRequest.expectedSupplyDuration; no dose or quantity conversion is applied.
+ */ + @JsonSetter(value = "days_supply", nulls = Nulls.SKIP) + public Builder daysSupply(OptionalNewline-joined non-empty FHIR Dosage.text instructions in source order.
+ */ @JsonSetter(value = "sig", nulls = Nulls.SKIP) public Builder sig(OptionalTarget-valid OMOP Route concept for an unambiguous coded FHIR route; 0 for an unmapped coded route, omitted for absent, text-only, or conflicting routes.
Direct FHIR R4 Immunization.lotNumber value.
+ */ + @JsonSetter(value = "lot_number", nulls = Nulls.SKIP) + public Builder lotNumber(OptionalSelected source coding or text for an unambiguous FHIR route.
+ */ + @JsonSetter(value = "route_source_value", nulls = Nulls.SKIP) + public Builder routeSourceValue(Optionalcondition_concept_id, route_concept_id, or race_concept_id.
+ */
+ @JsonProperty("omop_field")
+ public Optionalconcept_id stays 0), or
- * UNMAPPED (no standard concept found).
+ * standard code was suggested for a text-only resource but not verified
+ * against the OMOP vocabulary, so concept_id stays 0), or UNMAPPED
+ * (no standard concept found).
*/
@JsonProperty("mapping_status")
- public Optional*_source_value field. Always present; false for alternate codings and text-only rows. For a Patient demographic, it marks the code that determined the PERSON field or race observation row, even when that code has no concept; it is false for race and ethnicity null flavors, conflicting values, a Patient gender overridden by birth sex, and race categories that did not determine the field.
+ */
+ @JsonProperty("selected")
+ public boolean getSelected() {
+ return selected;
+ }
+
+ /**
+ * @return Additional context for the entry. A coded route is noted as
+ * FHIR route. Patient demographic entries name their source and, when
+ * not applied, why:
+ * US Core birth sex; US Core birth sex; null flavor;
+ * US Core birth sex; outside value set;
+ * US Core birth sex; conflicting valuesFHIR administrative gender; assumed sex at birth;
+ * FHIR administrative gender; not a sex-at-birth value;
+ * FHIR administrative gender; not used, birth sex suppliedUS Core race OMB category;
+ * US Core race OMB category; more than one race (linked to its
+ * observation race row); US Core race; null flavorUS Core ethnicity OMB category;
+ * US Core ethnicity OMB category; conflicting categories;
+ * US Core ethnicity; null flavorWhether this source coding was selected for the linked row's *_source_value field. Always present; false for alternate codings and text-only rows. For a Patient demographic, it marks the code that determined the PERSON field or race observation row, even when that code has no concept; it is false for race and ethnicity null flavors, conflicting values, a Patient gender overridden by birth sex, and race categories that did not determine the field.
The id of the OMOP row this coding produced (e.g. condition_occurrence_id),
+ * within omop_table. A resource with multiple codings yields one entry
+ * per coding, all sharing this id.
The OMOP concept-ID field populated from this source coding, such as condition_concept_id, route_concept_id, or race_concept_id.
The standard concept's own code: the source code itself for an + * ALREADY_STANDARD row, the standard concept's code for a MAPPED row, + * or the suggested code for an UNCHECKED row. Omitted for UNMAPPED + * rows.
+ */ + _FinalStage targetCode(OptionalALREADY_STANDARD (source coding is already a standard OMOP concept), + * MAPPED (source coding was mapped to a standard concept), UNCHECKED (a + * standard code was suggested for a text-only resource but not verified + * against the OMOP vocabulary, so