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.lang2FhirBatch.cancel(jobId) -> BatchJobclient.profiles.profiles.delete(id)client.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 Resource support is intentionally limited to the OMOP tables returned by
- * this endpoint: 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires Current resource coverage: Each resource's primary clinical coding is resolved to a standard OMOP
- * Coded Observation routing is selected from the resolved OMOP concept
+ * domain. Numeric and nonnumeric A standard OMOP A tables.
+ * drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
- *
- * Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
+ * 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.
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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.
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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
+ * Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
+ * 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.
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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.
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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
+ * Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
+ * 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.
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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.
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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
+ * Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
+ * 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.
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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.
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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
+ * Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
+ * 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.
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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.
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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
+ * Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
+ * 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.
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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.
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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
+ * Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
+ * 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 source-faithful mapping result, not a complete CDM
+ * load pipeline. CDM v5.4 requires drug_exposure_end_date; when a FHIR
+ * medication source supplies neither an explicit end nor a safe
+ * instantaneous-event interpretation, the response leaves the end absent
+ * rather than inferring it from a validity period, quantity, dose, or
+ * refill count. A downstream ETL must apply its own documented duration
+ * policy before loading such rows into a strictly conformant CDM instance.
Current resource coverage:
*Patient -> personPatient -> person; deceased[x] can also produce death, and the
+ * first address can produce locationobservation_period -> one request-local derived row per person with
+ * valid dated visit, clinical, or death rows, spanning those dates; 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. 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 always produces its role-specific provider row;
+ * PractitionerRole.practitioner enriches that row only when it identifies
+ * one supplied Practitioner: 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 leaves the practitioner identity unset and is returned in
+ * diagnostics. The response retains a provider row for each
+ * PractitionerRole without mutating direct Practitioner rows, preserving
+ * role-specific specialty and care-site context.
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 could not be shaped because the subject/patient,
+ * clinical code/text, or medication data was not usable. 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.
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 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 that is sent to resolution, linked back to the
+ * row it produced),
+ * 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),
+ * 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). Demographic, visit, and unit concept fields currently
+ * remain 0. Coded Observation values may populate value_as_concept_id;
+ * measurement operator_concept_id is set from a value comparator
+ * (<, <=, >, >=) rather than terminology resolution. 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.
+ * Direct FHIR R4 timing and medication detail policy:
+ *MedicationStatement.effectiveDateTime and effectivePeriod.start
+ * populate drug start fields; effectivePeriod.end also populates drug
+ * end date/datetime and verbatim_end_date. dateAsserted is recorded
+ * time, not exposure timing.MedicationAdministration.effectiveDateTime is a single-event,
+ * same-day exposure; an explicit effectivePeriod.end populates
+ * source-supported end and verbatim-end fields. A start-only
+ * administration period keeps its start and leaves the end absent.
+ * Immunization.occurrenceDateTime is also a single-event, same-day
+ * exposure.MedicationRequest.authoredOn is an order-date start fallback, not
+ * proof of administration. Direct allowed repeats, whole-day expected
+ * supply, and all non-empty dosage text are preserved; its validity
+ * period is not exposure duration.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; its expirationDate is not an
+ * exposure end.Condition.abatementDateTime and abatementPeriod.end populate
+ * condition_end_date. Core CDM v5.4 has no procedure-end column.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 null without a diagnostic; an explicit optional
+ * reference that is unresolved, ambiguous, conflicting with the row's
+ * person, or unsupported remains null 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.
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 FHIR R4 Condition.abatementDateTime or abatementPeriod.end when supplied.
+ */ @JsonSetter(value = "condition_end_date", nulls = Nulls.SKIP) public Builder conditionEndDate(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.
+ */
+ @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 (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.
*/ @JsonSetter(value = "mappings", nulls = Nulls.SKIP) public Builder mappings(OptionalAdditive 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 required clinical data was missing, or an explicit + * subject/patient reference was unresolved, ambiguous, or unsupported. + * Unsupported resource types are ignored and do not appear here. */ @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.
The OMOP vocabulary release returned for coded concept resolution + * (for example, "v20240229"), for reproducibility. It is generally + * absent for requests containing only text-only resources.
*/ @JsonSetter(value = "vocab_version", nulls = Nulls.SKIP) public Builder vocabVersion(Optional0 for an unmapped coded route, omitted for absent, text-only, or conflicting routes.
+ */
+ @JsonProperty("route_concept_id")
+ public OptionalDate from the resource-specific direct timing source, such as effective[x], occurrenceDateTime, or MedicationRequest.authoredOn.
+ */ @JsonSetter(value = "drug_exposure_start_date", nulls = Nulls.SKIP) public Builder drugExposureStartDate(OptionalDate-time precision from the resource-specific direct timing source when supplied.
+ */ @JsonSetter(value = "drug_exposure_start_datetime", nulls = Nulls.SKIP) public Builder drugExposureStartDatetime(OptionalExplicit FHIR Period end, or same-day inferred end for a structured instantaneous administration or immunization. Omitted when no source-supported end is available.
+ */ @JsonSetter(value = "drug_exposure_end_date", nulls = Nulls.SKIP) public Builder drugExposureEndDate(OptionalDate-time precision from an explicit FHIR Period end or a structured instantaneous administration or immunization.
+ */ + @JsonSetter(value = "drug_exposure_end_datetime", nulls = Nulls.SKIP) + public Builder drugExposureEndDatetime(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 or route_concept_id.
+ */
+ @JsonProperty("omop_field")
+ public Optional*_source_value field. Always present; false for alternate codings and text-only rows.
+ */
+ @JsonProperty("selected")
+ public boolean getSelected() {
+ return selected;
+ }
+
@JsonProperty("note")
public OptionalWhether this source coding was selected for the linked clinical *_source_value field. Always present; false for alternate codings and text-only rows.
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 or route_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 — e.g. for a text-only resource — but not
+ * verified against the OMOP vocabulary, so concept_id stays 0), or
+ * UNMAPPED (no standard concept found).
Whether this source coding was selected for the linked clinical *_source_value field. Always present; false for alternate codings and text-only rows.
ALREADY_STANDARD (source coding is already a standard OMOP concept),
+ * MAPPED (source coding was mapped to a standard concept), UNCHECKED (a
+ * standard code was suggested — e.g. for a text-only resource — but not
+ * verified against the OMOP vocabulary, so concept_id stays 0), or
+ * UNMAPPED (no standard concept found).
ALREADY_STANDARD (source coding is already a standard OMOP concept),
+ * MAPPED (source coding was mapped to a standard concept), UNCHECKED (a
+ * standard code was suggested — e.g. for a text-only resource — but not
+ * verified against the OMOP vocabulary, so concept_id stays 0), or
+ * UNMAPPED (no standard concept found).
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 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.
+ * @return Reference to {@code this} so that method calls can be chained together. */ - @JsonSetter(value = "omop_id", nulls = Nulls.SKIP) - public Builder omopId(OptionalThe 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.
+ */ + @java.lang.Override + @JsonSetter(value = "target_code", nulls = Nulls.SKIP) + public _FinalStage targetCode(Optional