dirigent-dhis2 0.9.1__py3-none-any.whl

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/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

dirigent_dhis2/analytics_query.py

@@ -0,0 +1,144 @@
+"""``dhis2.analytics_query``: read one analytics query, aggregate or event/enrollment."""
+
+import time
+from typing import Any, ClassVar, Final, Literal
+
+from dhis2w_client import AnalyticsAccessor
+from dhis2w_client.errors import AuthenticationError, Dhis2ApiError
+from pydantic import BaseModel, JsonValue, model_validator
+
+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, StepContext
+
+#: The aggregate analytics endpoint the client's analytics accessor reads.
+AGGREGATE_ENDPOINT: Final = "/api/analytics.json"
+
+#: The query modes this block runs, keyed by the ``mode`` a document names.
+AnalyticsMode = Literal["aggregate", "event", "enrollment"]
+
+
+class Dhis2AnalyticsQueryConfig(BlockModel):
+    """What one analytics query asks of the instance."""
+
+    connection: str
+    """The code of the dhis2 connection naming the instance."""
+
+    mode: AnalyticsMode
+    """Which analytics query to run: ``aggregate`` over ``/api/analytics``, or an ``event`` or
+    ``enrollment`` query over ``/api/analytics/{events,enrollments}/query``."""
+
+    dimension: list[str] = []
+    """The DHIS2 ``dimension=`` axes, such as ``dx:fbfJHSPpUQD`` or ``pe:LAST_12_MONTHS``."""
+
+    filter: list[str] = []
+    """The DHIS2 ``filter=`` axes, fixing a dimension the result is not broken down by."""
+
+    program: str | None = None
+    """The uid of the program an ``event`` or ``enrollment`` query reads; unused for aggregate."""
+
+    start_date: str | None = None
+    """The ISO start of the query window, for the query kinds that take one."""
+
+    end_date: str | None = None
+    """The ISO end of the query window, for the query kinds that take one."""
+
+    output_id_scheme: str | None = None
+    """The DHIS2 ``outputIdScheme``, such as ``UID`` or ``NAME``, applied to the answer."""
+
+    page: int | None = None
+    """The 1-based page to read, for the event and enrollment queries that page."""
+
+    page_size: int | None = None
+    """How many rows a page holds, for the event and enrollment queries that page."""
+
+    @model_validator(mode="after")
+    def _program_scopes_the_query_kinds_that_need_it(self) -> "Dhis2AnalyticsQueryConfig":
+        """An event or enrollment query reads under one program, so it must be named."""
+        if self.mode in ("event", "enrollment") and not self.program:
+            raise ValueError(f"a {self.mode} analytics query needs a program to read under")
+        return self
+
+
+class Dhis2AnalyticsQueryOutput(BlockModel):
+    """The query the analytics endpoint answered, for a downstream step to reference by field."""
+
+    json_body: JsonValue | None = None
+    """The parsed response: the analytics grid, its headers, metaData, and rows."""
+
+    duration_ms: int
+
+
+def _params(config: Dhis2AnalyticsQueryConfig) -> dict[str, Any]:
+    """Build the analytics query from the axes and window the step set, in DHIS2's own names."""
+    params: dict[str, Any] = {}
+    if config.dimension:
+        params["dimension"] = config.dimension
+    if config.filter:
+        params["filter"] = config.filter
+    if config.start_date is not None:
+        params["startDate"] = config.start_date
+    if config.end_date is not None:
+        params["endDate"] = config.end_date
+    if config.output_id_scheme is not None:
+        params["outputIdScheme"] = config.output_id_scheme
+    if config.page is not None:
+        params["page"] = config.page
+    if config.page_size is not None:
+        params["pageSize"] = config.page_size
+    return params
+
+
+class Dhis2AnalyticsQueryOperator(Dhis2Operator[Dhis2AnalyticsQueryConfig, Dhis2AnalyticsQueryOutput]):
+    """Runs one analytics query -- aggregate, event, or enrollment -- and hands the grid on."""
+
+    spec = OperatorSpec(
+        id="dhis2.analytics_query",
+        summary="Run a DHIS2 analytics query.",
+        idempotent=True,
+    )
+    config_model: ClassVar[type[BaseModel]] = Dhis2AnalyticsQueryConfig
+    output_model: ClassVar[type[BaseModel]] = Dhis2AnalyticsQueryOutput
+
+    async def execute(self, config: Dhis2AnalyticsQueryConfig, ctx: StepContext) -> Dhis2AnalyticsQueryOutput:
+        """Read the query once through the accessor for aggregate, the request path otherwise."""
+        started = time.monotonic()
+        async with client_for(ctx, config.connection) as client:
+            if config.mode == "aggregate":
+                body = await self._aggregate(client.analytics, _params(config))
+            else:
+                body = await self._events(client.analytics, config)
+        duration = round((time.monotonic() - started) * 1000)
+        ctx.log.info("analytics query read", mode=config.mode, duration_ms=duration)
+        return Dhis2AnalyticsQueryOutput(json_body=body, duration_ms=duration)
+
+    async def _aggregate(self, analytics: AnalyticsAccessor, params: dict[str, Any]) -> JsonValue:
+        """Read the aggregate grid through the client's analytics accessor."""
+        try:
+            grid = await analytics.aggregate(endpoint=AGGREGATE_ENDPOINT, extra_params=params)
+        except (Dhis2ApiError, AuthenticationError) as error:
+            raise refuse(error, f"GET {AGGREGATE_ENDPOINT}") from error
+        return grid.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+    async def _events(self, analytics: AnalyticsAccessor, config: Dhis2AnalyticsQueryConfig) -> JsonValue:
+        """Read an event or enrollment query grid through the analytics accessor."""
+        collection = "events" if config.mode == "event" else "enrollments"
+        if config.program is None:
+            raise BlockFailure(f"a {config.mode} analytics query needs a program", error_class=ErrorClass.REJECTED)
+        extra = {"outputIdScheme": config.output_id_scheme} if config.output_id_scheme is not None else None
+        query = analytics.event_query if config.mode == "event" else analytics.enrollment_query
+        try:
+            grid = await query(
+                config.program,
+                dimension=config.dimension or None,
+                filter=config.filter or None,
+                start_date=config.start_date,
+                end_date=config.end_date,
+                page=config.page,
+                page_size=config.page_size,
+                extra_params=extra,
+            )
+        except (Dhis2ApiError, AuthenticationError) as error:
+            raise refuse(error, f"GET /api/analytics/{collection}/query/{config.program}") from error
+        return grid.model_dump(mode="json", by_alias=True, exclude_none=True)

