Generated Narrative: StructureMap ExtractDeclineForm

/// url = 'https://fhir.slade360.co.ke/fhir/StructureMap/ExtractDeclineForm'
/// name = 'ExtractDeclineForm'
/// title = 'Decline Form Extraction'
/// status = 'active'
/// description = 'The refusal out as a Consent with `decision = \'deny\'` -- the only deny decision in this whole set -- with one provision per thing actually being refused, so a patient refusing a single procedure is not recorded as having refused all care. An Observation records whether they understood the explanation and in which language, because that is what makes the refusal informed and it is the fact a later dispute turns on.'

uses "http://hl7.org/fhir/StructureDefinition/QuestionnaireResponse" alias QR as source
uses "http://hl7.org/fhir/StructureDefinition/Bundle" alias Bundle as target
uses "http://hl7.org/fhir/StructureDefinition/Consent" alias Consent as target
uses "http://hl7.org/fhir/StructureDefinition/Observation" alias Observation as target

group ExtractDeclineForm(source qr : QR, target bundle : Bundle) {
  qr -> bundle.type = 'transaction' "setBundleType";
  // Guarded on the person having actually signed. A refusal built from a
  // half-filled form asserts that somebody declined care when they may not have.
  qr where (item.where(linkId = 'signatures').item.where(linkId = 'signatures/person-signed').answer.value = true) ->  bundle.entry as entry,  entry.resource = create('Consent') as consent then {
    qr ->  consent,  entry then BuildConsentBase(qr, consent, entry) "base";
    qr -> consent.status = 'active' "status";
    // `deny`, not `permit`. This is the one form in the set that records a
    // refusal, and the whole resource turns on this single code.
    qr -> consent.decision = 'deny' "decision";
    qr -> consent.category as cat then {
      qr -> cat.coding as cg then {
        qr -> cg.system = 'http://terminology.hl7.org/CodeSystem/consentcategorycodes' "sys";
        qr -> cg.code = 'acd' "cd";
        qr -> cg.display = 'Advance Directive' "dsp";
      } "coding";
      qr -> cat.text = 'Decline of care, procedure or assessment' "categoryText";
    } "category";
    qr.item as sg where (linkId = 'signatures') then {
      sg.item as it where ((linkId = 'signatures/signed-on') and answer.value.exists()) then {
        it.answer first as a then {
          a.value as d -> consent.date = d "signedDate";
        };
      } "signedOnRule";
      // The witness verifies the refusal. On this form that matters more than on
      // a consent: the hospital is recording that somebody left against advice.
      sg.item as it where ((linkId = 'signatures/witness-signed') and (answer.value = true)) -> consent.verification as ver then {
        it -> ver.verified = true "verified";
        sg.item as wn where ((linkId = 'signatures/witness-name') and answer.value.exists()) then {
          wn.answer first as wa then {
            wa.value as txt ->  ver.verifiedBy = create('Reference') as ref,  ref.display = txt "witnessDisplay";
          };
        } "witnessNameRule";
      } "witnessVerification";
    } "signaturesGroup";
    qr.item as pg where (linkId = 'person-declining') then {
      pg.item as it where ((linkId = 'person-declining/name') and answer.value.exists()) then {
        it.answer first as a then {
          a.value as txt ->  consent.grantor = create('Reference') as ref,  ref.display = txt "grantorDisplay";
        };
      } "nameRule";
      pg.item as it where ((linkId = 'person-declining/relationship') and answer.value.exists()) then {
        it.answer first as a then {
          a.value as txt ->  consent.grantor = create('Reference') as ref,  ref.display = txt "relationshipDisplay";
        };
      } "relationshipRule";
    } "personGroup";
    qr.item as eg where (linkId = 'what-was-explained') then {
      eg.item as it where ((linkId = 'what-was-explained/doctor') and answer.value.exists()) then {
        it.answer first as a then {
          a.value as ref -> consent.manager = ref "manager";
        };
      } "doctorRule";
    } "explainedGroup";
    // ── One provision per thing refused ─────────────────────────────────────
    // The sheet prints "care/procedure/assessment" as one slashed phrase. A
    // single provision saying all three would record a patient who declined one
    // investigation as having refused every kind of care, which is both wrong
    // and the sort of wrong that ends up in a coroner's court.
    qr.item as it where (linkId = 'declining') then {
      it.answer as a -> consent.provision as prov then {
        a.value as cv -> prov.code as pc then {
          cv -> pc.coding = cv "coding";
          cv.display as d -> pc.text = d "text";
        } "declineCode";
      } "declineProvision";
    } "decliningGroup";
    qr.item as it where ((linkId = 'procedure-declined') and answer.value.exists()) -> consent.provision as prov then {
      it.answer first as a then {
        a.value as txt ->  prov.code as pc,  pc.text = txt "procedureText";
      };
    } "procedureDeclinedProvision";
    // Where the patient is going. Recorded on the Consent because it is part of
    // the refusal -- a patient transferring to another hospital and one going
    // home carry different follow-up obligations.
    qr.item as it where ((linkId = 'destination') and answer.value.exists()) -> consent.provision as prov then {
      it.answer first as a then {
        a.value as cv -> prov.code as pc then {
          cv -> pc.coding = cv "coding";
          cv.display as d -> pc.text = append('Opting to go to: ', d) "text";
        } "destinationCode";
      };
    } "destinationProvision";
  } "createDeclineConsent";
  // ── Was the refusal informed? ───────────────────────────────────────────
  // Its own Observation. Not a provision -- it is not a thing being refused --
  // but it is the fact that makes the refusal defensible, and it carries the
  // language the discussion was held in. The paper form is bilingual and the
  // language was previously only implied by which half of the sheet was signed.
  qr.item as g where (linkId = 'what-was-explained') then {
    g.item as it where ((linkId = 'what-was-explained/understood') and answer.value.exists()) ->  bundle.entry as entry,  entry.resource = create('Observation') as obs then {
      qr ->  obs,  entry then BuildObsBase(qr, obs, entry) "base";
      qr -> obs then SetSurveyCategory(qr, obs) "category";
      it -> obs.code as cc then {
        it -> cc.coding as cg then {
          it -> cg.system = 'https://fhir.slade360.co.ke/fhir/CodeSystem/inpatient-clinical-concept-codesystem' "sys";
          it -> cg.code = 'capacity-to-consent' "cd";
          it -> cg.display = 'Capacity to consent' "dsp";
        } "coding";
        it -> cc.text = 'Understood the explanation of the condition and the risks of declining' "codeText";
      } "code";
      it.answer first as a then {
        a.value as cv -> obs.value = create('CodeableConcept') as vc then {
          cv -> vc.coding = cv "valueCoding";
          cv.display as d -> vc.text = d "valueText";
        } "codedValue";
      };
      it.answer first as a then {
        a.value as cv where (code = 'N') -> obs.interpretation as interp then {
          cv -> interp.coding as icg then {
            cv -> icg.system = 'http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation' "sys";
            cv -> icg.code = 'A' "cd";
            cv -> icg.display = 'Abnormal' "dsp";
          } "coding";
        } "notUnderstoodInterp";
      } "understoodInterpretation";
      g.item as it where (linkId = 'what-was-explained/language') then {
        it.answer first as a then {
          a.value as txt ->  obs.note as n,  n.text = txt "text";
        };
      } "note";
      g.item as it where (linkId = 'what-was-explained/condition-and-risks') then {
        it.answer first as a then {
          a.value as txt ->  obs.note as n,  n.text = txt "text";
        };
      } "note2";
    } "understoodObservation";
  } "explainedGroup";
}

