# Cognito Field Mapping — MIGRATION SOURCE ONLY
# Maps Cognito form field keys to ACCESS Core DB tables and columns.
# Cognito is the legacy intake platform. Healthie Forms replace Cognito as the
# unified patient-facing and clinical workflow platform.
# See Cognito_to_Healthie_Form_Mapping.yaml for the Healthie migration spec.
# 'type' indicates how the value should be transformed before storage.

mapping_version: "2.1"
form_version: "cognito_v1"
last_updated: "2026-07-23"
status: "migration_source"
notes: |
  v2.1 changes:
  - Marked as migration-source artifact. Cognito is not the long-term platform.
  - Healthie-first model: all new intake occurs in Healthie. Cognito data is migrated to Core DB.
  - See Cognito_to_Healthie_Form_Mapping.yaml for complete Healthie form rebuild spec.
  v2.0 changes:
  - Identity fields now map to intake_records (two-stage design) instead of beneficiaries directly
  - Beneficiaries table is populated only after full enrollment workflow (eligibility + consent + alignment)
  - Added webhook fields (webhook_signature_valid, processing_status)

  WARNING: Cognito webhook payload has not been observed.
  - The sample payload this mapping is based on (`sample_data/MetaFlowEnrollmentAssessment.json`)
    is from an XLSX export, NOT a webhook or API response. The XLSX export format may differ
    significantly from the actual webhook payload.
  - Cognito has a form schema endpoint (`GET /forms/{formId}/schema`) per their OpenAPI spec,
    but the response is documented only as `"type": "object"` — zero properties, zero examples.
    Effectively a black box until tested against a live form.
  - All 70+ field mappings below are based on the XLSX export sample. Field names (e.g.,
    `NameEntryNumber_First`), value wrapping (`{"0": "value"}`), choice serialization, and
    timestamp format have not been validated against a real webhook.
  - Explicit field-to-column mapping is required regardless of platform since DB columns
    are hardcoded. The difference is that Cognito's field keys and webhook format are undocumented,
    while Healthie's `custom_module.id` values are stable and queryable.
  - See docs/architecture/Healthie_Forms_Vs_Cognito.md for migration option.

# ============================================================
# RAW PAYLOAD STORAGE (everything goes here first, untransformed)
# ============================================================

raw_storage:
  table: raw_ingestion_records
  columns:
    source_system:
      value: "cognito"  # constant
    source_record_id:
      field: "MetaFlowEnrollmentAssessment_Id"
      transform: "stringify"
    raw_payload:
      field: "*"  # entire JSON payload
    form_version:
      value: "cognito_v1"  # constant, update per form revision

# ============================================================
# INTAKE RECORDS (pre-enrollment identity, PHI)
# Two-stage design: Cognito → intake_records first.
# beneficiaries table populated only after eligibility + consent + alignment.
# ============================================================

intake_records:
  table: intake_records
  columns:
    external_form_id:
      field: "MetaFlowEnrollmentAssessment_Id"
      transform: "stringify"
    first_name:
      field: "NameEntryNumber_First"
      type: text
      encrypt: true
    middle_name:
      field: "NameEntryNumber_Middle"
      type: text
      encrypt: true
      nullable: true
      transform: "stringify"  # Cognito returns 1 for "no middle"
    last_name:
      field: "NameEntryNumber_Last"
      type: text
      encrypt: true
    dob:
      field: "DateOfBirth"
      type: date
      transform: "timestamp_ms_to_date"  # e.g. 1593561600000 -> "2020-06-30"
    sex:
      field: "SexOnMedicalOrLabRecords"
      type: text
      enum: ["male", "female", "other", "unknown"]
      transform: "lowercase"  # Cognito returns "Male"/"Female", schema expects lowercase

  intake_identifiers:
    table: intake_identifiers
    linked_table: intake_records
    entries:
      - identifier_type: email
        field: "Email"
        encrypt: true
        is_primary: true
      - identifier_type: phone
        field: "Phone"
        encrypt: true
      - identifier_type: address
        field: "Address_Line1"
        encrypt: true
        is_primary: true
        metadata:
          line2: "Address_Line2"
          city: "Address_City"
          state: "Address_State"
          postal_code: "Address_PostalCode"

# ============================================================
# SAFETY SCREENING
# ============================================================