dirigent_dhis2/complete.py

@@ -0,0 +1,80 @@
+"""``dhis2.data_set_complete``: wait for a data set registration to be marked complete."""
+
+from typing import ClassVar, Final
+
+from dhis2w_client import CompleteDataSetRegistration, CompleteDataSetRegistrations
+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 Dhis2Sensor, refuse
+from dirigent_plugin import NotYet, SensorSpec, StepContext
+
+#: Where completion registrations are read.
+REGISTRATIONS_PATH: Final = "/api/completeDataSetRegistrations"
+
+
+class Dhis2DataSetCompleteConfig(BlockModel):
+    """Which data set window the run is waiting on."""
+
+    connection: str
+    """The code of the dhis2 connection naming the instance."""
+
+    data_set: str
+    """The uid of the data set."""
+
+    period: str
+    """An ISO period identifier, such as 2026Q1."""
+
+    org_unit: str
+    """The uid of the organisation unit."""
+
+
+class Dhis2DataSetCompleteOutput(BlockModel):
+    """The registration that ended the wait."""
+
+    completed_at: str | None = None
+    """When the registration was made, in the instance's own timestamp."""
+
+    stored_by: str | None = None
+    """Who marked the data set complete."""
+
+
+class Dhis2DataSetCompleteSensor(Dhis2Sensor[Dhis2DataSetCompleteConfig, Dhis2DataSetCompleteOutput]):
+    """Waits for the registration; each poke is one short, read-only GET."""
+
+    spec = SensorSpec(id="dhis2.data_set_complete", summary="Wait for a DHIS2 data set to be marked complete.")
+    config_model: ClassVar[type[BaseModel]] = Dhis2DataSetCompleteConfig
+    output_model: ClassVar[type[BaseModel]] = Dhis2DataSetCompleteOutput
+
+    async def poke(self, config: Dhis2DataSetCompleteConfig, ctx: StepContext) -> Dhis2DataSetCompleteOutput | NotYet:
+        """Observe once. A window nobody has closed yet is the condition, not an error."""
+        async with client_for(ctx, config.connection) as client:
+            try:
+                registrations = await client.complete_data_set_registrations.export(
+                    data_set=config.data_set,
+                    period=config.period,
+                    org_unit=config.org_unit,
+                )
+            except (Dhis2ApiError, AuthenticationError) as error:
+                raise refuse(error, f"GET {REGISTRATIONS_PATH}") from error
+        registration = _completed(registrations)
+        if registration is None:
+            return NotYet(
+                message=f"data set {config.data_set} for {config.period} at {config.org_unit} is not complete"
+            )
+        return Dhis2DataSetCompleteOutput(completed_at=registration.date, stored_by=registration.storedBy)
+
+
+def _completed(envelope: CompleteDataSetRegistrations) -> CompleteDataSetRegistration | None:
+    """Find a completed registration in the endpoint's answer, or nothing while there is none.
+
+    A registration can be unmade, so one carrying ``completed: false`` is a window that was
+    reopened and the wait goes on. Older instances answer without the flag at all, and there
+    a registration's existence is the completion.
+    """
+    for registration in envelope.completeDataSetRegistrations:
+        if registration.completed is True or registration.completed is None:
+            return registration
+    return None