// ─────────────────────────────────────────────────────────────────────────────
// Shared scaffolding. Repeated in each map rather than imported: the transform
// engine resolves `imports` against whatever StructureMaps happen to be on the
// server, and a form that stops extracting because a shared map was not
// uploaded is a worse failure than a duplicated group.
// Two notes on what the publisher's StructureMap validator says about this file.
// Source parameters below are left untyped on purpose. Writing `: Element` makes
// the validator compare QuestionnaireResponse.item against the literal 'Element'
// and report them as incompatible with each other, which is noise, not a finding.
// `evaluate(context, expression)` is flagged as "takes 1 parameter but 2 were
// found". Leave it. The FML parser in the same jar refuses the one-argument form
// outright -- it wants a parameter, a comma, then the FHIRPath -- so the
// publisher is objecting to what its own compiler emits. Two arguments is the
// only form that compiles, and it is what the R5 transform engine executes.
// ─────────────────────────────────────────────────────────────────────────────
group BuildObsBase(source qr : QR, target obs : Observation, target entry) {
  qr -> obs then SetResponseProvenance(qr, obs) "responseProvenance";
  qr -> obs.id = uuid() then SetObservationFullUrl(obs, entry) "idAndFullUrl";
  qr -> entry.request as request then {
    qr -> request.method = 'POST' "requestMethod";
    qr -> request.url = 'Observation' "requestUrl";
  } "entryRequest";
  qr -> obs.status = 'final' "status";
  qr.subject as s -> obs.subject = s;
  qr.encounter as e -> obs.encounter = e;
  qr.authored as t -> obs.effective = t "effective";
  qr.source as src -> obs.performer = src "performerFromSource";
  qr where (source.exists().not()) then {
    qr.author as a -> obs.performer = a "performerFromAuthor";
  } "performerFallback";
  // A stored response's id already reads "QuestionnaireResponse/<id>", so it is
  // a relative reference as it stands. The hasValue() guard is what stops an
  // unsaved response -- one posted straight to $extract rather than saved first
  // -- from writing "QuestionnaireResponse/null" into the record.
  qr.id as qid where ($this.hasValue()) ->  obs.derivedFrom = create('Reference') as ref,  ref.reference = qid "linkQuestionnaireResponse";
}