safety_screening:
  table: safety_screening
  columns:
    safety_stop_applies:
      field: "SafetyScreening2_DoAnyOfTheAboveCurrentConditionsApplyToYou"
      type: boolean
      transform: "yes_no_to_boolean"
    free_text:
      field: "FinalReviewSubmission_IsThereAnythingElseYouWouldLikeTheMetaFlowReviewTeamToKnow"
      type: text
      nullable: true

  # Derived: exclusion flags based on medical conditions + safety stop
  derived_columns:
    exclusion_flags:
      logic: "evaluate_exclusion_rules"  # application-level logic
      depends_on:
        - "MedicalHistoryMedicationSafetyReview_HaveYouEverBeenDiagnosedByAPhysicianWithAnyOfTheFollowingConditions"
        - "MedicalHistoryMedicationSafetyReview_AreYouCurrentlyUsingAnyOfTheFollowingMedicationsInjectionsOrLongtermTreatments"
        - "SafetyScreening2_DoAnyOfTheAboveCurrentConditionsApplyToYou"

# ============================================================
# PARTICIPATION READINESS
# ============================================================

participation_readiness:
  table: participation_readiness
  columns:
    acknowledged:
      type: boolean
      transform: "yes_no_to_boolean"
      depends_on:
        - "IHaveReadAndUnderstandTheEligibilityAssessment"
        - "PreEnrollmentACCESSDataRecordsParticipationReadinessAcknowledgment2_PreEnrollmentAcknowledgment"
      logic: "both_fields_must_be_yes"

# ============================================================
# INTAKE ASSESSMENTS (medical history, medications, conditions)
# ============================================================

intake_assessments:
  table: intake_assessments
  columns:
    primary_concerns:
      field: "WholeSystem_WhatHealthConcernsWouldYouMostLikeMetaFlowToHelpYouTrackOrImprove"
      type: text[]
      transform: "json_array_to_list"  # Cognito returns "\"Option 1\", \"Option 2\""
    other_concerns:
      field: "WholeSystem_OtherConcerns"
      type: text
      nullable: true
    symptom_duration:
      field: "WholeSystem_HowLongHaveTheseConcernsOrSymptomsBeenPresent"
      type: text
      nullable: true
    primary_symptoms:
      field: "WholeSystem_WhatPhysicalSymptomsOrSensationsAreCurrentlyBotheringYouTheMost"
      type: text
      nullable: true
    medical_conditions:
      field: "MedicalHistoryMedicationSafetyReview_HaveYouEverBeenDiagnosedByAPhysicianWithAnyOfTheFollowingConditions"
      type: text[]
      transform: "json_array_to_list"
    infection_immune_conditions:
      field: "InfectionImmuneEndocrineAxisReview_HaveYouEverBeenDiagnosedByAPhysicianOrToldThatYouMayHaveAnyOfTheFollowing"
      type: text[]
      transform: "json_array_to_list"
    autoimmune_conditions:
      field: "InfectionImmuneEndocrineAxisReview_AutoimmuneImmuneInflammatoryOrEndocrineImmuneConditions"
      type: text[]
      transform: "json_array_to_list"
    conditions_active:
      field: "InfectionImmuneEndocrineAxisReview_AreAnyOfTheseInfectionImmuneInflammatoryOrEndocrineimmuneConditionsCurrentlyActiveOrUnstable"
      type: boolean
      nullable: true
      transform: "yes_no_to_boolean"  # "Yes" → true, "No" → false
    medications:
      field: "MedicalHistoryMedicationSafetyReview_AreYouCurrentlyUsingAnyOfTheFollowingMedicationsInjectionsOrLongtermTreatments"
      type: text[]
      transform: "json_array_to_list"
    medication_details:
      field: "MedicalHistoryMedicationSafetyReview_IfYouSelectedAnyMedicationOrSupplementAbovePleaseListTheNameDoseFrequencyAndReasonForUseIfKnown"
      type: text
      nullable: true
    medications_list:
      field: "PleaseListYourCurrentMedicationsSupplementsOrLongtermTreatments"
      type: text
      nullable: true
    allergies:
      field: "DoYouHaveAnyKnownAllergiesOrSensitivitiesToMedicationsFoodsHerbsSupplementsTopicalProductsFragrancesOrEssentialOils"
      type: text
      nullable: true

# ============================================================
# INTAKE LIFESTYLE (digestion, sleep, skin, body metrics, etc.)
# ============================================================

