dirigent-integration 0.23.2__py3-none-any.whl

dirigent_integration/shelves/fhir/fhir-encounter-to-event.yaml

@@ -0,0 +1,248 @@
+# One clinical Encounter and its Observations collapsed into one DHIS2 program stage event.
+#
+# THE FLOW, END TO END. Find an Encounter on a general-purpose FHIR server, read every
+# Observation that names it, fold the two into a single `/api/tracker` event whose data values
+# are the observations, and post it with importMode=VALIDATE.
+#
+# WHY NOT THE FACADE. `d2w fhir serve` serves no Encounter and no Observation -- it publishes
+# DHIS2 as forms and captures, so its whole clinical surface is the capture pair, and asking
+# it for an Observation answers an OperationOutcome with code `not-supported`. Encounters come
+# from the other kind of FHIR server: a hospital's own, an OpenMRS, a HAPI. That is the point
+# of this example, so `fhir_base` defaults to the public HAPI R4 test server. It is a shared
+# sandbox anyone can write to, so the resources it holds change under you; every id below is a
+# parameter for that reason, and the searches are written to survive not finding one.
+#
+# THE MODELLING QUESTION THIS ANSWERS. FHIR splits a visit into one Encounter plus one
+# Observation per measurement. DHIS2 tracker puts the whole visit in one event: an event has
+# an occurredAt, an org unit, an enrollment, and a bag of dataValues. So the cardinalities do
+# not line up, and the translation is a FOLD -- many Observations into one event -- keyed on
+# Observation.encounter. Nothing else in this document is hard.
+#
+# WHAT ARRIVES. One Encounter:
+#
+#   {"resourceType": "Encounter", "id": "137202491", "status": "finished",
+#    "class": {"code": "AMB"}, "subject": {"reference": "Patient/137202428"},
+#    "period": {"start": "2026-07-20T09:00:00Z"}}
+#
+# and its Observations, each a code and a value:
+#
+#   {"resourceType": "Observation", "status": "final",
+#    "code": {"coding": [{"system": "http://loinc.org", "code": "29463-7",
+#                         "display": "Body weight"}]},
+#    "encounter": {"reference": "Encounter/137202491"},
+#    "valueQuantity": {"value": 61.5, "unit": "kg"}}
+#
+# WHAT LEAVES. One `/api/tracker` document holding one event:
+#
+#   {"events": [{"event": "EvAaBbCcDd1", "program": "IpHINAT79UW",
+#                "programStage": "A03MvHHogjR", "enrollment": "EnAaBbCcDd1",
+#                "trackedEntity": "coxwIkMqNBB", "orgUnit": "DiszpKrYNg8",
+#                "occurredAt": "2026-07-20", "status": "COMPLETED",
+#                "dataValues": [{"dataElement": "UXz7xuGCEhU", "value": "61.5"}]}]}
+#
+# WHICH CODE MAPS TO WHICH DATA ELEMENT.
+#
+#   Encounter.period.start (or Encounter.period.end) -> occurredAt
+#   Encounter.status "finished"                      -> event status COMPLETED
+#   Observation.code.coding LOINC code               -> dataElement, through `loinc_to_de`
+#   Observation.valueQuantity.value                  -> that data value's value
+#
+# WHERE A READER CHANGES IT. `loinc_to_de` is the mapping and the only place codes appear:
+# each entry is one LOINC code and the DHIS2 data element uid it lands in. The stage the event
+# belongs to is `program_stage`, and the program and enrollment are `program` and
+# `enrollment_uid`. An observation whose LOINC code is not in the table is dropped and counted
+# -- conceptmap-driven-mapping.yaml is the same mapping fetched from a server instead.
+#
+# WHAT THIS DOES NOT DO. It does not resolve the Encounter's Patient to a DHIS2 tracked entity.
+# That is a real lookup against a real identifier crosswalk, and patient-to-tracked-entity.yaml
+# is the half that does it; here the entity and its enrollment are parameters.
+#
+#   dg run --local examples/fhir/fhir-encounter-to-event.yaml
+#   dg run --local examples/fhir/fhir-encounter-to-event.yaml -p encounter_id=137202491
+
+format: dirigent/v1
+kind: pipeline
+code: fhir-encounter-to-event
+name: Encounter and Observations to one event
+description: |
+  Fold one FHIR `Encounter` and every `Observation` naming it into a single DHIS2 tracker
+  event, posted with `importMode=VALIDATE`.
+
+  The cardinalities do not line up: FHIR spreads a visit over an Encounter plus one
+  Observation per measurement, and a DHIS2 event holds the whole visit with a bag of data
+  values. The translation is a fold keyed on `Observation.encounter`.
+
+  Read against a general clinical FHIR server, because `d2w fhir serve` publishes DHIS2 as
+  forms and captures and serves no `Encounter` or `Observation` at all.
+
+tags: [fhir, dhis2, cross-boundary]
+
+requires:
+  blocks:
+    - http.request
+    - transform.jq
+
+connections:
+  # A public FHIR R4 sandbox, open and unauthenticated, standing in for a hospital's own
+  # server. Repoint it and only the two searches below have to survive the move.
+  fhir-clinical:
+    kind: http
+    config:
+      base_url: https://hapi.fhir.org/baseR4
+      timeout: 60s
+  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:
+    encounter_status:
+      type: string
+      description: Which encounters to consider. A visit that has not finished has not
+        produced a completed event.
+      default: finished
+    program:
+      type: string
+      default: IpHINAT79UW
+    program_stage:
+      type: string
+      description: The stage the visit lands in; one Questionnaire per stage on the facade.
+      default: A03MvHHogjR
+    org_unit:
+      type: string
+      default: DiszpKrYNg8
+    tracked_entity:
+      type: string
+      description: The DHIS2 person the Encounter's Patient resolves to. A real crosswalk is
+        patient-to-tracked-entity.yaml.
+      default: coxwIkMqNBB
+    enrollment_uid:
+      type: string
+      default: EnAaBbCcDd1
+    event_uid:
+      type: string
+      description: The event's own uid, minted by the client. Deriving it from the source
+        resource is what makes a rehearsal and an import name the same event, and a
+        re-forward collide (E1030) rather than duplicate.
+      default: EvAaBbCcDd1
+    loinc_to_de:
+      type: object
+      description: One LOINC code per DHIS2 data element uid. An observation coded outside
+        this table is dropped and counted.
+      default:
+        "29463-7": UXz7xuGCEhU
+        "8302-2": lw1SqmMlnfh
+        "8480-6": XorIxxprsOp
+
+steps:
+  # `_sort=-_lastUpdated` asks the busiest end of a shared sandbox for something that exists
+  # today. On a real server this is the visit selector: a patient, a date range, a location.
+  find_encounter:
+    block: http.request
+    config:
+      connection: fhir-clinical
+      path: /Encounter
+      method: GET
+      query:
+        status: "${params.encounter_status}"
+        _sort: "-_lastUpdated"
+        _count: 1
+      headers:
+        Accept: application/fhir+json
+
+  # `encounter` is a reference search parameter: it takes `Encounter/<id>`, and it is how the
+  # measurements of one visit are gathered without walking every Observation on the server.
+  # A server that also supports it would answer the same question in one call with
+  # `_revinclude=Observation:encounter` on the search above; two calls is the portable shape.
+  read_observations:
+    block: http.request
+    depends_on: [find_encounter]
+    config:
+      connection: fhir-clinical
+      path: /Observation
+      method: GET
+      query:
+        encounter: "Encounter/${steps.find_encounter.output.body.entry.0.resource.id}"
+        _count: 50
+      headers:
+        Accept: application/fhir+json
+
+  # The fold. One event out, however many observations came in, plus the codes that mapped to
+  # nothing so the receipt can say so.
+  fold_to_event:
+    block: transform.jq
+    depends_on: [find_encounter, read_observations]
+    config:
+      input:
+        encounters: "${steps.find_encounter.output.body}"
+        observations: "${steps.read_observations.output.body}"
+        codes: "${params.loinc_to_de}"
+        program: "${params.program}"
+        program_stage: "${params.program_stage}"
+        org_unit: "${params.org_unit}"
+        tracked_entity: "${params.tracked_entity}"
+        enrollment: "${params.enrollment_uid}"
+        event: "${params.event_uid}"
+      program: |
+        . as {$encounters, $observations, $codes, $program, $program_stage,
+              $org_unit, $tracked_entity, $enrollment, $event}
+        | (($encounters.entry // [])[0].resource) as $e
+        | if $e == null then error("no encounter matched; widen the search") else . end
+        # A date, not an instant: DHIS2 keeps an event's occurredAt as a zone-less wall clock,
+        # so the instant is cut at the T rather than reformatted.
+        | (($e.period.start // $e.period.end // "") | split("T") | first) as $occurred
+        | [($observations.entry // [])[].resource
+           | select(.status == "final" or .status == "amended")
+           | {code: ([(.code.coding // [])[]
+                      | select(.system == "http://loinc.org").code][0]),
+              value: (.valueQuantity.value // .valueInteger
+                      // .valueString // .valueCodeableConcept.coding[0].code)}
+           | select(.code != null and .value != null)] as $seen
+        | {document: {events: [{
+             event: $event,
+             program: $program,
+             programStage: $program_stage,
+             enrollment: $enrollment,
+             trackedEntity: $tracked_entity,
+             orgUnit: $org_unit,
+             occurredAt: $occurred,
+             status: (if $e.status == "finished" then "COMPLETED" else "ACTIVE" end),
+             dataValues: [$seen[] | select($codes[.code] != null)
+                          | {dataElement: $codes[.code], value: (.value | tostring)}]}]},
+           encounter: $e.id,
+           unmapped_codes: [$seen[] | select($codes[.code] == null).code] | unique}
+
+  rehearse_import:
+    block: http.request
+    depends_on: [fold_to_event]
+    config:
+      connection: dhis2-demo
+      path: /api/tracker
+      method: POST
+      query:
+        # /api/tracker's dry run. /api/dataValueSets spells the same intention dryRun=true.
+        importMode: VALIDATE
+      headers:
+        Content-Type: application/json
+      body: "${steps.fold_to_event.output.value.document}"
+      success_status: [200, 201, 409]
+
+  receipt:
+    block: transform.jq
+    depends_on: [rehearse_import]
+    config:
+      input:
+        report: "${steps.rehearse_import.output.body}"
+        folded: "${steps.fold_to_event.output.value}"
+      program: |
+        {encounter: .folded.encounter,
+         data_values: (.folded.document.events[0].dataValues | length),
+         unmapped_codes: .folded.unmapped_codes,
+         status: .report.status,
+         errors: [((.report.validationReport // .report.response.validationReport).errorReports // [])[]
+                  | {code: .errorCode, message: .message}]}

dirigent_integration/shelves/fhir/fhir-measure-report-to-analytics-check.yaml

@@ -0,0 +1,205 @@
+# A FHIR MeasureReport held against DHIS2 analytics for the same period, and the gap reported.
+#
+# THE FLOW, END TO END. Read a MeasureReport for one measure and one period off a FHIR server,
+# ask DHIS2's own analytics for the indicator that is supposed to say the same thing over the
+# same period and org unit, subtract one from the other, and POST the verdict to a receiver.
+#
+# WHY THIS EXISTS. Two systems computing the same number from the same events is the normal
+# state of a country's data, and the useful question is not "what is the number" but "do the
+# two agree, and by how much". This is a reconciliation, so it writes NOTHING to DHIS2 and it
+# is safe to run on a schedule.
+#
+# WHERE THE MEASUREREPORT COMES FROM. Not from `d2w fhir serve`: that facade publishes DHIS2 as
+# forms and captures and serves no Measure and no MeasureReport. A report is produced by
+# SCORING a measure -- a CQL library with the five conventional population defines (Initial
+# population, Denominator, Denominator exclusion, Numerator, Numerator exclusion) -- over a
+# Bundle of FHIR data, and a measure evaluation engine is what turns that scoring into an R4
+# MeasureReport. The report is then a resource like any other, so this document fetches it
+# from wherever it was published. `fhir_base` defaults to a public HAPI R4 sandbox.
+#
+# WHAT ARRIVES -- the report. A proportion measure scored over a period:
+#
+#   {"resourceType": "MeasureReport", "status": "complete", "type": "summary",
+#    "measure": "http://example.org/Measure/measles-coverage",
+#    "period": {"start": "2026-08-01", "end": "2026-08-31"},
+#    "group": [{"population": [
+#                 {"code": {"coding": [{"code": "initial-population"}]}, "count": 4},
+#                 {"code": {"coding": [{"code": "denominator"}]}, "count": 4},
+#                 {"code": {"coding": [{"code": "numerator"}]}, "count": 3}],
+#               "measureScore": {"value": 0.75}}]}
+#
+# WHAT ARRIVES -- the grid. DHIS2 analytics answers a grid, not objects: `headers` names the
+# columns and `rows` is a list of lists, so a value is read by finding its header's index.
+# That indirection is the one awkward thing about analytics and it is why the jq below looks
+# up `value` rather than indexing a fixed position.
+#
+#   {"headers": [{"name": "dx"}, {"name": "pe"}, {"name": "ou"}, {"name": "value"}],
+#    "rows": [["fbfJHSPpUQD", "202608", "ImspTQPwCqd", "0.71"]]}
+#
+# WHAT LEAVES. One discrepancy record, POSTed whether or not it found a gap, because "we
+# checked and they agree" is a fact worth delivering too:
+#
+#   {"measure": "...", "period": "202608", "org_unit": "ImspTQPwCqd",
+#    "fhir_score": 0.75, "dhis2_value": 0.71, "difference": 0.04, "discrepant": true}
+#
+# WHICH CODES LINE UP WITH WHAT. `measure_url` and `indicator` are the two halves of one claim
+# -- that this FHIR measure and this DHIS2 data element or indicator count the same thing --
+# and a reader changes both together or neither. `period` is a DHIS2 ISO period; the FHIR side
+# carries a date range, so the two are matched on the range the period covers.
+#
+# WHEN IT FINDS NOTHING. A missing report and an empty grid are ordinary answers, not failures:
+# the diff says `unavailable` and the receiver hears about it. A reconciliation that crashed
+# when one side was quiet would be silent exactly when something is wrong.
+#
+#   dg run --local examples/fhir/fhir-measure-report-to-analytics-check.yaml
+#   dg run --local examples/fhir/fhir-measure-report-to-analytics-check.yaml -p tolerance=0.1
+
+format: dirigent/v1
+kind: pipeline
+code: fhir-measure-report-to-analytics-check
+name: MeasureReport against DHIS2 analytics
+description: |
+  Hold a FHIR `MeasureReport` against the DHIS2 analytics value for the same period and org
+  unit, and deliver the gap.
+
+  A reconciliation, so it writes nothing: safe on a schedule. The report is produced by
+  scoring a CQL measure over FHIR data -- `d2w fhir serve` publishes no `Measure` or
+  `MeasureReport` of its own -- and read here from wherever it was published.
+
+tags: [fhir, dhis2, cross-boundary]
+
+requires:
+  blocks:
+    - http.request
+    - dhis2.analytics_query
+    - transform.jq
+    - webhook.post
+
+connections:
+  fhir-reports:
+    kind: http
+    config:
+      base_url: https://hapi.fhir.org/baseR4
+      timeout: 60s
+  dhis2-demo:
+    kind: dhis2
+    config:
+      base_url: https://play.im.dhis2.org/stable-2-43-1
+      basic_username: admin
+      basic_password: district
+      timeout: 60s
+  # Where a discrepancy is delivered. Postman Echo stands in for the receiver so the document
+  # runs; hmac_secret would let webhook.post sign the body, which is what a receiver that
+  # trusts nobody wants.
+  discrepancy-sink:
+    kind: http
+    config:
+      base_url: https://postman-echo.com
+      timeout: 30s
+
+params:
+  type: object
+  properties:
+    measure_url:
+      type: string
+      description: The measure whose report is read. Half of the claim that the two systems
+        count the same thing.
+      default: http://cms.gov/fhir/hqr/Measure/synthetic-test-measure
+    indicator:
+      type: string
+      description: The DHIS2 data element or indicator uid that is the other half of it.
+      default: fbfJHSPpUQD
+    org_unit:
+      type: string
+      default: ImspTQPwCqd
+    period:
+      type: string
+      description: A DHIS2 ISO period; the FHIR side is matched on the range it covers.
+      default: "202608"
+    tolerance:
+      type: number
+      description: How far apart the two may be before the difference is called a discrepancy.
+      default: 0.02
+
+steps:
+  # `measure` is the canonical of the measure, which is what makes a report findable without
+  # knowing its id. `_sort=-date` takes the most recent scoring when a measure was scored more
+  # than once for the same period.
+  read_report:
+    block: http.request
+    config:
+      connection: fhir-reports
+      path: /MeasureReport
+      method: GET
+      query:
+        measure: "${params.measure_url}"
+        _sort: "-date"
+        _count: 1
+      headers:
+        Accept: application/fhir+json
+      # A search that matched nothing is a 200 with an empty Bundle, so nothing special is
+      # needed here; this only says a 404 on the endpoint itself is still a failure.
+      success_status: [200]
+
+  # The same question, asked of DHIS2. An aggregate query takes its axes as `dimension`
+  # strings in DHIS2's own vocabulary: dx is the data, pe the period, ou the org unit.
+  read_analytics:
+    block: dhis2.analytics_query
+    config:
+      connection: dhis2-demo
+      mode: aggregate
+      dimension:
+        - "dx:${params.indicator}"
+        - "pe:${params.period}"
+      # A dimension the answer is not broken down BY, only filtered to. Putting ou here rather
+      # than in dimension is what makes the grid one row instead of one row per unit.
+      filter:
+        - "ou:${params.org_unit}"
+
+  # The subtraction. Both sides may be absent, and each absence is reported as itself rather
+  # than folded into a zero: a measure nobody scored and a coverage of 0% are different facts.
+  diff:
+    block: transform.jq
+    depends_on: [read_report, read_analytics]
+    config:
+      input:
+        reports: "${steps.read_report.output.body}"
+        grid: "${steps.read_analytics.output.body}"
+        measure: "${params.measure_url}"
+        period: "${params.period}"
+        org_unit: "${params.org_unit}"
+        tolerance: "${params.tolerance}"
+      program: |
+        . as {$reports, $grid, $measure, $period, $org_unit, $tolerance}
+        | (($reports.entry // [])[0].resource) as $report
+        | ($report.group[0].measureScore.value) as $score
+        # The grid's columns are named in headers, so the value column is found by name and
+        # never by position: DHIS2 adds columns, and a fixed index would start reading one.
+        | ([($grid.headers // []) | to_entries[] | select(.value.name == "value") | .key][0]) as $col
+        | (if $col == null then null
+           else [($grid.rows // [])[] | .[$col] | tonumber?][0] end) as $value
+        | {measure: $measure,
+           period: $period,
+           org_unit: $org_unit,
+           fhir_score: $score,
+           dhis2_value: $value,
+           populations: [(($report.group[0].population // [])[])
+                         | {code: .code.coding[0].code, count: .count}],
+           difference: (if $score == null or $value == null then null
+                        else (($score - $value) | fabs) end),
+           verdict: (if $score == null then "unavailable: no report was scored for this measure"
+                     elif $value == null then "unavailable: analytics answered no value"
+                     elif (($score - $value) | fabs) > $tolerance then "discrepant"
+                     else "agrees" end)}
+
+  # Delivered on every run. A receiver that only ever hears about disagreements cannot tell a
+  # healthy silence from a pipeline that stopped running.
+  report_discrepancy:
+    block: webhook.post
+    depends_on: [diff]
+    config:
+      connection: discrepancy-sink
+      path: /post
+      body: "${steps.diff.output.value}"
+      headers:
+        X-Dirigent-Check: fhir-measure-vs-dhis2-analytics

dirigent_integration/shelves/fhir/fhir-nightly-window-sync.yaml

@@ -0,0 +1,182 @@
+# A nightly incremental pull: everything a FHIR server changed last night, type by type.
+#
+# THE FLOW, END TO END. A cron schedule fires at five and hands the run the interval that just
+# closed. One step fans out over the resource types being synced, each item asking the server
+# for what changed inside that interval, and a join reads the settled fan-out back into one
+# summary that says how much of each type moved and which types could not be reached.
+#
+# THE WINDOW IS A PROPERTY OF THE RUN, NOT OF THIS DOCUMENT. Nothing below declares it: the
+# cadence computes it, and every schedule-fired run carries `${run.window.start}` up to but not
+# including `${run.window.end}`. Half-open is the whole point of an incremental sync -- `ge` on
+# the start and `lt` on the end means two consecutive nights tile the timeline without
+# double-reading a resource that landed exactly on the boundary, and without leaving a hole.
+# An ad hoc run has to be given one, and a run carrying no window REFUSES the reference rather
+# than resolving it to nothing and asking the server for its entire history.
+#
+# THE FACADE HAS NO _lastUpdated. `d2w fhir serve` publishes a fixed store of definitional
+# resources and a spool of receipts; its searches take `_id`, `url`, `identifier` and
+# `questionnaire`, and there is no modified-since anywhere. Its incremental surface is
+# `GET /facade/spool`, whose receipts carry a lifecycle and a `received_at`, paged by an opaque
+# token. So this document is written against a general FHIR server -- `fhir_base` defaults to a
+# public HAPI R4 sandbox -- and the shape it teaches is the one a spool pull would use too.
+#
+# WHAT ARRIVES. One searchset Bundle per resource type, each holding what changed:
+#
+#   {"resourceType": "Bundle", "type": "searchset", "total": 41,
+#    "link": [{"relation": "self", "url": "..."},
+#             {"relation": "next", "url": ".../Patient?_getpages=...&_getpagesoffset=50"}],
+#    "entry": [{"resource": {"resourceType": "Patient", "id": "137202428",
+#                            "meta": {"lastUpdated": "2026-09-04T22:14:03Z"}}}]}
+#
+# WHAT LEAVES. One summary record per run:
+#
+#   {"window": {"from": "2026-09-04T05:00:00Z", "to": "2026-09-05T05:00:00Z"},
+#    "types": [{"type": "Patient", "total": 41, "read": 50, "more_pages": true}],
+#    "changed": 41, "types_reached": 3, "types_asked": 4}
+#
+# WHY items: continue. Each resource type is its own item and its own attempt. Under the
+# default, `fail_fast`, one type the server chokes on fails the whole night's sync. Under
+# `items: continue` that type's failure is recorded against its own run item, the others
+# finish, and the run reports `completed_with_errors`. The cost is worth knowing: a failed item
+# is ABSENT from the step's output -- not null, absent -- so the join sees only what worked,
+# which is why the summary counts the types it asked for as well as the ones it reached.
+#
+# WHY rule: all_done ON THE JOIN. The default `all_success` edge would skip the summary exactly
+# on the night something went wrong, which is the night it is worth having.
+#
+# WHY THE ABSOLUTE URL. A half-open range needs `_lastUpdated` twice in one search, and the
+# `query` map holds one value per key, so the search is written as a URL. That is also the
+# honest shape for FHIR paging: `next` is an opaque link to be followed verbatim, never a page
+# number to be constructed, and a real sync follows it until it is gone. This one reads the
+# first page and reports whether there were more, which is the smallest thing that does not
+# quietly lie about completeness.
+#
+# WHERE A READER CHANGES IT. `resource_types` is the fan-out and the whole scope of the sync;
+# `page_size` is what one page holds. Add a type to the list and the grid grows on the next
+# firing with nothing else edited.
+#
+#   dg run --local examples/fhir/fhir-nightly-window-sync.yaml --window 2026-09-01..2026-09-02
+#   dg apply examples/fhir/fhir-nightly-window-sync.yaml
+#   dg backfill fhir-nightly-window-sync --schedule nightly \
+#     --from 2026-09-01T05:00:00Z --to 2026-09-08T05:00:00Z --dry-run
+
+format: dirigent/v1
+kind: pipeline
+code: fhir-nightly-window-sync
+name: Nightly windowed FHIR sync
+description: |
+  Pull everything a FHIR server changed inside the interval a nightly schedule just closed,
+  one fan-out item per resource type, and join the results into one summary.
+
+  The window belongs to the run, not to this document: `${run.window.start}` and
+  `${run.window.end}` are half-open ISO instants, so consecutive firings tile the timeline
+  without overlap or gap. `items: continue` lets one unreachable type cost only itself.
+
+tags: [fhir, dhis2, cross-boundary]
+
+requires:
+  blocks:
+    - http.request
+    - transform.jq
+
+connections:
+  # Carried for its timeout and TLS setting; the searches below give absolute URLs, because a
+  # half-open range needs the same query parameter twice and the query map holds one per key.
+  fhir-source:
+    kind: http
+    config:
+      base_url: https://hapi.fhir.org/baseR4
+      timeout: 60s
+  # Not read by this document, which only pulls. It is here because the sync exists to feed
+  # DHIS2, and the shelf's other documents are what turn each of these types into an import:
+  # Patient through patient-to-tracked-entity.yaml, Encounter through encounter-to-event.yaml,
+  # QuestionnaireResponse through capture-bundle-to-data-values.yaml.
+  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:
+    fhir_base:
+      type: string
+      description: The server to sync from. Not the facade -- it answers no _lastUpdated.
+      default: https://hapi.fhir.org/baseR4
+    resource_types:
+      type: array
+      description: The scope of the sync. One fan-out item each.
+      default: [Patient, Encounter, Observation]
+      items:
+        type: string
+    page_size:
+      type: integer
+      description: How many resources one page holds. A server may answer fewer; it never
+        answers more.
+      default: 50
+
+steps:
+  # for_each is expanded when the run is created, so it reads params, run and item -- never
+  # another step's output, because the cardinality of the grid has to be known before anything
+  # executes. That is why the types are a parameter and not something discovered from
+  # /metadata: a run's shape is fixed before its first request.
+  pull:
+    block: http.request
+    for_each: "${params.resource_types}"
+    items: continue
+    config:
+      url: "${params.fhir_base}/${item}?_lastUpdated=ge${run.window.start}&_lastUpdated=lt${run.window.end}&_count=${params.page_size}&_sort=_lastUpdated"
+      method: GET
+      headers:
+        Accept: application/fhir+json
+      # A type this server does not serve answers 404 or an OperationOutcome, and under
+      # items: continue that costs one item rather than the night.
+      success_status: [200]
+
+  # The join. A fan-out step's output is the list of its items' outputs in item order, so the
+  # object carrying each response is unwrapped once here.
+  summarise:
+    block: transform.jq
+    depends_on: [pull]
+    rule: all_done
+    config:
+      input:
+        pages: "${steps.pull.output}"
+        asked: "${params.resource_types}"
+        from: "${run.window.start}"
+        to: "${run.window.end}"
+      program: |
+        . as {$pages, $asked, $from, $to}
+        | [$pages[] | .body
+           | {type: ((.entry // [])[0].resource.resourceType
+                     // (.link[0].url | split("/") | last | split("?") | first)),
+              # `total` is the server's count of the whole searchset, a different number from
+              # how many rode in this page: a sync reporting the page size would say the same
+              # thing on a quiet night and a busy one. A server is allowed to omit it on a
+              # large searchset, and HAPI does, so it is nullable and the count below says so.
+              total: .total,
+              read: ((.entry // []) | length),
+              more_pages: ([(.link // [])[] | select(.relation == "next")] | length > 0)}] as $seen
+        | {window: {from: $from, to: $to},
+           types: $seen,
+           changed: ([$seen[] | .total // .read] | add // 0),
+           counted_from_pages: [$seen[] | select(.total == null) | .type],
+           types_reached: ($seen | length),
+           types_asked: ($asked | length),
+           # The gap between the two is what items: continue bought, and saying it out loud is
+           # what keeps a partial sync from reading like a complete one.
+           types_missed: ($asked - [$seen[] | .type])}
+
+triggers:
+  schedules:
+    - code: nightly
+      name: Nightly, Oslo time
+      description: Reads the day that closed at five this morning.
+      cron: "0 5 * * *"
+      # The zone belongs to the schedule, so the window it derives is a day of Oslo's clock
+      # rather than a fixed 24 hours: the spring-forward night is 23 hours long and the
+      # fall-back night is 25, and a pair of instants says so honestly.
+      timezone: Europe/Oslo