dirigent_dhis2/connection.py

@@ -0,0 +1,102 @@
+"""The ``dhis2`` connection kind: one DHIS2 instance, its credential, and the client that talks to it."""
+
+from datetime import timedelta
+from typing import ClassVar
+
+from dhis2w_client import Dhis2Client, Profile, build_auth_provider
+from pydantic import BaseModel, Field, SecretStr, model_validator
+
+from dirigent_common import BlockModel, Duration, HealthReport
+from dirigent_plugin import ConnectionKind, StepContext
+
+
+class Dhis2ConnectionConfig(BlockModel):
+    """Everything needed to talk to one DHIS2 instance, credentials included."""
+
+    base_url: str = Field(min_length=1)
+    """The instance root every request path is resolved against, version pin included.
+
+    Name the host the instance actually answers on: a redirect to another origin arrives
+    without the credential, because the client drops the Authorization header when the
+    origin changes.
+    """
+
+    api_token: SecretStr | None = None
+    """A personal access token, sent as ``Authorization: ApiToken``."""
+
+    basic_username: str | None = None
+    """The user half of HTTP basic authentication."""
+
+    basic_password: SecretStr | None = None
+    """The secret half of HTTP basic authentication."""
+
+    verify_tls: bool = True
+    """Whether certificates are verified; turning this off is a per-connection decision."""
+
+    timeout: Duration = Field(default=timedelta(seconds=30), gt=timedelta(0))
+    """The timeout applied to every request through this connection."""
+
+    @model_validator(mode="after")
+    def _require_one_credential(self) -> "Dhis2ConnectionConfig":
+        """Reject a config carrying both credential kinds, neither, or half of the basic pair."""
+        if self.api_token is not None and self.basic_username:
+            raise ValueError("a dhis2 connection takes an api_token or basic credentials, not both")
+        if self.api_token is None and not self.basic_username:
+            raise ValueError("a dhis2 connection needs an api_token or basic credentials")
+        if self.basic_username and self.basic_password is None:
+            raise ValueError("basic credentials need a basic_password beside the basic_username")
+        return self
+
+
+def _profile(config: Dhis2ConnectionConfig) -> Profile:
+    """Map the connection's credential onto the profile dhis2w-client authenticates from."""
+    if config.api_token is not None:
+        return Profile(base_url=config.base_url, auth="pat", token=config.api_token.get_secret_value())
+    password = config.basic_password.get_secret_value() if config.basic_password else ""
+    return Profile(base_url=config.base_url, auth="basic", username=config.basic_username, password=password)
+
+
+def build_client(config: Dhis2ConnectionConfig) -> Dhis2Client:
+    """Build a dhis2w-client bound to the connection's URL, credential, TLS setting, and timeout.
+
+    The client is returned unconnected: entering it as an async context manager opens the pool
+    and detects the instance's version from ``/api/system/info`` the dhis2w way.
+    """
+    return Dhis2Client(
+        config.base_url,
+        auth=build_auth_provider(_profile(config)),
+        timeout=config.timeout.total_seconds(),
+        verify=config.verify_tls,
+    )
+
+
+def client_for(ctx: StepContext, ref: str) -> Dhis2Client:
+    """Build the dhis2w-client one block call uses, from the named connection's own config."""
+    return build_client(ctx.connection(ref, Dhis2ConnectionConfig))
+
+
+def settings_of(config: BaseModel) -> Dhis2ConnectionConfig:
+    """Read a connection's config as this kind's own model, whichever model the caller held."""
+    if isinstance(config, Dhis2ConnectionConfig):
+        return config
+    return Dhis2ConnectionConfig.model_validate(config.model_dump())
+
+
+class Dhis2ConnectionKind(ConnectionKind):
+    """The connection kind every block in this pack resolves its instance and credential through."""
+
+    id: ClassVar[str] = "dhis2"
+    config_model: ClassVar[type[BaseModel]] = Dhis2ConnectionConfig
+
+    async def check(self, config: BaseModel) -> HealthReport:
+        """Ask the instance what it is, proving the credential works, never raising.
+
+        Connecting reads ``/api/system/info`` with the credential attached, so a healthy report
+        means the credential is good and the version is the instance's own word for itself.
+        """
+        try:
+            async with build_client(settings_of(config)) as client:
+                version = client.raw_version
+        except Exception as error:  # noqa: BLE001 - a health check reports its verdict, it never raises
+            return HealthReport(healthy=False, detail=f"{type(error).__name__}: {error}")
+        return HealthReport(healthy=True, version=version or None)