intake_lifestyle:
  table: intake_lifestyle
  columns:
    weight_lbs:
      field: "BodyMetrics_WeightInPounds"
      type: number
    waist_circumference_inches:
      field: "BodyMetrics_WaistCircumference"
      type: number
    height_inches:
      field: "BodyMetrics_HeightInInches"
      type: number
    weight_change_6mo:
      field: "BodyMetrics_WeightChangeOverThePast6Months"
      type: text
      nullable: true
    weight_control_patterns:
      field: "BodyMetrics_WhichOfTheFollowingBestDescribeYourWeightcontrolOrEatingcontrolPatterns"
      type: text[]
      transform: "json_array_to_list"
    activity_level:
      field: "BodyMetrics_WhichOptionBestDescribesYourUsualPhysicalActivityLevel"
      type: text
      nullable: true
    activity_types:
      field: "BodyMetrics_WhatTypesOfPhysicalActivityDoYouCurrentlyDo"
      type: text[]
      transform: "json_array_to_list"
    post_activity_response:
      field: "BodyMetrics_HowDoesYourBodyUsuallyRespondAfterPhysicalActivity"
      type: text[]
      transform: "json_array_to_list"
    digestive_patterns:
      field: "DigestionIntakeEnergyPattern_WhichOfTheFollowingDigestivePatternsDoYouCommonlyExperience"
      type: text[]
      transform: "json_array_to_list"
    diet_patterns:
      field: "DigestionIntakeEnergyPattern_WhichOfTheFollowingBestDescribeYourUsualDietAndLifestylePatterns"
      type: text[]
      transform: "json_array_to_list"
    digestive_conditions:
      field: "DigestionIntakeEnergyPattern_HaveYouEverBeenDiagnosedByAPhysicianWithAnyOfTheFollowingDigestiveConditions"
      type: text[]
      transform: "json_array_to_list"
    bowel_patterns:
      field: "BowelUrinaryFluidPattern_WhichOfTheFollowingBestDescribeYourTypicalBowelMovements"
      type: text[]
      transform: "json_array_to_list"
    urination_patterns:
      field: "BowelUrinaryFluidPattern_WhichOfTheFollowingBestDescribeYourTypicalUrinationPattern"
      type: text[]
      transform: "json_array_to_list"
    hemorrhoids:
      field: "BowelUrinaryFluidPattern_DoYouHaveHemorrhoidsOrAnalperianalIssues"
      type: text
      nullable: true
    sleep_quality:
      field: "SleepStressEmotionalState_WhichOfTheFollowingBestDescribeYourSleepQuality"
      type: text[]
      transform: "json_array_to_list"
    stress_emotional_state:
      field: "SleepStressEmotionalState_WhichOfTheFollowingBestDescribeYourRecentStressOrEmotionalState"
      type: text[]
      transform: "json_array_to_list"
    sweating_patterns:
      field: "SkinSweatingSurfaceReadout_WhichOfTheFollowingBestDescribeYourSweatingPatternAndTemperatureSensitivity"
      type: text[]
      transform: "json_array_to_list"
    skin_patterns:
      field: "SkinSweatingSurfaceReadout_WhichOfTheFollowingSkinPatternsApplyToYou"
      type: text[]
      transform: "json_array_to_list"
    skin_longterm_meds:
      field: "SkinSweatingSurfaceReadout_HaveYouUsedAnyOfTheFollowingLongtermForSkinImmuneInflammatoryOrAutoimmuneConditions"
      type: text
      nullable: true
    mouth_throat_ear_eye_symptoms:
      type: jsonb
      fields:
        - "MouthThroatNoseEyesEars_WhichOfTheFollowingMouthOrThroatSymptomsDoYouCommonlyExperience"
        - "MouthThroatNoseEyesEars_IfYouCoughUpPhlegmWhichDescriptionIsClosest"
        - "MouthThroatNoseEyesEars_WhichOfTheFollowingEyeSymptomsDoYouCommonlyExperience"
        - "MouthThroatNoseEyesEars_WhichOfTheFollowingNoseOrBreathingrelatedSymptomsDoYouCommonlyExperience"
        - "MouthThroatNoseEyesEars_WhichOfTheFollowingEarSymptomsDoYouCommonlyExperience"
        - "MouthThroatNoseEyesEars_DoYouCommonlyExperienceHeadachesDizzinessNauseaOrVomiting"
      transform: "collect_into_jsonb"

# ============================================================
# FEMALE HEALTH (only if sex = female)
# ============================================================

