dirigent-dhis2 0.9.1__tar.gz

dirigent_dhis2-0.9.1/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Morten Olav Hansen <morten@winterop.com>. All rights reserved.
+
+This source code and accompanying documentation are the property of
+Morten Olav Hansen. No license, express or implied, is granted to use, copy,
+modify, merge, publish, distribute, sublicense, or sell copies of this
+software or its derivatives.
+
+The source is published for reference only. Any use beyond reading
+requires written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

dirigent_dhis2-0.9.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: dirigent-dhis2
+Version: 0.9.1
+Summary: The DHIS2 adapter pack for dirigent: a connection kind and the blocks for one instance.
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Requires-Dist: dhis2w-client>=1.13.4,<2
+Requires-Dist: dirigent-common==0.9.1
+Requires-Dist: dirigent-plugin==0.9.1
+Requires-Dist: httpx>=0.28
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# dirigent-dhis2
+
+Documentation: <https://winterop-com.github.io/dirigent-dhis2/>
+
+The DHIS2 adapter pack for [dirigent](https://github.com/winterop-com/dirigent). It
+contributes the `dhis2` connection kind, two JSON Schema formats (`dhis2-uid` and
+`dhis2-period`), and the blocks that speak DHIS2's asynchronous jobs, import summaries,
+completeness registrations, metadata, tracker and analytics reads as first-class steps,
+rather than composing them out of raw HTTP:
+
+| Block | Kind | What it does |
+| --- | --- | --- |
+| `dhis2.analytics_run` | operator | Submits the analytics tables job and follows its task notifications to the end. |
+| `dhis2.analytics_query` | operator | Runs one analytics query, aggregate or event/enrollment, and hands the grid on. |
+| `dhis2.data_value_set_export` | operator | Reads a data value set for a data set, period and org unit, inline or to storage. |
+| `dhis2.data_value_set_import` | operator | Imports a data value set, parsing the import summary and its conflicts. |
+| `dhis2.metadata` | operator | Reads one metadata collection through the version-bound generic accessor. |
+| `dhis2.tracker` | operator | Reads a page of tracked entities, enrollments or events from `/api/tracker`. |
+| `dhis2.data_set_complete` | sensor | Holds a run until a data set is marked complete for the period. |
+
+Every block classifies its failures the dhis2w-client way: an instance whose version the
+client does not speak is refused rather than retried, and a transport failure is transient.
+
+An instance discovers the pack by installing it: the `dirigent.plugins.v1` entry point in
+`pyproject.toml` is the whole registration.
+
+## Install
+
+Install the pack into the dirigent image:
+
+```bash
+uv pip install dirigent-dhis2
+```
+
+or add it to a project:
+
+```bash
+uv add dirigent-dhis2
+```
+
+## Develop
+
+```bash
+uv sync --locked
+uv run ruff format --check . && uv run ruff check .
+uv run mypy && uv run pyright
+uv run pytest
+```
+
+That is what CI runs. The lock file is committed and CI syncs against it, so a pack build is
+reproducible; the ecosystem's nightly integration is what proves the pack against the
+
+`tests/` exercises every block against a mocked DHIS2 instance, and `tests/test_examples.py`
+validates the example documents against the pack's own catalog. The examples run standalone,
+each carrying the connection it uses.
+
+## Examples
+
+One file per operation, grouped by how it is built:
+
+| Shelf | What is in it |
+| --- | --- |
+| [`examples/dhis2/`](examples/dhis2) | The native adapter: exports and their import strategies, the sign-off gate, the analytics reads and rebuilds, the three tracker collections, the metadata reads. |
+| [`examples/dhis2-compose/`](examples/dhis2-compose) | A `dhis2.*` block beside one of the engine's own: a schema gate, a jq reshape, a fan-out over org units. |
+| [`examples/dhis2-http/`](examples/dhis2-http) | The generic-HTTP way, for what no adapter covers: a CSV export, a period range, a completion registration, a stage-scoped event read. |
+| [`examples/validate/`](examples/validate) | A metadata read held to a shape: a `fields=` projection gated on `validate.schema`, with the schema carried and named. |
+| [`examples/schemas/`](examples/schemas) | The JSON Schemas that pin the reads the DHIS2 series makes, applied on their own. |
+
+Each shelf's README lists its files one line each.
+
+## Licence
+
+Copyright (c) 2026 Morten Olav Hansen. All rights reserved. See [LICENSE](LICENSE).
+
+The source is published for reference only: no licence to use, copy, modify or distribute it
+is granted, and any use beyond reading requires written permission.

dirigent_dhis2-0.9.1/README.md

@@ -0,0 +1,76 @@
+# dirigent-dhis2
+
+Documentation: <https://winterop-com.github.io/dirigent-dhis2/>
+
+The DHIS2 adapter pack for [dirigent](https://github.com/winterop-com/dirigent). It
+contributes the `dhis2` connection kind, two JSON Schema formats (`dhis2-uid` and
+`dhis2-period`), and the blocks that speak DHIS2's asynchronous jobs, import summaries,
+completeness registrations, metadata, tracker and analytics reads as first-class steps,
+rather than composing them out of raw HTTP:
+
+| Block | Kind | What it does |
+| --- | --- | --- |
+| `dhis2.analytics_run` | operator | Submits the analytics tables job and follows its task notifications to the end. |
+| `dhis2.analytics_query` | operator | Runs one analytics query, aggregate or event/enrollment, and hands the grid on. |
+| `dhis2.data_value_set_export` | operator | Reads a data value set for a data set, period and org unit, inline or to storage. |
+| `dhis2.data_value_set_import` | operator | Imports a data value set, parsing the import summary and its conflicts. |
+| `dhis2.metadata` | operator | Reads one metadata collection through the version-bound generic accessor. |
+| `dhis2.tracker` | operator | Reads a page of tracked entities, enrollments or events from `/api/tracker`. |
+| `dhis2.data_set_complete` | sensor | Holds a run until a data set is marked complete for the period. |
+
+Every block classifies its failures the dhis2w-client way: an instance whose version the
+client does not speak is refused rather than retried, and a transport failure is transient.
+
+An instance discovers the pack by installing it: the `dirigent.plugins.v1` entry point in
+`pyproject.toml` is the whole registration.
+
+## Install
+
+Install the pack into the dirigent image:
+
+```bash
+uv pip install dirigent-dhis2
+```
+
+or add it to a project:
+
+```bash
+uv add dirigent-dhis2
+```
+
+## Develop
+
+```bash
+uv sync --locked
+uv run ruff format --check . && uv run ruff check .
+uv run mypy && uv run pyright
+uv run pytest
+```
+
+That is what CI runs. The lock file is committed and CI syncs against it, so a pack build is
+reproducible; the ecosystem's nightly integration is what proves the pack against the
+
+`tests/` exercises every block against a mocked DHIS2 instance, and `tests/test_examples.py`
+validates the example documents against the pack's own catalog. The examples run standalone,
+each carrying the connection it uses.
+
+## Examples
+
+One file per operation, grouped by how it is built:
+
+| Shelf | What is in it |
+| --- | --- |
+| [`examples/dhis2/`](examples/dhis2) | The native adapter: exports and their import strategies, the sign-off gate, the analytics reads and rebuilds, the three tracker collections, the metadata reads. |
+| [`examples/dhis2-compose/`](examples/dhis2-compose) | A `dhis2.*` block beside one of the engine's own: a schema gate, a jq reshape, a fan-out over org units. |
+| [`examples/dhis2-http/`](examples/dhis2-http) | The generic-HTTP way, for what no adapter covers: a CSV export, a period range, a completion registration, a stage-scoped event read. |
+| [`examples/validate/`](examples/validate) | A metadata read held to a shape: a `fields=` projection gated on `validate.schema`, with the schema carried and named. |
+| [`examples/schemas/`](examples/schemas) | The JSON Schemas that pin the reads the DHIS2 series makes, applied on their own. |
+
+Each shelf's README lists its files one line each.
+
+## Licence
+
+Copyright (c) 2026 Morten Olav Hansen. All rights reserved. See [LICENSE](LICENSE).
+
+The source is published for reference only: no licence to use, copy, modify or distribute it
+is granted, and any use beyond reading requires written permission.

dirigent_dhis2-0.9.1/pyproject.toml

@@ -0,0 +1,113 @@
+[project]
+name = "dirigent-dhis2"
+version = "0.9.1"
+description = "The DHIS2 adapter pack for dirigent: a connection kind and the blocks for one instance."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "dhis2w-client>=1.13.4,<2",
+    "dirigent-common==0.9.1",
+    "dirigent-plugin==0.9.1",
+    "httpx>=0.28",
+]
+
+[project.entry-points."dirigent.plugins.v1"]
+dhis2 = "dirigent_dhis2:plugin"
+
+[dependency-groups]
+dev = [
+    "dirigent-testing==0.9.1",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.7",
+    "mypy>=1.19",
+    "pymdown-extensions>=11.0.2",
+    "pyright>=1.1",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pyyaml>=6",
+    "respx>=0.21",
+    "ruff>=0.16",
+    "types-jsonschema>=4",
+    "types-pyyaml>=6",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "D",
+    "SIM",
+    "UP",
+    "B",
+    "TID",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D103",
+    "D100",
+    "D101",
+    "D102",
+    "D104",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = [
+    "dirigent_common",
+    "dirigent_dhis2",
+    "dirigent_plugin",
+    "dirigent_testing",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.13"
+disallow_untyped_defs = true
+warn_return_any = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+no_implicit_optional = true
+strict_equality = true
+plugins = ["pydantic.mypy"]
+files = [
+    "src",
+    "tests",
+]
+mypy_path = ["tests"]
+
+[tool.pyright]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+include = [
+    "src",
+    "tests",
+]
+extraPaths = ["tests"]
+reportMissingTypeStubs = false

dirigent_dhis2-0.9.1/pyproject.toml.orig

@@ -0,0 +1,83 @@
+[project]
+name = "dirigent-dhis2"
+version = "0.9.1"
+description = "The DHIS2 adapter pack for dirigent: a connection kind and the blocks for one instance."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "dhis2w-client>=1.13.4,<2",
+    "dirigent-common==0.9.1",
+    "dirigent-plugin==0.9.1",
+    "httpx>=0.28",
+]
+
+[project.entry-points."dirigent.plugins.v1"]
+dhis2 = "dirigent_dhis2:plugin"
+
+[dependency-groups]
+dev = [
+    "dirigent-testing==0.9.1",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.7",
+    "mypy>=1.19",
+    "pymdown-extensions>=11.0.2",
+    "pyright>=1.1",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pyyaml>=6",
+    "respx>=0.21",
+    "ruff>=0.16",
+    "types-jsonschema>=4",
+    "types-pyyaml>=6",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "D", "SIM", "UP", "B", "TID"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D103", "D100", "D101", "D102", "D104"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["dirigent_common", "dirigent_dhis2", "dirigent_plugin", "dirigent_testing"]
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.13"
+disallow_untyped_defs = true
+warn_return_any = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+no_implicit_optional = true
+strict_equality = true
+plugins = ["pydantic.mypy"]
+files = ["src", "tests"]
+mypy_path = ["tests"]
+
+[tool.pyright]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+include = ["src", "tests"]
+extraPaths = ["tests"]
+reportMissingTypeStubs = false

dirigent_dhis2-0.9.1/src/dirigent_dhis2/__init__.py

@@ -0,0 +1,108 @@
+"""The DHIS2 adapter pack: the ``dhis2`` connection kind and the blocks for one instance."""
+
+from dirigent_dhis2.analytics import (
+    Dhis2AnalyticsRunConfig,
+    Dhis2AnalyticsRunOperator,
+    Dhis2AnalyticsRunOutput,
+)
+from dirigent_dhis2.analytics_query import (
+    Dhis2AnalyticsQueryConfig,
+    Dhis2AnalyticsQueryOperator,
+    Dhis2AnalyticsQueryOutput,
+)
+from dirigent_dhis2.complete import (
+    Dhis2DataSetCompleteConfig,
+    Dhis2DataSetCompleteOutput,
+    Dhis2DataSetCompleteSensor,
+)
+from dirigent_dhis2.connection import (
+    Dhis2ConnectionConfig,
+    Dhis2ConnectionKind,
+    build_client,
+    client_for,
+)
+from dirigent_dhis2.export import (
+    Dhis2DataValueSetExportConfig,
+    Dhis2DataValueSetExportOperator,
+    Dhis2DataValueSetExportOutput,
+)
+from dirigent_dhis2.formats import DHIS2_FORMATS, is_period, is_uid
+from dirigent_dhis2.imports import (
+    Dhis2DataValueSetImportConfig,
+    Dhis2DataValueSetImportOperator,
+    Dhis2DataValueSetImportOutput,
+    Dhis2ImportConflict,
+)
+from dirigent_dhis2.metadata import (
+    Dhis2MetadataConfig,
+    Dhis2MetadataOperator,
+    Dhis2MetadataOutput,
+)
+from dirigent_dhis2.tracker import (
+    Dhis2TrackerConfig,
+    Dhis2TrackerOperator,
+    Dhis2TrackerOutput,
+)
+from dirigent_dhis2.web import Dhis2Operator, Dhis2Sensor, classify
+from dirigent_plugin import Contribution, extension
+
+
+class Dhis2Plugin:
+    """The plugin object the host discovers under the dirigent.plugins.v1 entry-point group."""
+
+    @extension
+    def contribute(self) -> Contribution:
+        """Contribute the DHIS2 blocks and the ``dhis2`` connection kind they are configured from."""
+        return Contribution(
+            operators=[
+                Dhis2AnalyticsRunOperator(),
+                Dhis2AnalyticsQueryOperator(),
+                Dhis2DataValueSetExportOperator(),
+                Dhis2DataValueSetImportOperator(),
+                Dhis2MetadataOperator(),
+                Dhis2TrackerOperator(),
+            ],
+            sensors=[Dhis2DataSetCompleteSensor()],
+            connection_kinds=[Dhis2ConnectionKind()],
+            formats=DHIS2_FORMATS,
+        )
+
+
+plugin = Dhis2Plugin()
+
+__all__ = [
+    "DHIS2_FORMATS",
+    "Dhis2AnalyticsQueryConfig",
+    "Dhis2AnalyticsQueryOperator",
+    "Dhis2AnalyticsQueryOutput",
+    "Dhis2AnalyticsRunConfig",
+    "Dhis2AnalyticsRunOperator",
+    "Dhis2AnalyticsRunOutput",
+    "Dhis2ConnectionConfig",
+    "Dhis2ConnectionKind",
+    "Dhis2DataSetCompleteConfig",
+    "Dhis2DataSetCompleteOutput",
+    "Dhis2DataSetCompleteSensor",
+    "Dhis2DataValueSetExportConfig",
+    "Dhis2DataValueSetExportOperator",
+    "Dhis2DataValueSetExportOutput",
+    "Dhis2DataValueSetImportConfig",
+    "Dhis2DataValueSetImportOperator",
+    "Dhis2DataValueSetImportOutput",
+    "Dhis2ImportConflict",
+    "Dhis2MetadataConfig",
+    "Dhis2MetadataOperator",
+    "Dhis2MetadataOutput",
+    "Dhis2Operator",
+    "Dhis2Plugin",
+    "Dhis2Sensor",
+    "Dhis2TrackerConfig",
+    "Dhis2TrackerOperator",
+    "Dhis2TrackerOutput",
+    "build_client",
+    "classify",
+    "client_for",
+    "is_period",
+    "is_uid",
+    "plugin",
+]

dirigent_dhis2-0.9.1/src/dirigent_dhis2/analytics.py

@@ -0,0 +1,199 @@
+"""``dhis2.analytics_run``: run the analytics tables job, submitted once and then probed."""
+
+import json
+from datetime import UTC, datetime, timedelta
+from typing import Any, ClassVar, Final
+
+from dhis2w_client.errors import AuthenticationError, Dhis2ApiError
+from pydantic import BaseModel
+
+from dirigent_common import BlockModel
+from dirigent_dhis2.connection import client_for
+from dirigent_dhis2.web import Dhis2Operator, refuse
+from dirigent_plugin import (
+    BlockFailure,
+    ErrorClass,
+    OperatorSpec,
+    ProbeResult,
+    ProbeStatus,
+    RemoteHandle,
+    StepContext,
+)
+
+#: Where the analytics tables job is submitted.
+ANALYTICS_PATH: Final = "/api/resourceTables/analytics"
+
+#: The handle key holding the notifier endpoint the submission answered with.
+NOTIFIER = "notifier"
+
+#: The handle key holding the job type the task poll is keyed by, beside the handle's task uid.
+JOB_TYPE = "job_type"
+
+#: The handle key holding the poll cursor: the notification identifiers already streamed in.
+CURSOR = "cursor"
+
+#: How many notification messages the output keeps, from the end of the task's story.
+MESSAGE_TAIL = 10
+
+#: How long a task may stay silent from the attempt's start before it is taken to be lost.
+#:
+#: DHIS2 answers a task it has never heard of exactly the way it answers one that has not
+#: written its first notification yet: 200 and an empty feed. The two are told apart by time.
+#: A submitted job writes its first line within seconds of starting, so a feed still empty
+#: this long after the submission is a task the instance lost, restarted away, or never had.
+GONE_AFTER: Final = timedelta(minutes=15)
+
+
+class Dhis2AnalyticsRunConfig(BlockModel):
+    """What one analytics tables run asks of the instance."""
+
+    connection: str
+    """The code of the dhis2 connection naming the instance."""
+
+    last_years: int | None = None
+    """Limit the tables to this many years back, or leave unset to build them all."""
+
+    skip_resource_tables: bool = False
+    """Whether the resource tables are left as they are."""
+
+    skip_aggregate: bool = False
+    """Whether aggregate data analytics tables are left as they are."""
+
+    skip_events: bool = False
+    """Whether event analytics tables are left as they are."""
+
+    skip_enrollment: bool = False
+    """Whether enrollment analytics tables are left as they are."""
+
+    skip_org_unit_ownership: bool = False
+    """Whether the org unit ownership table is left as it is."""
+
+
+class Dhis2AnalyticsRunOutput(BlockModel):
+    """What the finished analytics job reported."""
+
+    task_id: str
+    """The id the instance gave the job."""
+
+    completed_at: str | None = None
+    """When the task said it was done, in the instance's own timestamp."""
+
+    messages: list[str]
+    """The last few notification messages, oldest first."""
+
+
+def _level(entry: Any) -> str:
+    """Read a notification's level, defaulting the one a version left unset."""
+    return (entry.level or "INFO").upper()
+
+
+def _completed_at(entry: Any) -> str | None:
+    """Read the completing notification's timestamp as the instance's own ISO instant."""
+    return entry.time.isoformat() if entry is not None and entry.time is not None else None
+
+
+def _silent_for(ctx: StepContext) -> timedelta:
+    """How long this attempt has been waiting on the task, measured from its first start."""
+    started = ctx.started_at if ctx.started_at.tzinfo is not None else ctx.started_at.replace(tzinfo=UTC)
+    return datetime.now(UTC) - started
+
+
+class Dhis2AnalyticsRunOperator(Dhis2Operator[Dhis2AnalyticsRunConfig, Dhis2AnalyticsRunOutput]):
+    """Submits the analytics tables job and follows its notifications until it settles."""
+
+    spec = OperatorSpec(
+        id="dhis2.analytics_run",
+        summary="Run the DHIS2 analytics tables job.",
+        default_poll=timedelta(minutes=1),
+    )
+    config_model: ClassVar[type[BaseModel]] = Dhis2AnalyticsRunConfig
+    output_model: ClassVar[type[BaseModel]] = Dhis2AnalyticsRunOutput
+
+    async def execute(self, config: Dhis2AnalyticsRunConfig, ctx: StepContext) -> RemoteHandle:
+        """Submit the job and hand back the task reference the engine probes."""
+        async with client_for(ctx, config.connection) as client:
+            try:
+                envelope = await client.maintenance.run_analytics_tables(
+                    last_years=config.last_years,
+                    skip_resource_tables=config.skip_resource_tables,
+                    skip_aggregate=config.skip_aggregate,
+                    skip_events=config.skip_events,
+                    skip_enrollment=config.skip_enrollment,
+                    skip_org_unit_ownership=config.skip_org_unit_ownership,
+                )
+            except (Dhis2ApiError, AuthenticationError) as error:
+                raise refuse(error, f"POST {ANALYTICS_PATH}") from error
+        task_ref = envelope.task_ref()
+        endpoint = envelope.notifier_endpoint()
+        if task_ref is None or endpoint is None:
+            raise BlockFailure(
+                "the analytics job submission answered without a task reference to follow",
+                error_class=ErrorClass.REJECTED,
+            )
+        job_type, task_uid = task_ref
+        ctx.log.info("analytics job submitted", notifier=endpoint)
+        return RemoteHandle(block_id=self.spec.id, ref=task_uid, meta={NOTIFIER: endpoint, JOB_TYPE: job_type})
+
+    async def probe(self, handle: RemoteHandle, config: Dhis2AnalyticsRunConfig, ctx: StepContext) -> ProbeResult:
+        """Poll the task once, stream the notifications new since the cursor, and map its state."""
+        task_ref = (handle.meta[JOB_TYPE], handle.ref)
+        cursor = json.loads(handle.meta.get(CURSOR, "[]"))
+        async with client_for(ctx, config.connection) as client:
+            try:
+                poll = await client.tasks.poll_once(task_ref, cursor=cursor)
+            except Dhis2ApiError as error:
+                if error.status_code == 404:
+                    return ProbeResult(
+                        status=ProbeStatus.GONE, message=f"the instance no longer knows task {handle.ref}"
+                    )
+                raise refuse(error, f"GET {handle.meta[NOTIFIER]}") from error
+            except AuthenticationError as error:
+                raise refuse(error, f"GET {handle.meta[NOTIFIER]}") from error
+        for entry in poll.new:
+            log = ctx.log.warning if _level(entry) == "ERROR" else ctx.log.info
+            log(entry.message or "", level=_level(entry))
+        advanced = {**handle.meta, CURSOR: json.dumps(sorted(poll.cursor))}
+        if not poll.completed:
+            if not poll.cursor and _silent_for(ctx) >= GONE_AFTER:
+                return ProbeResult(
+                    status=ProbeStatus.GONE,
+                    message=f"the instance has reported nothing for task {handle.ref} since it was submitted",
+                )
+            return ProbeResult(status=ProbeStatus.RUNNING, message="the task is still running", meta=advanced)
+        terminal = poll.new[-1] if poll.new else None
+        if terminal is not None and _level(terminal) == "ERROR":
+            return ProbeResult(status=ProbeStatus.FAILED, message=f"the task failed: {terminal.message or ''}")
+        return ProbeResult(
+            status=ProbeStatus.SUCCEEDED,
+            message=terminal.message if terminal is not None else None,
+            meta=advanced,
+        )
+
+    async def fetch(
+        self, handle: RemoteHandle, config: Dhis2AnalyticsRunConfig, ctx: StepContext
+    ) -> Dhis2AnalyticsRunOutput:
+        """Collect the finished task's story; safe to call again."""
+        task_ref = (handle.meta[JOB_TYPE], handle.ref)
+        async with client_for(ctx, config.connection) as client:
+            try:
+                poll = await client.tasks.poll_once(task_ref)
+            except Dhis2ApiError as error:
+                if error.status_code == 404:
+                    raise BlockFailure(
+                        f"task {handle.ref} disappeared before its result could be collected",
+                        error_class=ErrorClass.TRANSIENT,
+                    ) from error
+                raise refuse(error, f"GET {handle.meta[NOTIFIER]}") from error
+            except AuthenticationError as error:
+                raise refuse(error, f"GET {handle.meta[NOTIFIER]}") from error
+        story = poll.new
+        terminal = story[-1] if story and story[-1].completed else None
+        return Dhis2AnalyticsRunOutput(
+            task_id=handle.ref,
+            completed_at=_completed_at(terminal),
+            messages=[entry.message or "" for entry in story][-MESSAGE_TAIL:],
+        )
+
+    async def cancel(self, handle: RemoteHandle, config: Dhis2AnalyticsRunConfig, ctx: StepContext) -> bool:
+        """Report that the job could not be told: DHIS2 offers no way to stop a running analytics job."""
+        return False