dirigent-integration 0.23.2__py3-none-any.whl

dirigent_integration/shelves/fhir/fhir-patient-to-tracked-entity.yaml

@@ -0,0 +1,225 @@
+# A FHIR Patient search turned into a DHIS2 tracked entity, posted to /api/tracker by hand.
+#
+# THE FLOW, END TO END. Search the facade's Patient register by identifier, read one Patient
+# out of the searchset Bundle, build the `/api/tracker` payload DHIS2 wants for a tracked
+# entity and its enrollment, and post it with importMode=VALIDATE.
+#
+# WHY http.request AND NOT dhis2.tracker. `dhis2.tracker` READS: it is idempotent, it takes a
+# `kind` of trackedEntities, enrollments or events, and it has no payload field at all. There
+# is no tracker write block in the pack today, so a pipeline that writes tracker objects posts
+# them itself. That works without a second credential, because `http.request` resolves a
+# connection's base URL, basic credentials, TLS setting and timeout STRUCTURALLY, by field
+# name, whatever kind the connection is -- so the `dhis2` connection this pack contributes
+# drives an ordinary HTTP call. One caveat, and it is the reason this comment exists: only
+# `basic_username`/`basic_password` are read that way. A dhis2 connection authenticating with
+# `api_token` reaches `http.request` UNAUTHENTICATED, so a token-based instance needs an
+# `http` connection carrying the token as a header instead.
+#
+# WHAT ARRIVES. The register projects each DHIS2 tracked entity as a Patient:
+#
+#   {"resourceType": "Patient", "id": "coxwIkMqNBB",
+#    "meta": {"tag": [{"system": "http://dhis2.org/fhir/id/tracked-entity-type",
+#                      "code": "nEenWmSyUEp"}]},
+#    "identifier": [
+#      {"system": "http://dhis2.org/fhir/id/tracked-entity", "value": "coxwIkMqNBB"},
+#      {"system": "http://dhis2.org/fhir/tracked-entity-attribute/AuPLng5hLbE",
+#       "value": "299554435"}],
+#    "extension": [{"url": ".../d2-tracked-entity-attribute-value",
+#                   "extension": [{"url": "attributeId", "valueString": "w75KJ2mc4zz"},
+#                                 {"url": "value", "valueString": "Eden"}]}]}
+#
+# The split is deliberate and it is the whole mapping: a tracked entity attribute DHIS2
+# declares `unique` is projected as an `identifier` under its own per-attribute system, and
+# every other attribute rides as a `D2TrackedEntityAttributeValue` extension. Both are
+# attributes on the way back in.
+#
+# WHAT LEAVES. One `/api/tracker` document:
+#
+#   {"trackedEntities": [
+#      {"trackedEntity": "coxwIkMqNBB", "trackedEntityType": "nEenWmSyUEp",
+#       "orgUnit": "ImspTQPwCqd",
+#       "attributes": [{"attribute": "w75KJ2mc4zz", "value": "Eden"},
+#                      {"attribute": "AuPLng5hLbE", "value": "299554435"}],
+#       "enrollments": [{"enrollment": "EnAaBbCcDd1", "program": "IpHINAT79UW",
+#                        "orgUnit": "ImspTQPwCqd", "enrolledAt": "2026-09-01",
+#                        "status": "ACTIVE"}]}]}
+#
+# WHICH SYSTEM BECOMES WHAT.
+#
+#   meta.tag under .../id/tracked-entity-type          -> trackedEntityType
+#   identifier under .../id/tracked-entity             -> trackedEntity (the uid)
+#   identifier under .../tracked-entity-attribute/<uid> -> one attribute, uid from the system
+#   D2TrackedEntityAttributeValue extension            -> one attribute, uid from attributeId
+#
+# WHERE A READER CHANGES IT. `program` is the tracker program to enrol into and `org_unit` the
+# unit that owns the registration; both are DHIS2 uids and neither is anywhere in the Patient,
+# because the register publishes people rather than enrollments. `search_identifier` is what
+# picks the person: a bare value tries every key, `system|value` pins one.
+#
+# WHAT THIS DOES NOT DO. It does not mint an enrollment uid. A registration needs one, DHIS2
+# does not generate it for this shape, and inventing an 11-character uid in jq would teach the
+# wrong lesson -- so `enrollment_uid` is a parameter, which is exactly where a real forwarder
+# derives one deterministically so a rehearsal and an import name the same object.
+#
+#   dg run --local examples/fhir/fhir-patient-to-tracked-entity.yaml
+#   dg run --local examples/fhir/fhir-patient-to-tracked-entity.yaml -p search_identifier=299554435
+
+format: dirigent/v1
+kind: pipeline
+code: fhir-patient-to-tracked-entity
+name: FHIR Patient to a DHIS2 tracked entity
+description: |
+  Search the facade's `Patient` register and build the `/api/tracker` payload for one tracked
+  entity and its enrollment, posted with `importMode=VALIDATE`.
+
+  `dhis2.tracker` reads and does not write, so the write is an ordinary `http.request` on the
+  `dhis2` connection -- which works because the HTTP blocks read `base_url` and the basic
+  credentials structurally, by field name, from a connection of any kind.
+
+tags: [fhir, dhis2, cross-boundary]
+
+requires:
+  blocks:
+    - http.request
+    - transform.jq
+
+connections:
+  fhir-facade:
+    kind: http
+    config:
+      base_url: http://localhost:8095
+      timeout: 30s
+  # Driven by two different blocks below: `dhis2.*` blocks would resolve it through
+  # dhis2w-client, and `http.request` resolves the same record structurally. The password is a
+  # SecretStr either way -- sealed on the way in, redacted in every read back.
+  dhis2-demo:
+    kind: dhis2
+    config:
+      base_url: https://play.im.dhis2.org/stable-2-43-1
+      basic_username: admin
+      basic_password: district
+      timeout: 60s
+
+params:
+  type: object
+  properties:
+    search_identifier:
+      type: string
+      description: The identifier token to find the person by; bare value, or system|value.
+      default: "299554435"
+    tracked_entity_type:
+      type: string
+      description: Which register to search, over meta.tag.
+      default: nEenWmSyUEp
+    program:
+      type: string
+      description: The tracker program to enrol into. Not in the Patient, because the register
+        publishes people and not enrollments.
+      default: IpHINAT79UW
+    org_unit:
+      type: string
+      description: The org unit owning the registration.
+      default: ImspTQPwCqd
+    enrollment_uid:
+      type: string
+      description: The enrollment's own uid, which the client mints. A real forwarder derives
+        it from the receipt so a rehearsal and an import name the same object.
+      default: EnAaBbCcDd1
+    enrolled_at:
+      type: string
+      description: The enrolment date, a zone-less wall clock in DHIS2's vocabulary.
+      default: "2026-09-01"
+
+steps:
+  # The register answers exactly three search parameters -- identifier, _tag and d2-attribute
+  # -- and REFUSES anything else with a 400 naming the three, rather than ignoring it. That is
+  # the opposite of the definitional types, which ignore what they do not know: an unapplied
+  # filter on a register would otherwise answer with every person in the country.
+  find_patient:
+    block: http.request
+    config:
+      connection: fhir-facade
+      path: /Patient
+      method: GET
+      query:
+        identifier: "${params.search_identifier}"
+        _tag: "${params.tracked_entity_type}"
+        _count: 1
+      headers:
+        Accept: application/fhir+json
+
+  # Both attribute carriers are read here, and they union into one `attributes` array. The
+  # per-attribute identifier system ends in the attribute's own uid, so the uid is the last
+  # path segment of the system rather than a field of its own.
+  to_tracker_payload:
+    block: transform.jq
+    depends_on: [find_patient]
+    config:
+      input:
+        bundle: "${steps.find_patient.output.body}"
+        program: "${params.program}"
+        org_unit: "${params.org_unit}"
+        enrollment: "${params.enrollment_uid}"
+        enrolled_at: "${params.enrolled_at}"
+      program: |
+        . as {$bundle, $program, $org_unit, $enrollment, $enrolled_at}
+        | ($bundle.entry // [])[0].resource as $p
+        | if $p == null then error("the register answered no Patient for that identifier") else . end
+        | {trackedEntities: [{
+            trackedEntity: (
+              [$p.identifier[] | select(.system | endswith("/id/tracked-entity"))][0].value),
+            trackedEntityType: (
+              [$p.meta.tag[] | select(.system | endswith("/id/tracked-entity-type"))][0].code),
+            orgUnit: $org_unit,
+            attributes: (
+              [$p.identifier[]
+               | select(.system | contains("/tracked-entity-attribute/"))
+               | {attribute: (.system | split("/") | last), value: .value}]
+              + [($p.extension // [])[]
+                 | select(.url | endswith("/d2-tracked-entity-attribute-value"))
+                 | {attribute: ([.extension[] | select(.url == "attributeId").valueString][0]),
+                    value: ([.extension[] | select(.url == "value").valueString][0])}]),
+            enrollments: [{
+              enrollment: $enrollment,
+              program: $program,
+              orgUnit: $org_unit,
+              enrolledAt: $enrolled_at,
+              status: "ACTIVE"}]}]}
+
+  # A dry run on /api/tracker is importMode=VALIDATE. It is NOT dryRun=true -- that is
+  # /api/dataValueSets -- and reaching for the wrong spelling on either endpoint does not
+  # fail, it imports.
+  #
+  # A payload carrying `trackedEntities` implies CREATE_AND_UPDATE. Enrolling a person who
+  # already exists is a different document -- a top-level `enrollments` array with no
+  # trackedEntities wrapper, under plain CREATE -- because the wrapper would rewrite the
+  # person's owning org unit on the way past.
+  rehearse_import:
+    block: http.request
+    depends_on: [to_tracker_payload]
+    config:
+      connection: dhis2-demo
+      path: /api/tracker
+      method: POST
+      query:
+        importMode: VALIDATE
+      headers:
+        Content-Type: application/json
+      body: "${steps.to_tracker_payload.output.value}"
+      # /api/tracker answers an async job with 200 and a completed one with 200 or 409; the
+      # report is in the body either way, so a 409 is a verdict to read rather than a
+      # transport failure to fail the step on.
+      success_status: [200, 201, 409]
+
+  # The tracker import report, not the HTTP status. `status` is the instance's own word, and
+  # validationReport.errorReports names every refused object with its DHIS2 error code.
+  read_report:
+    block: transform.jq
+    depends_on: [rehearse_import]
+    config:
+      input: "${steps.rehearse_import.output.body}"
+      program: |
+        {status: .status,
+         stats: (.stats // .response.stats),
+         errors: [((.validationReport // .response.validationReport).errorReports // [])[]
+                  | {code: .errorCode, uid: .uid, message: .message}]}

dirigent_integration/shelves/fhir/fhir-questionnaire-response-to-data-values.yaml

@@ -0,0 +1,187 @@
+# One QuestionnaireResponse mapped onto data elements by a linkId lookup the document carries.
+#
+# THE FLOW, END TO END. Read one capture off the facade by its receipt id, translate its
+# answers into data values through an explicit linkId-to-data-element table held in params,
+# and import the result -- dry run first.
+#
+# WHY A LOOKUP AT ALL. On a `d2w fhir serve` facade the linkIds already ARE DHIS2 uids, so
+# capture-bundle-to-data-values.yaml needs no table: it splits the dotted linkId and is done.
+# Every other FHIR server in the world uses linkIds a form designer chose -- "anc.visits.total",
+# "q3b", "weight_kg" -- and then the table IS the integration. This document is the general
+# case, and the facade is only where the example gets a real response to run against.
+#
+# WHAT ARRIVES. One QuestionnaireResponse, answers keyed by whatever the form calls them:
+#
+#   {"resourceType": "QuestionnaireResponse", "status": "completed",
+#    "subject": {"reference": "Location/dczh6Jfd4no"},
+#    "item": [{"linkId": "anc.visits.first", "answer": [{"valueInteger": 42}]},
+#             {"linkId": "anc.visits.followup", "answer": [{"valueInteger": 17}]},
+#             {"linkId": "anc.notes", "answer": [{"valueString": "clinic closed on the 4th"}]}]}
+#
+# WHAT LEAVES. The same `/api/dataValueSets` envelope every aggregate import wants:
+#
+#   {"dataSet": "lyLU2wR22tC", "period": "202608", "orgUnit": "dczh6Jfd4no",
+#    "dataValues": [{"dataElement": "GMd99K8gVut", "categoryOptionCombo": "qNCMOhkoQju",
+#                    "value": "42"}]}
+#
+# WHERE A READER CHANGES IT. `link_ids` below, and nowhere else. Each entry maps one linkId to
+# the DHIS2 cell it means: `data_element` alone for an undisaggregated data element, plus
+# `category_option_combo` for one column of a category combination. A linkId absent from the
+# table is dropped rather than guessed at, and the drop is counted and reported, because an
+# answer that silently vanishes is worse than an import that refuses.
+#
+#   dg run --local examples/fhir/fhir-questionnaire-response-to-data-values.yaml
+#   dg run --local examples/fhir/fhir-questionnaire-response-to-data-values.yaml -p period=202607
+
+format: dirigent/v1
+kind: pipeline
+code: fhir-questionnaire-response-to-data-values
+name: QuestionnaireResponse through a linkId table
+description: |
+  Map one `QuestionnaireResponse` onto DHIS2 data values through an explicit linkId lookup,
+  for the general case where a form's `linkId` is a designer's name rather than a DHIS2 uid.
+
+  A linkId the table does not name is dropped and counted, never guessed at.
+
+tags: [fhir, dhis2, cross-boundary]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+    - dhis2.data_value_set_import
+
+connections:
+  dhis2-demo:
+    kind: dhis2
+    config:
+      base_url: https://play.im.dhis2.org/stable-2-43-1
+      basic_username: admin
+      basic_password: district
+      timeout: 60s
+
+params:
+  type: object
+  properties:
+    data_set:
+      type: string
+      description: The DHIS2 data set the answers belong to.
+      default: lyLU2wR22tC
+    org_unit:
+      type: string
+      description: The org unit reporting, which a real capture reads off subject.reference.
+      default: dczh6Jfd4no
+    period:
+      type: string
+      description: The DHIS2 ISO period, which is a period identifier and not a date range.
+      default: "202608"
+    link_ids:
+      type: object
+      description: |
+        The mapping. One entry per linkId the form can answer: data_element on its own is an
+        undisaggregated data element, and category_option_combo names one column of a
+        category combination.
+      default:
+        anc.visits.first:
+          data_element: GMd99K8gVut
+          category_option_combo: qNCMOhkoQju
+        anc.visits.followup:
+          data_element: GMd99K8gVut
+          category_option_combo: LbeIlyHEhKr
+        anc.staff.count:
+          data_element: wfKKFhBn0Q0
+
+steps:
+  # The capture, written inline so the document runs with nothing set up. In service it is the
+  # body of a webhook delivery (fhir-subscription-webhook-to-dhis2.yaml) or one entry of a
+  # searchset Bundle (capture-bundle-to-data-values.yaml); either way this step's output is
+  # exactly one QuestionnaireResponse, and nothing downstream knows where it came from.
+  receive:
+    block: value.const
+    config:
+      value:
+        resourceType: QuestionnaireResponse
+        status: completed
+        authored: "2026-08-31T09:00:00Z"
+        questionnaire: http://example.org/fhir/Questionnaire/anc-monthly
+        subject:
+          reference: Location/dczh6Jfd4no
+        item:
+          - linkId: anc.visits.first
+            text: First antenatal visits
+            answer:
+              - valueInteger: 42
+          - linkId: anc.visits.followup
+            text: Follow-up antenatal visits
+            answer:
+              - valueInteger: 17
+          - linkId: anc.staff.count
+            text: Midwives on duty
+            answer:
+              - valueInteger: 3
+          # Answered, and mapped to nothing. It must not reach DHIS2, and it must not vanish
+          # in silence either: the translation counts it.
+          - linkId: anc.notes
+            text: Notes
+            answer:
+              - valueString: clinic closed on the 4th
+          # Asked and not answered. An absent answer and a zero are different facts.
+          - linkId: anc.visits.referred
+            text: Referrals
+
+  # The translation. It hands on the import document AND the drops beside it, so the receipt
+  # step below can report what did not map without re-deriving anything.
+  translate:
+    block: transform.jq
+    depends_on: [receive]
+    config:
+      input:
+        response: "${steps.receive.output.value}"
+        link_ids: "${params.link_ids}"
+        data_set: "${params.data_set}"
+        org_unit: "${params.org_unit}"
+        period: "${params.period}"
+      program: |
+        . as {$response, $link_ids, $data_set, $org_unit, $period}
+        | [$response.item[] | recurse(.item[]?) | select((.answer // []) | length > 0)] as $answered
+        | {document: {
+             dataSet: $data_set,
+             period: $period,
+             orgUnit: $org_unit,
+             dataValues: [
+               $answered[]
+               | select($link_ids[.linkId] != null)
+               | $link_ids[.linkId] as $cell
+               | (.answer[0] | (.valueDecimal // .valueInteger // .valueString // .valueBoolean)) as $v
+               | {dataElement: $cell.data_element, value: ($v | tostring)}
+                 + (if $cell.category_option_combo
+                    then {categoryOptionCombo: $cell.category_option_combo} else {} end)]},
+           unmapped: [$answered[] | select($link_ids[.linkId] == null) | .linkId]}
+
+  rehearse:
+    block: dhis2.data_value_set_import
+    depends_on: [translate]
+    config:
+      connection: dhis2-demo
+      data_values: "${steps.translate.output.value.document}"
+      # dryRun on /api/dataValueSets. The instance validates every value against the data set,
+      # the period and the org unit and reports conflicts, and writes nothing.
+      dry_run: true
+      atomic_mode: ALL
+
+  # What the run is for: the import summary's counts beside the linkIds nothing claimed. A
+  # growing `unmapped` list is the table falling behind the form, which is the failure mode
+  # this whole shape exists to make visible.
+  receipt:
+    block: transform.jq
+    depends_on: [rehearse]
+    config:
+      input:
+        summary: "${steps.rehearse.output}"
+        unmapped: "${steps.translate.output.value.unmapped}"
+      program: |
+        {rehearsed: .summary.status,
+         would_import: .summary.imported,
+         would_update: .summary.updated,
+         conflicts: (.summary.conflicts | length),
+         unmapped_link_ids: .unmapped}

dirigent_integration/shelves/fhir/fhir-subscription-webhook-to-dhis2.yaml

@@ -0,0 +1,218 @@
+# A FHIR Subscription notification delivered to a webhook, translated, and imported.
+#
+# THE FLOW, END TO END. A FHIR server holds a Subscription that watches for new captures. When
+# one arrives it POSTs a notification to this pipeline's webhook endpoint; the webhook maps the
+# notified resource onto a parameter, the document translates it into a data value set, and the
+# import runs as a dry run.
+#
+# THE SUBSCRIPTION CONTRACT, WHICH IS THE POINT OF THIS FILE. A FHIR Subscription is a standing
+# request: "when a resource matching this search appears, tell me here". Three fields carry it.
+#
+#   criteria      a search string, exactly as it would be typed against the server, e.g.
+#                 "QuestionnaireResponse?questionnaire=http://example.org/fhir/Questionnaire/lyLU2wR22tC"
+#   channel.type  how to be told. `rest-hook` is an HTTP POST, which is what a dirigent
+#                 webhook is; the others are websocket, email, and message.
+#   channel.endpoint  where to POST it -- the hooks URL the instance minted for this pipeline.
+#
+# What arrives in that POST depends on `channel.payload`, and the three choices are a real
+# decision rather than a formality:
+#
+#   absent          a PING. An empty body: "something matched, come and look". The pipeline
+#                   then has to search the server itself, which is more work and is also the
+#                   only choice that never puts patient data in a webhook body.
+#   id-only         the notification names the resource; the pipeline reads it back.
+#   full-resource   the resource rides in the notification. One request, no read-back, and
+#                   the delivery is now carrying clinical data -- so it is signed, and the
+#                   endpoint is not on the public internet.
+#
+# This document takes full-resource, because it is the shape that shows the whole translation
+# in one file. In R4 that body is the bare resource; R5 and the R4 backport wrap it in a
+# history Bundle whose first entry is a SubscriptionStatus and whose second is the resource,
+# which is the shape mapped below and the one most servers now send.
+#
+# `d2w fhir serve` HAS NO SUBSCRIPTION. Its capture surface is `POST /QuestionnaireResponse`
+# and its notification surface is the receipt spool -- `GET /facade/spool`, whose lifecycle
+# moves received -> forwarded or rejected. A pipeline pulls that spool on a schedule instead
+# (fhir-nightly-window-sync.yaml is that shape). This document is for the FHIR server that DOES
+# support Subscription, which is most of them, and it is written so the same translation serves
+# either way.
+#
+# WHAT ARRIVES. The notification body:
+#
+#   {"resourceType": "Bundle", "type": "history",
+#    "entry": [
+#      {"resource": {"resourceType": "SubscriptionStatus", "type": "event-notification",
+#                    "eventsSinceSubscriptionStart": "17"}},
+#      {"resource": {"resourceType": "QuestionnaireResponse", "status": "completed",
+#                    "questionnaire": ".../Questionnaire/lyLU2wR22tC",
+#                    "subject": {"reference": "Location/dczh6Jfd4no"},
+#                    "extension": [{"url": ".../d2-period",
+#                                   "extension": [{"url": "iso", "valueString": "202608"}]}],
+#                    "item": [...]}}]}
+#
+# WHAT LEAVES. The `/api/dataValueSets` envelope, same as every inbound document here:
+#
+#   {"dataSet": "lyLU2wR22tC", "period": "202608", "orgUnit": "dczh6Jfd4no",
+#    "dataValues": [{"dataElement": "GMd99K8gVut",
+#                    "categoryOptionCombo": "qNCMOhkoQju", "value": "426.3"}]}
+#
+# WHERE A READER CHANGES IT. The webhook's `params_from_payload` at the foot of this file, and
+# nothing else. The mapping is STRICT: each parameter names one dotted path into the body, a
+# path the body does not have refuses the delivery, and a parameter the mapping does not
+# mention cannot be reached by any caller whatever they POST. A server sending the bare R4
+# resource rather than a Bundle changes `capture` to `$` -- which this syntax spells as the
+# resource's own top-level keys, so the mapping names them.
+#
+# WHAT LIVES ON THE INSTANCE AND NOT IN GIT. The endpoint's token, whether it is active, and
+# every delivery it has taken. `dg webhook rotate-token` shows a token exactly once.
+#
+#   dg run --local examples/fhir/fhir-subscription-webhook-to-dhis2.yaml
+#
+# Against an instance, where the endpoint exists:
+#
+#   dg apply examples/fhir/fhir-subscription-webhook-to-dhis2.yaml
+#   dg webhook rotate-token fhir-subscription-webhook-to-dhis2 fhir-notification
+#   curl -X POST "$DG_URL/hooks/$TOKEN" -H 'Content-Type: application/json' --data @notification.json
+
+format: dirigent/v1
+kind: pipeline
+code: fhir-subscription-webhook-to-dhis2
+name: A FHIR Subscription notification imported
+description: |
+  Take a FHIR `Subscription` rest-hook notification on a webhook, translate the notified
+  `QuestionnaireResponse` into a DHIS2 data value set, and rehearse the import.
+
+  The subscription contract is three fields: `criteria` (a search string), `channel.type`
+  (`rest-hook` is an HTTP POST), and `channel.endpoint` (the hooks URL). `channel.payload`
+  decides whether the delivery is a ping, an id, or the resource itself -- this takes the
+  resource, wrapped in the history `Bundle` R5 and the R4 backport send.
+
+tags: [fhir, dhis2, cross-boundary]
+
+requires:
+  blocks:
+    - transform.jq
+    - dhis2.data_value_set_import
+
+connections:
+  dhis2-demo:
+    kind: dhis2
+    config:
+      base_url: https://play.im.dhis2.org/stable-2-43-1
+      basic_username: admin
+      basic_password: district
+      timeout: 60s
+
+params:
+  type: object
+  properties:
+    capture:
+      type: object
+      description: The notified QuestionnaireResponse. The default is what a delivery would
+        have carried, so the document runs without one.
+      default:
+        resourceType: QuestionnaireResponse
+        status: completed
+        authored: "2026-08-31T09:00:00Z"
+        questionnaire: http://example.org/fhir/Questionnaire/lyLU2wR22tC
+        subject:
+          reference: Location/dczh6Jfd4no
+        extension:
+          - url: http://example.org/fhir/StructureDefinition/d2-period
+            extension:
+              - url: iso
+                valueString: "202608"
+              - url: type
+                valueCode: Monthly
+          - url: http://example.org/fhir/StructureDefinition/d2-attribute-option-combo
+            valueCoding:
+              code: N7QFN41eTN8
+        item:
+          - linkId: GMd99K8gVut
+            item:
+              - linkId: GMd99K8gVut.qNCMOhkoQju
+                answer:
+                  - valueDecimal: 426.3
+              - linkId: GMd99K8gVut.LbeIlyHEhKr
+                answer:
+                  - valueDecimal: 628.2
+          - linkId: wfKKFhBn0Q0
+            answer:
+              - valueDecimal: 142.1
+    events_since_start:
+      type: string
+      description: The SubscriptionStatus counter. A gap between two deliveries means a
+        notification was lost, which is the only way this channel says so.
+      default: "0"
+
+steps:
+  # Only a completed response is translated. An in-progress one is a form still being filled,
+  # and a notification is allowed to fire on it -- `criteria` matches a resource, not a state.
+  translate:
+    block: transform.jq
+    config:
+      input: "${params.capture}"
+      program: |
+        if .status != "completed" then
+          error("the notified response is \(.status), not completed; nothing to import")
+        else . end
+        | . as $r
+        | {dataSet: ($r.questionnaire | split("/") | last),
+           period: ([$r.extension[] | select(.url | endswith("/d2-period")).extension[]
+                     | select(.url == "iso").valueString][0]),
+           orgUnit: ($r.subject.reference | ltrimstr("Location/")),
+           attributeOptionCombo: (
+             [$r.extension[] | select(.url | endswith("/d2-attribute-option-combo"))][0]
+             | .valueCoding.code),
+           dataValues: [
+             $r.item[] | recurse(.item[]?)
+             | select((.answer // []) | length > 0)
+             | (.linkId | split(".")) as $key
+             | (.answer[0] | (.valueDecimal // .valueInteger // .valueString // .valueBoolean)) as $v
+             | {dataElement: $key[0], value: ($v | tostring)}
+               + (if ($key | length) > 1 then {categoryOptionCombo: $key[1]} else {} end)]}
+        | del(.attributeOptionCombo | select(. == null))
+
+  # A notification arrives once and is not replayed, so the import's retry budget is what
+  # stands between a momentary DHIS2 and a lost capture. dry_run makes this a rehearsal;
+  # dropping it is the whole difference between this document and a live forwarder.
+  rehearse:
+    block: dhis2.data_value_set_import
+    depends_on: [translate]
+    retry:
+      # The budget counts the first try, so this is one attempt and two retries.
+      max_attempts: 3
+      backoff: 5s
+    config:
+      connection: dhis2-demo
+      data_values: "${steps.translate.output.value}"
+      dry_run: true
+      atomic_mode: ALL
+
+  receipt:
+    block: transform.jq
+    depends_on: [rehearse]
+    config:
+      input:
+        summary: "${steps.rehearse.output}"
+        events_since_start: "${params.events_since_start}"
+        document: "${steps.translate.output.value}"
+      program: |
+        {notification: .events_since_start,
+         data_set: .document.dataSet,
+         period: .document.period,
+         org_unit: .document.orgUnit,
+         status: .summary.status,
+         would_import: .summary.imported,
+         conflicts: (.summary.conflicts | length)}
+
+triggers:
+  webhooks:
+    # The whole declaration. `capture` takes the notified resource out of the history Bundle's
+    # second entry -- the first is the SubscriptionStatus -- and the counter comes off that
+    # status. Both are validated against params above before a run is created, so a delivery
+    # that does not carry them is refused rather than half-run.
+    - code: fhir-notification
+      params_from_payload:
+        capture: "$.entry.1.resource"
+        events_since_start: "$.entry.0.resource.eventsSinceSubscriptionStart"

dirigent_integration/shelves/inbound/README.md

@@ -0,0 +1,32 @@
+# Inbound examples
+
+Eight pipelines going the same direction: an outside system, a transform, DHIS2. They are
+authored here rather than in a pack because each one spans several -- the http, storage,
+transform and parquet blocks the runtime contributes, feeding the blocks `dirigent-dhis2`
+contributes -- and no single pack can hold, or test, a pipeline that needs them all.
+
+Every one of them:
+
+- names every block it uses under `requires: blocks:`, so an environment missing one refuses
+  the document rather than failing halfway through a run;
+- carries its DHIS2 connection in the document, pointed at the public play server, so
+  `dg run --local <file>` works with nothing applied and nothing configured;
+- imports with `dry_run` defaulting to true. The play server is shared: leave it that way
+  there, and turn it off against an instance of your own;
+- uses ids that exist on the demo. `WUg3MYWQ7pt` (Total Population, yearly) and
+  `x0PshcPLSk1` / `wZqi8EXN5x4` (PMTCT monthly) at Ngelehun CHC, `DiszpKrYNg8`, are the
+  defaults, because those are elements the demo will actually accept values for.
+
+The two that read object storage need an `s3` connection bound to the scheme as an instance
+setting (`storage_connections: {s3: <code>}`); the rest need only a network.
+
+| Example | What it teaches |
+| --- | --- |
+| [`http-json-to-data-values.yaml`](http-json-to-data-values.yaml) | The shortest inbound path: pull a public JSON API, reshape it, gate it on DHIS2's own id and period formats, import it as a dry run. |
+| [`csv-drop-to-data-values.yaml`](csv-drop-to-data-values.yaml) | The file drop: wait for a csv to land in a bucket, decode it, translate the sender's codes to uids through a lookup, drop the rows that carry no measurement. |
+| [`webhook-payload-to-tracker-event.yaml`](webhook-payload-to-tracker-event.yaml) | Push instead of poll: a webhook maps one posted encounter onto parameters, and that mapping is the whole security boundary. |
+| [`parquet-lakehouse-to-dhis2.yaml`](parquet-lakehouse-to-dhis2.yaml) | Grain: a parquet table of encounter-level rows reduced to the figures DHIS2 stores, then a completeness sensor that observes rather than registers. |
+| [`fhir-observations-to-data-values.yaml`](fhir-observations-to-data-values.yaml) | Two standards meeting: LOINC codes mapped onto data elements, instants truncated to periods, and the org unit the payload cannot supply. |
+| [`weekly-window-pull-and-import.yaml`](weekly-window-pull-and-import.yaml) | The window: a schedule whose runs pull the week that closed, `${run.window.start}` to `${run.window.end}`, so a late run and a backfill read the same week. |
+| [`fan-out-per-facility-import.yaml`](fan-out-per-facility-import.yaml) | One call per facility with `items: continue`, why the fan converges before the import, and a reconciliation of asked-for against answered. |
+| [`outside-to-dhis2-with-checks.yaml`](outside-to-dhis2-with-checks.yaml) | Every guard at once: a readiness sensor, a schema on what arrived, a schema on what was built, a rehearsed import, and the real one behind it. |