intake_female_health:
  table: intake_female_health
  condition: "intake_record.sex == 'female'"
  columns:
    menstrual_status:
      field: "Female_WhichOptionBestDescribesYourCurrentMenstrualStatus"
      type: text
      nullable: true
    menstrual_flow:
      field: "Female_HowWouldYouDescribeYourUsualMenstrualFlow"
      type: text
      nullable: true
    menstrual_blood_color:
      field: "Female_WhatColorIsYourMenstrualBloodUsuallyClosestTo"
      type: text
      nullable: true
    menstrual_clots_cramps:
      field: "Female_WhichOfTheFollowingApplyToMenstrualClotsCrampsOrAbnormalBleeding"
      type: text
      nullable: true
    discharge_discomfort:
      field: "Female_WhichOfTheFollowingApplyToVaginalDischargeOrPrivateareaDiscomfort"
      type: text
      nullable: true
    diagnosed_conditions:
      field: "Female_HaveYouEverBeenDiagnosedWithOrHadAHistoryOfAnyOfTheFollowing"
      type: text[]
      transform: "json_array_to_list"
    free_text:
      field: "Female_IsThereAnythingElseYouWouldLikeToAddAboutYourGynecologicHealthReproductiveHealthOrMenstrualStatus"
      type: text
      nullable: true

# ============================================================
# MALE HEALTH (only if sex = male)
# ============================================================

intake_male_health:
  table: intake_male_health
  condition: "intake_record.sex == 'male'"
  columns:
    prostate_conditions:
      field: "Male_HaveYouEverBeenDiagnosedWithOrToldYouMayHaveAnyProstaterelatedCondition"
      type: text[]
      transform: "json_array_to_list"
    sexual_function:
      field: "Male_WhichOfTheFollowingApplyToYourSexualFunction"
      type: text
      nullable: true
    ejaculation_concerns:
      field: "Male_WhichOfTheFollowingApplyToEjaculationOrSemenrelatedConcerns"
      type: text
      nullable: true
    perineal_testicular_symptoms:
      field: "Male_DoYouHaveAnyPerinealTesticularScrotalOrGroinSymptoms"
      type: text[]
      transform: "json_array_to_list"
    pelvic_surgery:
      field: "Male_HaveYouHadAnyMaleReproductiveUrologicOrPelvicSurgeryOrProcedure"
      type: text[]
      transform: "json_array_to_list"
    fertility_status:
      field: "Male_AreYouCurrentlyTryingToConceiveOrPlanningFertilityEvaluation"
      type: text
      nullable: true
    free_text:
      field: "Male_IsThereAnythingElseYouWouldLikeToAddAboutUrinaryProstateSexualFertilityOrMaleReproductiveHealth"
      type: text
      nullable: true

# ============================================================
# MSK / PAIN ASSESSMENT
# ============================================================

intake_msk:
  table: intake_msk
  columns:
    pain_locations:
      field: "PainInjuryMusculoskeletalFunctionalBoundary_WhereDoYouCommonlyExperienceSorenessTightnessPainNumbnessStiffnessOrWeakness"
      type: text[]
      transform: "json_array_to_list"
    msk_diagnoses:
      field: "PainInjuryMusculoskeletalFunctionalBoundary_HaveYouEverBeenDiagnosedByAPhysicianWithAnyOfTheFollowing"
      type: text[]
      transform: "json_array_to_list"
    injury_history:
      field: "PainInjuryMusculoskeletalFunctionalBoundary_DoYouHaveAClearHistoryOfSportsInjuryTraumaOrPhysicalInjury"
      type: text[]
      transform: "json_array_to_list"
    functional_impact:
      field: "PainInjuryMusculoskeletalFunctionalBoundary_DoesThePainAffectYourDailyFunction"
      type: text[]
      transform: "json_array_to_list"
    pain_quality:
      field: "PainInjuryMusculoskeletalFunctionalBoundary_WhichDescriptionsBestMatchTheQualityOfYourPain"
      type: text[]
      transform: "json_array_to_list"
    pain_duration:
      field: "PainInjuryMusculoskeletalFunctionalBoundary_HowLongHasThisPainBeenPresent"
      type: text
      nullable: true
    pain_severity:
      field: "PainInjuryMusculoskeletalFunctionalBoundary_WhatIsTheSeverityOfYourMainPainArea"
      type: number
      nullable: true

# ============================================================
# FORM SUBMISSION EVENTS
# ============================================================

form_submission_events:
  table: form_submission_events  # metadata about form submission lifecycle
  columns:
    submitted_at:
      field: "Entry_DateSubmitted"
      type: timestamp
      transform: "timestamp_ms_to_datetime"
    form_version:
      field: "Entry_DateCreated"
      type: timestamp
      transform: "timestamp_ms_to_datetime"  # as proxy for form version date
    source_system:
      value: "cognito"
    status:
      field: "Entry_Status"
      type: text