dirigent-integration 0.23.2__py3-none-any.whl

dirigent_integration/shelves/dhis2-values-per-org-unit-to-parquet.yaml

@@ -0,0 +1,186 @@
+# One export per organisation unit, flattened into one parquet table, with a manifest.
+#
+# The single-org-unit version of this is dhis2-values-to-parquet.yaml beside it. This is the
+# shape a real extraction has: a list of facilities or districts, one read each, one table at
+# the end, and something that says what actually landed. It spans three packs -- dhis2 for the
+# reads, parquet for the encoding, storage-s3 for both destinations -- so it belongs to none of
+# them and is authored here.
+#
+# WHY ONE TABLE AND NOT ONE FILE PER ORG UNIT. A value moves through step outputs, and a value
+# leaves a run through storage.write; a block does not write storage itself. A fan-out step
+# stores one output -- the list of its items' outputs, in item order, with a failed item absent
+# from it -- and `for_each` is expanded when the run is created, so it can read params, run and
+# item and never an upstream step's output. Item three of one step therefore cannot ask item
+# three of another what it produced: a second fan cannot pick up the export its twin made. So
+# the fan-in is a single step over every export, and the org unit is read out of each data
+# value where the join key can be seen, rather than out of a storage path that used to carry it.
+#
+# What happens, hop by hop:
+#
+#   export      one dhis2.data_value_set_export per org unit. Each item answers `body`, the
+#               data value set as a value. items: continue means one facility going quiet --
+#               a credential that cannot read it, an instance that times out on one subtree --
+#               does not cost the others their export; the run ends completed_with_errors and
+#               the failed item is simply absent from this step's output list.
+#   rows        the fan-in: every set this step is handed, opened at .dataValues and flattened
+#               into one table sorted by org unit and data element.
+#   staged      storage.write, that table as one json object. A converter reads one URI and
+#               writes another, so a value the run is holding is put down before it is
+#               re-encoded. Output: uri, bytes_written, content_type.
+#   parquet     convert.arrow, json to parquet. Parquet is bytes and never travels as a value:
+#               the step names a source URI and a target URI and carries nothing between them.
+#               Output: source, target, bytes_written.
+#   manifest    what the run has to say for itself: how many org units were asked for, how many
+#               answered, how many rows landed, and where the file is.
+#   index       that manifest written beside the parquet, at a stable URI. This is the artifact
+#               a downstream reader opens first to learn what a run produced without listing a
+#               bucket.
+#   archive     a second, dated copy of the manifest, so the history of what each run landed
+#               survives the next run overwriting the current one.
+#
+# To make it yours: change org_units, data_set and period, and point bucket at a bucket you
+# own. Which connection backs the s3:// scheme is an instance setting
+# (storage_connections: {s3: <code>}), so nothing about S3 appears in this document beyond
+# the URIs. The dhis2 connection below is the public play server, carried inline so the
+# document runs standalone; an instance you own names its own connection instead.
+#
+#   dg run --local examples/dhis2-values-per-org-unit-to-parquet.yaml
+#   dg run --local examples/dhis2-values-per-org-unit-to-parquet.yaml -p period=202506
+
+format: dirigent/v1
+kind: pipeline
+code: dhis2-values-per-org-unit-to-parquet
+name: A parquet table over a batch of org units
+description: Export a data value set per organisation unit, flatten the batch into one parquet table, and manifest what landed.
+
+tags: [dhis2, parquet, s3, cross-boundary]
+
+requires:
+  blocks:
+    - dhis2.data_value_set_export
+    - transform.jq
+    - storage.write
+    - convert.arrow
+    - storage.copy
+
+# The public DHIS2 play server, carried inline so this document runs on its own. A server
+# apply is where a connection is named rather than carried.
+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:
+    org_units:
+      type: array
+      # Facilities and districts that exist on the play server. The list is the fan-out's
+      # width: four elements here are four run items and four reads.
+      default: [vSbt6cezomG, DiszpKrYNg8, O6uvpzGd5pu, ImspTQPwCqd]
+      items:
+        type: string
+    data_set:
+      type: string
+      default: BfMAe6Itzgt
+    period:
+      type: string
+      default: "202507"
+      description: An ISO period identifier, such as 202507 or 2026Q1.
+    bucket:
+      type: string
+      default: dirigent-exports
+
+steps:
+  export:
+    block: dhis2.data_value_set_export
+    for_each: ${params.org_units}
+    items: continue
+    config:
+      connection: dhis2-demo
+      data_set: ${params.data_set}
+      period: ${params.period}
+      org_unit: ${item}
+
+  rows:
+    block: transform.jq
+    depends_on: [export]
+    config:
+      # One fan-out step, one output: the list of what its items answered. An org unit whose
+      # item failed is simply not in it, and an org unit with nothing reported answers a set
+      # with no dataValues, which is why the flattening tolerates both.
+      input: ${steps.export.output}
+      program: |
+        [.[]
+         | .body
+         | (.dataValues // [])[]
+         | {org_unit: .orgUnit,
+            data_element: .dataElement,
+            category_option_combo: .categoryOptionCombo,
+            period: .period,
+            value: .value,
+            stored_by: .storedBy,
+            last_updated: .lastUpdated}]
+        | sort_by(.org_unit, .data_element, .category_option_combo)
+
+  staged:
+    block: storage.write
+    depends_on: [rows]
+    config:
+      target: s3://${params.bucket}/dhis2/${params.data_set}/${params.period}/values.json
+      value: ${steps.rows.output.value}
+
+  parquet:
+    block: convert.arrow
+    depends_on: [staged]
+    config:
+      source: ${steps.staged.output.uri}
+      from: json
+      to: parquet
+      target: s3://${params.bucket}/dhis2/${params.data_set}/${params.period}/values.parquet
+
+  manifest:
+    block: transform.jq
+    depends_on: [export, rows, parquet]
+    config:
+      # `answered` is shorter than `asked_for` exactly when an item failed, which is the only
+      # place in the run where that difference is visible as data rather than as a status.
+      input:
+        data_set: ${params.data_set}
+        period: ${params.period}
+        asked_for: ${params.org_units}
+        answered: ${steps.export.output}
+        rows: ${steps.rows.output.value}
+        file: ${steps.parquet.output.target}
+        bytes: ${steps.parquet.output.bytes_written}
+      program: |
+        {
+          data_set,
+          period,
+          file,
+          bytes,
+          asked_for: (.asked_for | length),
+          answered: (.answered | length),
+          rows: (.rows | length),
+          org_units: ([.rows[].org_unit] | unique)
+        }
+
+  index:
+    block: storage.write
+    depends_on: [manifest]
+    config:
+      target: s3://${params.bucket}/dhis2/${params.data_set}/${params.period}/_manifest.json
+      value: ${steps.manifest.output.value}
+
+  archive:
+    block: storage.copy
+    depends_on: [index]
+    config:
+      source: ${steps.index.output.uri}
+      # Keyed by the run, so today's manifest does not overwrite yesterday's. The current
+      # manifest above stays at a stable URI for anything that just wants the latest.
+      target: s3://dirigent-archive/dhis2/${params.data_set}/${params.period}/${run.id}.json

dirigent_integration/shelves/dhis2-values-to-parquet.yaml

@@ -0,0 +1,64 @@
+# Export a DHIS2 data value set and re-encode it as parquet in object storage.
+#
+# Three packs meet in this one pipeline, which is why it lives here and in no pack: the read
+# is dhis2.data_value_set_export from the dhis2 pack, the re-encode is convert.arrow from the
+# parquet pack, and both ends address the s3:// scheme the dirigent-storage-s3 pack contributes.
+#
+# Three hops, and what each one hands on:
+#
+#   export      dhis2.data_value_set_export. The set comes back as `body`, a value in the run.
+#   stage       storage.write, that value as one JSON object. A converter reads a URI, so a
+#               value the run is holding is put down before it is re-encoded.
+#   to_parquet  convert.arrow, json to parquet. Parquet is bytes and never travels as a value:
+#               the step names a source URI and a target URI and carries nothing between them.
+#               Output: source, target, bytes_written.
+#
+# Which connection backs s3:// is an instance setting (storage_connections: {s3: <code>}).
+#
+#   dg run --local examples/dhis2-values-to-parquet.yaml
+
+format: dirigent/v1
+kind: pipeline
+code: dhis2-values-to-parquet
+name: Export a data value set as parquet
+description: Read a DHIS2 data value set into object storage, then re-encode it as parquet beside it.
+
+tags: [dhis2, parquet, s3, cross-boundary]
+
+requires:
+  blocks:
+    - dhis2.data_value_set_export
+    - storage.write
+    - convert.arrow
+
+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
+
+steps:
+  export:
+    block: dhis2.data_value_set_export
+    config:
+      connection: dhis2-demo
+      data_set: BfMAe6Itzgt
+      period: "202507"
+      org_unit: vSbt6cezomG
+  stage:
+    block: storage.write
+    depends_on: [export]
+    config:
+      target: s3://dirigent-exports/dhis2/BfMAe6Itzgt-202507.json
+      value: ${steps.export.output.body}
+  to_parquet:
+    block: convert.arrow
+    depends_on: [stage]
+    config:
+      source: ${steps.stage.output.uri}
+      from: json
+      to: parquet
+      target: s3://dirigent-exports/dhis2/BfMAe6Itzgt-202507.parquet

dirigent_integration/shelves/fhir/README.md

@@ -0,0 +1,79 @@
+# FHIR examples
+
+Pipelines that move data between a FHIR endpoint and a DHIS2 instance. They are cross-boundary
+twice over: the DHIS2 blocks come from the `dirigent-dhis2` pack, the HTTP, transform and
+validate blocks from the runtime, and neither knows the other exists -- only an assembled
+environment runs any of these at all.
+
+Most of them read a `d2w fhir serve` facade, which publishes one DHIS2 instance as a FHIR
+endpoint and takes captures back. Two are running on this machine at `http://localhost:8095`
+and `http://localhost:8096`; `fhir_base` defaults to the first, so every read below works
+against a real server. Where a general-purpose FHIR server is the point -- an Encounter, an
+Observation, a Subscription, a `_lastUpdated` search, none of which the facade serves -- the
+default is the public HAPI R4 sandbox at `https://hapi.fhir.org/baseR4` instead, and the
+document's header says why.
+
+No document here imports for real without being told to. Every write is a dry run:
+`dryRun=true` on `/api/dataValueSets` and `importMode=VALIDATE` on `/api/tracker`. Those are
+two spellings of one intention on two endpoints of the same server, and reaching for the wrong
+one does not fail -- it imports.
+
+## The mapping vocabulary
+
+Three words carry the whole translation, and they are worth learning once.
+
+**Subject.** Every capture is *about* something, and which something depends on the form.
+An aggregate or event form is answered for a place, so its `subject` is a literal
+`Reference(Location/<orgUnitUid>)` and the DHIS2 org unit is read straight out of it. A tracker
+form is answered about a person, so its `subject` is a *logical* reference -- `subject.type`
+`Patient` and `subject.identifier` under `http://dhis2.org/fhir/id/tracked-entity`, with no
+`reference` at all -- and the org unit rides on a `D2OrganisationUnit` extension instead. Two
+shapes, one field, and mixing them up is the first thing a facade refuses.
+
+**Capture.** The capture pair is `Questionnaire` and `QuestionnaireResponse`. A `Questionnaire`
+is a form *definition* generated from DHIS2 metadata: one per aggregate data set, event program,
+tracker program, program stage, or tracked entity type. A `QuestionnaireResponse` is one
+*submission* against it, answering item by item on the same `linkId`s. Those linkIds are DHIS2
+uids -- a plain one is a data element, and a dotted one, `<dataElement>.<categoryOptionCombo>`,
+is a single disaggregated cell -- which is what makes a response readable back into DHIS2
+without consulting the form. Everything DHIS2 has and FHIR has no field for rides as a named
+extension: `D2Period` carries the ISO period, `D2AttributeOptionCombo` the attribute option
+combo, `D2TrackerEnrollment` the enrollment. A capture reaches the facade one resource per
+`POST /QuestionnaireResponse`; there is no batch, and nothing reaches DHIS2 at capture time --
+the facade holds a receipt whose lifecycle moves `received` to `forwarded` or `rejected`.
+
+**ConceptMap.** A published, versioned, addressable translation between two code systems. The
+facade emits one per DHIS2 option set, with two groups distinguished by `group.target`: one to
+the DHIS2 option uid, always complete, and one to the DHIS2 option code, only where an option
+has one. Fetching the map at run time instead of writing a lookup into a document is the
+difference between a mapping that can drift and one that cannot: an option added to a DHIS2
+option set is in the regenerated map, and the pipeline that reads it needs no edit.
+
+## Pipelines
+
+| File | What it teaches |
+| --- | --- |
+| [fhir-capture-bundle-to-data-values.yaml](fhir-capture-bundle-to-data-values.yaml) | The capture pair end to end: a page of `QuestionnaireResponse` captures pulled off the facade, translated to `/api/dataValueSets`, gated on the pack's `dhis2-uid` and `dhis2-period` formats, rehearsed and then imported. |
+| [fhir-questionnaire-response-to-data-values.yaml](fhir-questionnaire-response-to-data-values.yaml) | The general case, where a `linkId` is a form designer's name rather than a DHIS2 uid: an explicit lookup in params, and every unmapped answer counted rather than dropped in silence. |
+| [fhir-patient-to-tracked-entity.yaml](fhir-patient-to-tracked-entity.yaml) | The `Patient` register searched by identifier and folded into an `/api/tracker` registration -- and why the write is an `http.request` on the `dhis2` connection, because `dhis2.tracker` reads and does not write. |
+| [fhir-encounter-to-event.yaml](fhir-encounter-to-event.yaml) | Cardinalities that do not line up: one `Encounter` plus every `Observation` naming it, folded into the single program stage event DHIS2 wants, with the LOINC codes mapped and the rest reported. |
+| [fhir-conceptmap-driven-mapping.yaml](fhir-conceptmap-driven-mapping.yaml) | The mapping fetched rather than written: a `ConceptMap` flattened into a lookup at run time, applied to coded answers, with `equivalence` honoured so an inexact match is reported instead of imported. |
+| [fhir-measure-report-to-analytics-check.yaml](fhir-measure-report-to-analytics-check.yaml) | A reconciliation that writes nothing: a `MeasureReport` held against `dhis2.analytics_query` for the same period and org unit, and the gap delivered by `webhook.post` whether or not there is one. |
+| [dhis2-to-fhir-observations.yaml](dhis2-to-fhir-observations.yaml) | The outbound direction: a data value set published as a transaction `Bundle` of `Observation`s, each a conditional update keyed on the aggregate cell's natural key so republishing updates rather than duplicates. |
+| [fhir-subscription-webhook-to-dhis2.yaml](fhir-subscription-webhook-to-dhis2.yaml) | The subscription contract -- `criteria`, `channel.type`, `channel.endpoint`, and what `channel.payload` decides -- landing on a webhook whose payload mapping is strict enough that no caller can reach a parameter it does not name. |
+| [fhir-nightly-window-sync.yaml](fhir-nightly-window-sync.yaml) | The interval a firing covers rather than the moment it fired at: a half-open `_lastUpdated` range, a fan-out per resource type under `items: continue`, and a join under `rule: all_done` that says what it did not reach. |
+
+## Running them
+
+```bash
+dg run --local examples/fhir/fhir-capture-bundle-to-data-values.yaml
+dg run --local examples/fhir/fhir-conceptmap-driven-mapping.yaml \
+  -p target_system=http://dhis2.org/fhir/id/option-code
+```
+
+One of them reads the window its firing covers, which no document declares and only a run
+carries, so an ad hoc run has to say which interval it is for:
+
+```bash
+dg run --local examples/fhir/fhir-nightly-window-sync.yaml --window 2026-09-01..2026-09-02
+```

dirigent_integration/shelves/fhir/dhis2-to-fhir-observations.yaml

@@ -0,0 +1,212 @@
+# The other direction: DHIS2 aggregate values published as a FHIR Bundle of Observations.
+#
+# THE FLOW, END TO END. Export one data value set from DHIS2, turn every data value into an
+# Observation, wrap them in a transaction Bundle, and POST that Bundle to a FHIR server.
+#
+# WHY IT IS HERE. Every other document on this shelf reads FHIR and writes DHIS2. This one is
+# the mirror, and a reader who has both in front of them can see what is symmetric and what is
+# not. What is symmetric: the value, the period, the org unit, the code. What is NOT: DHIS2
+# says "this cell of this data set for this period", one row; FHIR says "this observation about
+# this subject at this time", one resource. Aggregate goes to FHIR by inventing an Observation
+# per cell whose subject is a place rather than a person -- which is legal, and is what
+# `Observation.subject` referencing a Location means.
+#
+# WHAT ARRIVES. A `/api/dataValueSets` export:
+#
+#   {"dataSet": "BfMAe6Itzgt", "period": "202608", "orgUnit": "vSbt6cezomG",
+#    "dataValues": [{"dataElement": "s46m5MS0hxu", "period": "202608",
+#                    "orgUnit": "vSbt6cezomG", "categoryOptionCombo": "Prlt0C1RF0s",
+#                    "value": "12"}]}
+#
+# WHAT LEAVES. A transaction Bundle, one entry per data value:
+#
+#   {"resourceType": "Bundle", "type": "transaction",
+#    "entry": [{"request": {"method": "POST", "url": "Observation"},
+#               "resource": {
+#                 "resourceType": "Observation", "status": "final",
+#                 "identifier": [{"system": "http://dhis2.org/fhir/id/data-value",
+#                                 "value": "s46m5MS0hxu.Prlt0C1RF0s-202608-vSbt6cezomG"}],
+#                 "code": {"coding": [{"system": "http://dhis2.org/fhir/id/data-element",
+#                                      "code": "s46m5MS0hxu"}]},
+#                 "subject": {"reference": "Location/vSbt6cezomG"},
+#                 "effectivePeriod": {"start": "2026-08-01", "end": "2026-08-31"},
+#                 "valueQuantity": {"value": 12}}}]}
+#
+# WHICH FIELD BECOMES WHICH.
+#
+#   dataElement                     -> Observation.code.coding, system .../id/data-element
+#   categoryOptionCombo             -> a second coding, system .../id/category-option-combo,
+#                                      because the disaggregation is part of what was counted
+#   orgUnit                         -> Observation.subject, a Reference(Location)
+#   period                          -> Observation.effectivePeriod, resolved to real dates
+#   value                           -> valueQuantity.value, or valueString when it is not a number
+#   (dataElement.coc, period, ou)   -> Observation.identifier, so a re-publish updates rather
+#                                      than duplicates
+#
+# THAT IDENTIFIER IS THE WHOLE IDEMPOTENCY STORY. An aggregate cell has a natural key and FHIR
+# has a place to put it, so each entry uses `PUT` with a conditional-update url --
+# `Observation?identifier=<system>|<key>` -- rather than POST. Running this document twice
+# leaves one Observation per cell, not two. A server that does not implement conditional update
+# refuses the Bundle rather than silently duplicating, which is the right failure.
+#
+# WHERE A READER CHANGES IT. `data_set`, `period` and `org_unit` pick what is exported;
+# `identifier_base` is the system every identifier and code is minted under, and it must be the
+# same base the FHIR side of your project already uses.
+#
+#   dg run --local examples/fhir/dhis2-to-fhir-observations.yaml
+#   dg run --local examples/fhir/dhis2-to-fhir-observations.yaml -p period=202507
+
+format: dirigent/v1
+kind: pipeline
+code: dhis2-to-fhir-observations
+name: DHIS2 data values to FHIR Observations
+description: |
+  Export a DHIS2 data value set and publish it as a transaction `Bundle` of `Observation`
+  resources on a FHIR server.
+
+  The outbound half of this shelf. Each entry is a conditional update keyed on the aggregate
+  cell's natural key -- `(dataElement.categoryOptionCombo, period, orgUnit)` -- so publishing
+  twice updates rather than duplicates.
+
+tags: [fhir, dhis2, cross-boundary]
+
+requires:
+  blocks:
+    - dhis2.data_value_set_export
+    - transform.jq
+    - http.request
+
+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
+  # A public FHIR R4 sandbox, open to anyone, which is exactly why the Bundle below is keyed:
+  # a shared server that everybody publishes to is where duplicate-on-republish shows up first.
+  fhir-target:
+    kind: http
+    config:
+      base_url: https://hapi.fhir.org/baseR4
+      timeout: 60s
+
+params:
+  type: object
+  properties:
+    data_set:
+      type: string
+      default: BfMAe6Itzgt
+    period:
+      type: string
+      description: A DHIS2 ISO period. The Observation carries the dates it resolves to.
+      default: "202608"
+    org_unit:
+      type: string
+      default: vSbt6cezomG
+    identifier_base:
+      type: string
+      description: The system every minted identifier and code hangs off. Match it to whatever
+        the FHIR side of your project already publishes under.
+      default: http://dhis2.org/fhir
+
+steps:
+  # The export hands the set on as `body`, a value, and the next step is a jq program that
+  # wants exactly that. A national export over a year is the case for putting it down with a
+  # storage.write first and converting from there, so nothing holds it whole.
+  export:
+    block: dhis2.data_value_set_export
+    config:
+      connection: dhis2-demo
+      data_set: "${params.data_set}"
+      period: "${params.period}"
+      org_unit: "${params.org_unit}"
+      children: false
+
+  to_observation_bundle:
+    block: transform.jq
+    depends_on: [export]
+    config:
+      input:
+        export: "${steps.export.output.body}"
+        base: "${params.identifier_base}"
+        period: "${params.period}"
+        org_unit: "${params.org_unit}"
+      program: |
+        . as {$export, $base, $period, $org_unit}
+        # A DHIS2 monthly period is yyyyMM and carries no dates, so the range is derived. Only
+        # Monthly is handled here; a quarterly or weekly set needs its own arm, which is the
+        # honest shape -- there are 23 DHIS2 period types and none of them is guessable.
+        | ($period | .[0:4]) as $year
+        | ($period | .[4:6]) as $month
+        | (if ($period | length) == 6 then
+             {start: "\($year)-\($month)-01",
+              end: ("\($year)-\($month)-01" | strptime("%Y-%m-%d") | mktime
+                    | . + (32 * 86400) | strftime("%Y-%m-01")
+                    | strptime("%Y-%m-%d") | mktime | . - 86400 | strftime("%Y-%m-%d"))}
+           else null end) as $range
+        | {resourceType: "Bundle",
+           type: "transaction",
+           entry: [($export.dataValues // [])[]
+             | . as $v
+             | (if .categoryOptionCombo
+                then "\(.dataElement).\(.categoryOptionCombo)" else .dataElement end) as $cell
+             # A data value repeats the envelope's period and org unit only when the export
+             # broke them down; a single-cell-block export leaves them off every row, and the
+             # envelope is then the only place they are. Both are read with that fallback.
+             | ($v.period // $export.period // $period) as $value_period
+             | ($v.orgUnit // $export.orgUnit // $org_unit) as $value_org_unit
+             | "\($cell)-\($value_period)-\($value_org_unit)" as $key
+             | {# A conditional update, not a create: the natural key decides identity, so the
+                # server updates the Observation that already carries it or creates the first.
+                request: {method: "PUT",
+                          url: "Observation?identifier=\($base)/id/data-value|\($key)"},
+                resource: ({
+                  resourceType: "Observation",
+                  status: "final",
+                  identifier: [{system: "\($base)/id/data-value", value: $key}],
+                  code: {coding: (
+                    [{system: "\($base)/id/data-element", code: $v.dataElement}]
+                    + (if $v.categoryOptionCombo
+                       then [{system: "\($base)/id/category-option-combo",
+                              code: $v.categoryOptionCombo}] else [] end))},
+                  subject: {reference: "Location/\($value_org_unit)"}}
+                  + (if $range then {effectivePeriod: $range} else {} end)
+                  # A DHIS2 value is always a string on the wire. A number becomes a Quantity
+                  # and anything else stays a string, because coercing a coded answer or a
+                  # free-text comment into a number would be inventing a measurement.
+                  + (if ($v.value | tonumber? ) != null
+                     then {valueQuantity: {value: ($v.value | tonumber)}}
+                     else {valueString: $v.value} end))}]}
+
+  # A transaction is all-or-nothing: the server applies every entry or none of them, and
+  # answers a transaction-response Bundle with one entry per request. That is the right
+  # granularity for one org unit and one period -- the whole month lands or the whole month
+  # does not -- and the wrong one for a year, which wants a batch per period instead.
+  publish:
+    block: http.request
+    depends_on: [to_observation_bundle]
+    config:
+      connection: fhir-target
+      path: /
+      method: POST
+      headers:
+        Content-Type: application/fhir+json
+        Accept: application/fhir+json
+      body: "${steps.to_observation_bundle.output.value}"
+
+  # The transaction response, read as a verdict rather than a status code: each entry carries
+  # its own `response.status`, and a 201 and a 200 mean created and updated respectively.
+  receipt:
+    block: transform.jq
+    depends_on: [publish]
+    config:
+      input: "${steps.publish.output.body}"
+      program: |
+        {bundle: .type,
+         entries: ((.entry // []) | length),
+         created: [(.entry // [])[] | select(.response.status | startswith("201"))] | length,
+         updated: [(.entry // [])[] | select(.response.status | startswith("200"))] | length,
+         issues: [(.entry // [])[] | select(.response.outcome.issue != null)
+                  | .response.outcome.issue[] | {severity, code, diagnostics}]}