dirigent-integration 0.26.0__tar.gz → 0.27.0__tar.gz

{dirigent_integration-0.26.0 → dirigent_integration-0.27.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: dirigent-integration
-Version: 0.26.0
+Version: 0.27.0
 Summary: The control center for the dirigent plugin ecosystem: assemble every pack, run everyone's tests and examples together.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
-Requires-Dist: dirigent-plugin==0.26.0
+Requires-Dist: dirigent-plugin==0.27.0
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 
@@ -160,8 +160,8 @@ vocabulary the shelf is built on -- subject, capture, ConceptMap.
   `dhis2.analytics_query` for the same period, and the gap delivered by `webhook.post`.
 - **`examples/fhir/dhis2-to-fhir-observations.yaml`** -- the outbound leg: a data value set
   published as a transaction `Bundle` of conditionally-updated `Observation`s.
-- **`examples/fhir/fhir-subscription-webhook-to-dhis2.yaml`** -- the subscription contract,
-  landing on a webhook whose payload mapping no caller can reach past.
+- **`examples/fhir/fhir-subscription-to-dhis2.yaml`** -- the subscription contract, landing on
+  an endpoint source whose first step picks the only fields any later step sees.
 - **`examples/fhir/fhir-nightly-window-sync.yaml`** -- a half-open `_lastUpdated` window, a
   fan-out per resource type under `items: continue`, and a join that says what it missed.
 
@@ -169,7 +169,7 @@ vocabulary the shelf is built on -- subject, capture, ConceptMap.
 
 `examples/inbound/` is a shelf of eight pipelines going one direction -- an outside system, a
 transform, DHIS2 -- teaching the shapes an inbound integration actually takes: a public JSON
-API, a csv dropped in a bucket, a pushed webhook, a parquet table from a lakehouse, a FHIR
+API, a csv dropped in a bucket, an encounter pushed to an endpoint, a parquet table from a lakehouse, a FHIR
 Observation feed, a windowed weekly pull, a fan-out across facilities, and the defensive
 version with every guard on. Each names every block it needs, carries its DHIS2 connection
 pointed at the public play server, and imports as a dry run by default, so

{dirigent_integration-0.26.0 → dirigent_integration-0.27.0}/README.md

@@ -150,8 +150,8 @@ vocabulary the shelf is built on -- subject, capture, ConceptMap.
   `dhis2.analytics_query` for the same period, and the gap delivered by `webhook.post`.
 - **`examples/fhir/dhis2-to-fhir-observations.yaml`** -- the outbound leg: a data value set
   published as a transaction `Bundle` of conditionally-updated `Observation`s.
-- **`examples/fhir/fhir-subscription-webhook-to-dhis2.yaml`** -- the subscription contract,
-  landing on a webhook whose payload mapping no caller can reach past.
+- **`examples/fhir/fhir-subscription-to-dhis2.yaml`** -- the subscription contract, landing on
+  an endpoint source whose first step picks the only fields any later step sees.
 - **`examples/fhir/fhir-nightly-window-sync.yaml`** -- a half-open `_lastUpdated` window, a
   fan-out per resource type under `items: continue`, and a join that says what it missed.
 
@@ -159,7 +159,7 @@ vocabulary the shelf is built on -- subject, capture, ConceptMap.
 
 `examples/inbound/` is a shelf of eight pipelines going one direction -- an outside system, a
 transform, DHIS2 -- teaching the shapes an inbound integration actually takes: a public JSON
-API, a csv dropped in a bucket, a pushed webhook, a parquet table from a lakehouse, a FHIR
+API, a csv dropped in a bucket, an encounter pushed to an endpoint, a parquet table from a lakehouse, a FHIR
 Observation feed, a windowed weekly pull, a fan-out across facilities, and the defensive
 version with every guard on. Each names every block it needs, carries its DHIS2 connection
 pointed at the public play server, and imports as a dry run by default, so

{dirigent_integration-0.26.0 → dirigent_integration-0.27.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "dirigent-integration"
-version = "0.26.0"
+version = "0.27.0"
 description = "The control center for the dirigent plugin ecosystem: assemble every pack, run everyone's tests and examples together."
 readme = "README.md"
 requires-python = ">=3.13"
 license = "LicenseRef-Proprietary"
 license-files = ["LICENSE"]
-dependencies = ["dirigent-plugin==0.26.0"]
+dependencies = ["dirigent-plugin==0.27.0"]
 
 [project.entry-points."dirigent.plugins.v1"]
 integration = "dirigent_integration:plugin"
@@ -34,10 +34,12 @@ assembly = [
 ]
 dev = [
     "dirigent-testing",
+    "mypy>=2",
     "pytest>=8",
     "pytest-asyncio>=0.24",
     "pyyaml>=6",
     "ruff>=0.16",
+    "types-pyyaml>=6",
 ]
 
 [tool.uv]

{dirigent_integration-0.26.0 → dirigent_integration-0.27.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-integration"
-version = "0.26.0"
+version = "0.27.0"
 description = "The control center for the dirigent plugin ecosystem: assemble every pack, run everyone's tests and examples together."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -10,7 +10,7 @@ license-files = ["LICENSE"]
 # A published install carries the cross-boundary shelves and nothing else: each document
 # names the packs it needs under requires, and the Examples screen marks what is missing.
 dependencies = [
-    "dirigent-plugin==0.26.0",
+    "dirigent-plugin==0.27.0",
 ]
 
 # dirigent-testing is dev-only: the packs' suites import it, and nothing at runtime does,
@@ -41,10 +41,12 @@ assembly = [
 ]
 dev = [
     "dirigent-testing",
+    "mypy>=2",
     "pytest>=8",
     "pytest-asyncio>=0.24",
     "pyyaml>=6",
     "ruff>=0.16",
+    "types-pyyaml>=6",
 ]
 
 # All component packages ride their tracked branch, unpinned: the integration always assembles

{dirigent_integration-0.26.0 → dirigent_integration-0.27.0}/src/dirigent_integration/shelves/fhir/README.md

@@ -60,7 +60,7 @@ option set is in the regenerated map, and the pipeline that reads it needs no ed
 | [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-subscription-to-dhis2.yaml](fhir-subscription-to-dhis2.yaml) | The subscription contract -- `criteria`, `channel.type`, `channel.endpoint`, and what `channel.payload` decides -- landing on an endpoint source the FHIR server calls with a fixed `Authorization` header, whose first step unwraps the notification so strictly that nothing it does not name reaches a later step. |
 | [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

{dirigent_integration-0.26.0 → dirigent_integration-0.27.0}/src/dirigent_integration/shelves/fhir/fhir-questionnaire-response-to-data-values.yaml

@@ -93,7 +93,7 @@ params:
 
 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
+  # body of an endpoint delivery (fhir-subscription-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:

dirigent_integration-0.27.0/src/dirigent_integration/shelves/fhir/fhir-subscription-to-dhis2.yaml

@@ -0,0 +1,249 @@
+# A FHIR Subscription notification delivered to an endpoint source, 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 endpoint; the request becomes the
+# source's output, `unwrap` picks the notified resource out of its body, 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
+#                 endpoint source takes; the others are websocket, email, and message.
+#   channel.endpoint  where to POST it -- this source's route on the instance,
+#                 `$DG_URL/endpoints/fhir/notifications`.
+#
+# HOW THE SERVER PRESENTS THE TOKEN. A rest-hook subscription can carry fixed headers that the
+# server sends with every notification: `channel.header` in R4, a `parameter` named for the
+# header in R5. Set one to `Authorization: Bearer <token>`, with the token the apply printed,
+# and every delivery authenticates as this source. A server that cannot send headers cannot
+# reach it, which is the point: the endpoint takes no anonymous POST.
+#
+# 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 request 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 `unwrap` step, and nothing else. It is STRICT: it names two
+# paths into the body, a body that does not have them fails the run before anything is
+# translated, and nothing else the caller POSTs reaches a later step, because no later step
+# reads the body. A server sending the bare R4 resource rather than a Bundle changes `capture`
+# to the body itself, and the counter, which a bare resource does not carry, to null.
+#
+# WHAT LIVES ON THE INSTANCE AND NOT IN GIT. The source's token, whether it is paused, and
+# every input it has taken. The apply shows the token exactly once, and
+# `dg source rotate-token` mints another, which the Subscription's header then has to carry.
+#
+# RUN IT BY HAND, here, with no server. No --input takes the source's sample, a whole
+# notification Bundle:
+#
+#   dg run --local examples/fhir/fhir-subscription-to-dhis2.yaml
+#
+# ON A SERVER, apply it, keep the token the apply printed, and deliver a notification the way
+# the FHIR server would:
+#
+#   dg apply examples/fhir/fhir-subscription-to-dhis2.yaml
+#   dg source call fhir-subscription-to-dhis2 notified --source-token "$TOKEN" --body @notification.json
+#   curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/fhir+json' \
+#     --data @notification.json "$DG_URL/endpoints/fhir/notifications"
+#   dg source inputs fhir-subscription-to-dhis2 notified
+#
+# EXPECT THIS RUN TO SUCCEED with network access to the play server, the import a dry run.
+
+format: dirigent/v1
+kind: pipeline
+code: fhir-subscription-to-dhis2
+name: A FHIR Subscription notification imported
+description: |
+  Take a FHIR `Subscription` rest-hook notification on an endpoint source, 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 source's route). The server
+  presents the source's token as a fixed `Authorization` header on the subscription.
+  `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, sources, transform, jq, cross-boundary]
+
+requires:
+  blocks:
+    - transform.jq
+    - dhis2.data_value_set_import
+
+connections:
+  dhis2-demo:
+    kind: dhis2
+    config:
+      base_url: https://play.dhis2.org/2.43
+      basic_username: admin
+      basic_password: district
+      timeout: 60s
+
+steps:
+  notified:
+    source:
+      kind: endpoint
+      path: /fhir/notifications
+      methods: [POST]
+      accepts: [application/fhir+json, application/json]
+      max_body: 1MB
+    # What a delivery carries: the history Bundle, a SubscriptionStatus and then the resource.
+    sample:
+      content_type: application/fhir+json
+      body:
+        resourceType: Bundle
+        type: history
+        entry:
+          - resource:
+              resourceType: SubscriptionStatus
+              type: event-notification
+              eventsSinceSubscriptionStart: "17"
+          - resource:
+              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
+
+  # The whole declaration of what a delivery may carry. `capture` is the history Bundle's second
+  # entry -- the first is the SubscriptionStatus -- and the counter comes off that status. A gap
+  # between two deliveries' counters means a notification was lost, which is the only way this
+  # channel says so.
+  unwrap:
+    block: transform.jq
+    depends_on: [notified]
+    config:
+      input: "${steps.notified.output.body}"
+      program: |
+        if .resourceType != "Bundle" then error("the notification is not a Bundle")
+        elif (.entry[1].resource.resourceType // null) != "QuestionnaireResponse"
+        then error("the notification's second entry is not a QuestionnaireResponse")
+        elif (.entry[0].resource.eventsSinceSubscriptionStart | type) != "string"
+        then error("the notification carries no SubscriptionStatus counter")
+        else {capture: .entry[1].resource,
+              events_since_start: .entry[0].resource.eventsSinceSubscriptionStart}
+        end
+
+  # 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
+    depends_on: [unwrap]
+    config:
+      input: "${steps.unwrap.output.value.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: "${steps.unwrap.output.value.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)}

{dirigent_integration-0.26.0 → dirigent_integration-0.27.0}/src/dirigent_integration/shelves/inbound/README.md

@@ -24,7 +24,7 @@ setting (`storage_connections: {s3: <code>}`); the rest need only a network.
 | --- | --- |
 | [`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. |
+| [`endpoint-payload-to-tracker-event.yaml`](endpoint-payload-to-tracker-event.yaml) | Push instead of poll: an endpoint source takes one posted encounter, and the jq step that picks its named fields 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. |

dirigent_integration-0.26.0/src/dirigent_integration/shelves/inbound/webhook-payload-to-tracker-event.yaml → dirigent_integration-0.27.0/src/dirigent_integration/shelves/inbound/endpoint-payload-to-tracker-event.yaml

@@ -1,9 +1,8 @@
 # An event posted by an outside system, landing in DHIS2 the moment it is captured.
 #
 # The other examples on this shelf poll or wait. This one is pushed: a mobile capture app,
-# an EMR, a lab middleware POSTs one encounter to this pipeline's webhook and the run starts
-# with that encounter already in its parameters. Nothing is scheduled and nothing is
-# scanned.
+# an EMR, a lab middleware POSTs one encounter to this pipeline's endpoint and the run starts
+# with that request as its source's output. Nothing is scheduled and nothing is scanned.
 #
 # WHERE THIS LANDS, AND WHY IT IS NOT A TRACKER EVENT. An event-shaped capture is what
 # arrives, but `dhis2.tracker` in this pack READS `/api/tracker` -- tracked entities,
@@ -11,51 +10,61 @@
 # today. The encounter is therefore summed into the aggregate figures it contributes to and
 # imported as a data value set, which is what an aggregate DHIS2 wants from an event stream
 # anyway. When a tracker write block lands, only the reshape and the import change; the
-# intake, the mapping table and the guard do not.
+# intake, the pick, the mapping table and the guard do not.
 #
 # The hops, and the shape at each one:
 #
 #   1. the POST     -> {encounter: {facility, occurred_at, items: [{code, quantity}]}}
-#   2. the mapping  -> three params, each one path into that body and nothing else
+#   2. pick         -> {facility, occurred_at, items}, three paths into that body and
+#                      nothing else
 #   3. reshape      -> {dataValues: [{dataElement, period, orgUnit, value}]}, one value per
 #                      distinct item code, quantities summed
 #   4. gate         -> the same, refused unless the ids and the period are DHIS2's own
 #   5. import       -> the instance's summary
 #
-# THE MAPPING IS THE WHOLE SECURITY BOUNDARY. A caller reaches exactly the three parameters
-# named under params_from_payload, and each mapped value is validated against the params
-# schema like any other run's. A payload carrying a connection code, a dry_run: false, or a
-# different org unit reaches none of them, because none of them is mapped.
+# THE PICK IS THE WHOLE SECURITY BOUNDARY. The whole body is the source's output, but only
+# `pick` reads it, and it hands on exactly three named fields, each checked for its type. A
+# payload carrying a connection code, a dry_run: false, or a field nobody asked for reaches
+# no later step, because no path names it; `dry_run` is a parameter, the pipeline's own to
+# decide, and no call can choose it.
 #
 # The period is derived rather than accepted. A capture knows when it happened; it does not
 # get to say which DHIS2 month it belongs to, because that is the receiving instance's
 # vocabulary and a caller that gets it wrong would silently write into the wrong month.
 #
-# Locally, the payload is supplied as parameters, which is exactly what a delivery does:
+# RUN IT BY HAND, here, with no server. No --input takes the source's sample:
 #
-#   dg run --local examples/inbound/webhook-payload-to-tracker-event.yaml \
-#     -p facility=DiszpKrYNg8 -p occurred_at=2026-06-14T09:20:00Z
+#   dg run --local examples/inbound/endpoint-payload-to-tracker-event.yaml
+#   dg run --local examples/inbound/endpoint-payload-to-tracker-event.yaml --input '{body: {
+#     encounter: {facility: DiszpKrYNg8, occurred_at: "2026-06-14T09:20:00Z",
+#     items: [{code: NVP_WITHIN_72H, quantity: 3}]}}}'
 #
-# Against an instance, where the endpoint exists:
+# ON A SERVER, apply it, keep the token the apply printed, and post an encounter:
 #
-#   dg apply examples/inbound/webhook-payload-to-tracker-event.yaml
-#   dg webhook rotate-token webhook-payload-to-tracker-event capture-posted
-#   curl -X POST "$DG_URL/hooks/$TOKEN" -d '{"encounter": {
-#     "facility": "DiszpKrYNg8", "occurred_at": "2026-06-14T09:20:00Z",
+#   dg apply examples/inbound/endpoint-payload-to-tracker-event.yaml
+#   dg source call endpoint-payload-to-tracker-event posted --source-token "$TOKEN" --body '{
+#     "encounter": {"facility": "DiszpKrYNg8", "occurred_at": "2026-06-14T09:20:00Z",
 #     "items": [{"code": "EXPOSED_REGISTERED", "quantity": 2}]}}'
+#   curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+#     --data @encounter.json http://localhost:3333/endpoints/captures
+#   dg source inputs endpoint-payload-to-tracker-event posted
+#
+# The token lives on the instance and is shown once; `dg source rotate-token` mints another.
+#
+# EXPECT THIS RUN TO SUCCEED with network access to the play server, the import a dry run.
 
 format: dirigent/v1
 kind: pipeline
-code: webhook-payload-to-tracker-event
+code: endpoint-payload-to-tracker-event
 name: A pushed encounter into DHIS2
 description: |
-  An outside system POSTs one captured encounter; the run reshapes it into a DHIS2 data
-  value set and imports it.
+  An outside system POSTs one captured encounter to an endpoint source; a jq step picks the
+  named fields, and the run reshapes them into a DHIS2 data value set and imports it.
 
   The pack's `dhis2.tracker` block reads `/api/tracker` and does not write it, so an
   event-shaped capture lands as the aggregate figures it contributes to.
 
-tags: [inbound, dhis2, webhook, transform, validate, cross-boundary]
+tags: [inbound, dhis2, sources, transform, validate, cross-boundary]
 
 requires:
   blocks:
@@ -75,28 +84,6 @@ connections:
 params:
   type: object
   properties:
-    facility:
-      type: string
-      description: The uid of the facility the encounter was captured at.
-      default: DiszpKrYNg8
-    occurred_at:
-      type: string
-      format: date-time
-      description: When the encounter happened, which is what the DHIS2 period is derived from.
-      default: "2026-06-14T09:20:00Z"
-    items:
-      type: array
-      description: What was given or done, in the sending system's own item codes.
-      default:
-        - { code: EXPOSED_REGISTERED, quantity: 2 }
-        - { code: NVP_WITHIN_72H, quantity: 1 }
-        - { code: EXPOSED_REGISTERED, quantity: 1 }
-      items:
-        type: object
-        required: [code, quantity]
-        properties:
-          code: { type: string }
-          quantity: { type: integer }
     dry_run:
       type: boolean
       description: Whether the instance validates the import and writes nothing.
@@ -120,16 +107,55 @@ schemas:
             value: { type: string }
 
 steps:
+  posted:
+    source:
+      kind: endpoint
+      path: /captures
+      methods: [POST]
+      accepts: [application/json]
+      max_body: 64KB
+    sample:
+      body:
+        encounter:
+          facility: DiszpKrYNg8
+          occurred_at: "2026-06-14T09:20:00Z"
+          items:
+            - { code: EXPOSED_REGISTERED, quantity: 2 }
+            - { code: NVP_WITHIN_72H, quantity: 1 }
+            - { code: EXPOSED_REGISTERED, quantity: 1 }
+
+  # Three paths into the body, each one typed; anything else the caller sent stops here.
+  pick:
+    block: transform.jq
+    depends_on: [posted]
+    config:
+      input: "${steps.posted.output.body}"
+      program: |
+        .encounter as $e
+        | if ($e | type) != "object" then error("the body carries no encounter object")
+          elif ($e.facility | type) != "string" then error("encounter.facility must be a string")
+          elif ($e.occurred_at | type) != "string" then error("encounter.occurred_at must be a string")
+          elif ($e.items | type) != "array"
+            or ([$e.items[] | select((.code | type) != "string"
+                                     or (.quantity | type) != "number"
+                                     or .quantity != (.quantity | floor))] | length) > 0
+          then error("encounter.items must be a list of {code: string, quantity: integer}")
+          else {facility: $e.facility,
+                occurred_at: $e.occurred_at,
+                items: [$e.items[] | {code, quantity}]}
+          end
+
   # One encounter can carry the same item twice -- two children registered in one visit --
   # so the items are grouped and summed before they become data values. Importing them as
   # two values would have the second silently replace the first rather than add to it.
   reshape:
     block: transform.jq
+    depends_on: [pick]
     config:
       input:
-        facility: "${params.facility}"
-        occurred_at: "${params.occurred_at}"
-        items: "${params.items}"
+        facility: "${steps.pick.output.value.facility}"
+        occurred_at: "${steps.pick.output.value.occurred_at}"
+        items: "${steps.pick.output.value.items}"
         lookup:
           EXPOSED_REGISTERED: x0PshcPLSk1
           NVP_WITHIN_72H: wZqi8EXN5x4
@@ -164,13 +190,3 @@ steps:
       connection: dhis2-demo
       data_values: "${steps.gate.output.value}"
       dry_run: "${params.dry_run}"
-
-triggers:
-  webhooks:
-    - code: capture-posted
-      name: One encounter, pushed
-      description: The capture app POSTs an encounter as it is recorded.
-      params_from_payload:
-        facility: "$.encounter.facility"
-        occurred_at: "$.encounter.occurred_at"
-        items: "$.encounter.items"

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

@@ -1,218 +0,0 @@
-# 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.dhis2.org/2.43
-      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"