Generated Narrative: StructureMap ExtractLabRequisitionSerology

/// url = 'https://fhir.slade360.co.ke/fhir/StructureMap/ExtractLabRequisitionSerology'
/// name = 'ExtractLabRequisitionSerology'
/// title = 'Medical Laboratory Requisition Extraction'
/// status = 'active'
/// description = 'One ServiceRequest per investigation asked for, category SNOMED 108252007 laboratory, with the urgency mapped onto the three request-priority codes; and one laboratory Observation per result the sheet carries, because this form is a requisition and a report on one page. The clinical history rides on every request: a serology result without it is uninterpretable, which is exactly why the form asks for it.'

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/Observation" alias Observation as target
uses "http://hl7.org/fhir/StructureDefinition/ServiceRequest" alias ServiceRequest as target

group ExtractLabRequisitionSerology(source qr : QR, target bundle : Bundle) {
  qr -> bundle.type = 'transaction' "setBundleType";
  qr.item as i where ((linkId = 'investigation') and item.where(linkId = 'investigation/name').answer.value.exists()) ->  bundle.entry as entry,  entry.resource = create('ServiceRequest') as sr then {
    qr ->  sr,  entry then BuildServiceRequestBase(qr, sr, entry) "base";
    i -> sr.status = 'active' "status";
    i -> sr.intent = 'order' "intent";
    qr.encounter as e -> sr.encounter = e;
    qr.authored as t -> sr.authoredOn = t "authoredOn";
    i -> sr.category as cat then {
      i -> cat.coding as cg then {
        i -> cg.system = 'http://snomed.info/sct' "sys";
        i -> cg.code = '108252007' "cd";
        i -> cg.display = 'Laboratory procedure' "dsp";
      } "coding";
    } "category";
    i.item as it where (linkId = 'investigation/name') then {
      it.answer first as a then {
        a.value as txt ->  sr.code as cr,  cr.concept as cc,  cc.text = txt "codeText";
      };
    } "nameRule";
    i.item as it where ((linkId = 'investigation/specimen') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as txt ->  sr.specimen = create('Reference') as spref,  spref.display = txt "specimen";
      };
    } "specimenRule";
    qr -> sr then SetLabRequestCommon(qr, sr) "common";
  } "investigationRequest";
  // ── The results the sheet carries ───────────────────────────────────────
  qr.item as r where ((linkId = 'result') and item.where(linkId = 'result/test').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 SetLaboratoryCategory(qr, obs) "category";
    r.item as it where (linkId = 'result/test') then {
      it.answer first as a then {
        a.value as txt ->  obs.code as cc,  cc.text = txt "codeText";
      };
    } "testRule";
    // The result is free text on the paper -- "Reactive", "1:160", "Negative"
    // -- so it goes to note rather than being coerced into a value type the
    // form does not commit to. Observation.value[x] has no string choice in R5.
    r.item as it where (linkId = 'result/value') then {
      it.answer first as a then {
        a.value as txt ->  obs.note as n,  n.text = txt "resultText";
      };
    } "valueRule";
    r.item as it where ((linkId = 'result/tested-by') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as ref -> obs.performer = ref "testedBy";
      };
    } "testedByRule";
    r.item as it where ((linkId = 'result/reviewed-by') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as ref -> obs.performer = ref "reviewedBy";
      };
    } "reviewedByRule";
    r.item as it where ((linkId = 'result/dispatched-at') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as v -> obs.issued = cast(v, 'instant') "issued";
      };
    } "dispatchedRule";
    qr.item as s where (linkId = 'specimen') then {
      s.item as it where ((linkId = 'specimen/collected-at') and answer.value.exists()) then {
        it.answer first as a then {
          a.value as v -> obs.effective = v "effective";
        };
      } "collectedAtRule";
      s.item as it where ((linkId = 'specimen/lab-registration-number') and answer.value.exists()) then {
        it.answer first as a then {
          a.value as txt -> obs.identifier as ident then {
            txt -> ident.system = 'https://fhir.slade360.co.ke/fhir/identifier/lab-registration' "identSystem";
            txt -> ident.value = txt "identValue";
          } "identifier";
        };
      } "labRegRule";
    } "specimenGroup";
  } "resultObservation";
  qr.item as it where ((linkId = 'clinical-history') 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 = 'http://loinc.org' "sys";
        it -> cg.code = '55752-0' "cd";
        it -> cg.display = 'Clinical information' "dsp";
      } "coding";
      it -> cc.text = 'Clinical history given to the laboratory' "codeText";
    } "code";
    it.answer first as a then {
      a.value as txt ->  obs.note as n,  n.text = txt "text";
    };
  } "narr_55752_0";
}

// Everything every investigation on the sheet shares. Factored out because
// drifting copies is how one request silently loses its priority.
group SetLabRequestCommon(source qr : QR, target sr : ServiceRequest) {
  qr.item as g where (linkId = 'request') then {
    g.item as it where ((linkId = 'request/requester') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as ref -> sr.requester = ref "requester";
      };
    } "requesterRule";
    // The form's own three words mapped onto request-priority. Desperate is
    // stat, routine is routine; the middle one happens to share its name.
    g.item as it where ((linkId = 'request/urgency') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as cv where (code = 'lab-urgency-desperate') -> sr.priority = 'stat' "stat";
      } "desperateRule";
      it.answer first as a then {
        a.value as cv where (code = 'lab-urgency-urgent') -> sr.priority = 'urgent' "urgent";
      } "urgentRule";
      it.answer first as a then {
        a.value as cv where (code = 'lab-urgency-routine') -> sr.priority = 'routine' "routine";
      } "routineRule";
    } "urgencyRule";
    g.item as it where ((linkId = 'request/department') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as txt ->  sr.note as n,  n.text = txt "departmentNote";
      };
    } "departmentRule";
  } "requestGroup";
  // The clinical history, on the request itself. The SGHI ServiceRequest
  // profile binds `reason` required to a LOINC value set and this form takes
  // free text, so a coded reason is not available -- but a laboratory that
  // cannot see why a test was asked for cannot interpret it either.
  qr.item as it where ((linkId = 'clinical-history') and answer.value.exists()) then {
    it.answer first as a then {
      a.value as txt ->  sr.note as n,  n.text = txt "historyNote";
    };
  } "historyRule";
  qr.item as g where (linkId = 'specimen') then {
    g.item as it where ((linkId = 'specimen/collected-by') and answer.value.exists()) then {
      it.answer first as a then {
        a.value as ref -> sr.performer = ref "collectedBy";
      };
    } "collectedByRule";
  } "specimenGroup";
}

// ─────────────────────────────────────────────────────────────────────────────
// 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 SetLaboratoryCategory(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 = 'laboratory' "categoryCode";
      qr -> coding.display = 'Laboratory' "categoryDisplay";
    } "categoryCoding";
  } "category";
}

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

group SetServiceRequestFullUrl(source r : ServiceRequest, target entry) {
  r.id as id -> entry.fullUrl = append('https://fhir.slade360.co.ke/fhir/ServiceRequest/', 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 = 'lab-requisition-serology' "provenanceCode";
      qr -> t.display = 'Medical laboratory requisition' "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";
}