group SetObservationFullUrl(source obs : Observation, target entry) {
  obs.id as id -> entry.fullUrl = append('https://fhir.slade360.co.ke/fhir/Observation/', id) "assignFullUrl";
}

// The two answer shapes a component can carry. Both read the answer through the
// untyped `.value` accessor: reading `valueCoding` or `valueQuantity` by its
// typed property name fails at transform time on HAPI R5 with "Attempt to read
// invalid property ... on QuestionnaireResponse.item.answer".
group SetComponentCodedValue(source it, target comp) {
  it.answer first as a then {
    a.value as cv -> comp.value = create('CodeableConcept') as cc then {
      cv -> cc.coding = cv "valueCoding";
      cv.display as d -> cc.text = d "valueText";
    } "codedValue";
  } "componentAnswer";
}

group SetComponentValue(source it, target comp) {
  it.answer first as a then {
    a.value as v -> comp.value = v "plainValue";
  } "componentAnswer";
}

group SetSurveyCategory(source qr : QR, target obs : Observation) {
  qr -> obs.category as cat then {
    qr -> cat.coding as coding then {
      qr -> coding.system = 'http://terminology.hl7.org/CodeSystem/observation-category' "categorySystem";
      qr -> coding.code = 'survey' "categoryCode";
      qr -> coding.display = 'Survey' "categoryDisplay";
    } "categoryCoding";
  } "category";
}

group BuildConsentBase(source qr : QR, target r : Consent, target entry) {
  qr -> r then SetResponseProvenance(qr, r) "responseProvenance";
  qr -> r.id = uuid() then SetConsentFullUrl(r, entry) "idAndFullUrl";
  qr -> entry.request as request then {
    qr -> request.method = 'POST' "requestMethod";
    qr -> request.url = 'Consent' "requestUrl";
  } "entryRequest";
  qr.subject as s -> r.subject = s;
}

group SetConsentFullUrl(source r : Consent, target entry) {
  r.id as id -> entry.fullUrl = append('https://fhir.slade360.co.ke/fhir/Consent/', id) "assignFullUrl";
}

// ── Provenance and tenancy ───────────────────────────────────────────────────
// Two tags on everything this map creates. The first says which questionnaire
// produced it, so a form that reopens mid-admission recalls its own earlier
// entries and not another form's. The second copies the tenant tags off the
// response, because nothing else on the path puts them there.
// The code is the form's document type, not the questionnaire's id: every
// environment mints its own ids, and there is only one set of maps, so an id
// here would tie the tag to whichever environment stamped it.
// ── Provenance and tenancy ───────────────────────────────────────────────────
group SetResponseProvenance(source qr : QR, target r) {
  qr -> r.meta as m then {
    qr -> m.tag as t then {
      qr -> t.system = 'http://slade360edi.com/questionnaire-provenance' "provenanceSystem";
      qr -> t.code = 'decline-form' "provenanceCode";
      qr -> t.display = 'Decline form' "provenanceDisplay";
    } "provenanceTag";
  } "provenanceMeta";
  // Every tag the response carries, onto the resource. `meta` is 0..1, so this
  // lands on the same meta the rule above created rather than a second one.
  qr.meta as qm then {
    qm.tag as qt ->  r.meta as m,  m.tag = qt "copyTag";
  } "tenantTags";
}