Configuration and notice contract¶

The package ships immuknow/config/ as its default configuration directory. Pass --config PATH to select a PHU-owned directory. It must contain the required reference files; installed resources remain read-only. The command and callable workflow are described in getting started.

The CSV input contract is packaged separately at immuknow/schemas/input_schema.json. It is maintained with preprocessing code; --config cannot replace its field names, types, or validation rules. A file named input_schema.json in a configuration directory is not used.

Files and responsibilities¶

Python uses the reference mappings to normalize records and decide eligibility. Typst loads the selected display dictionaries once from the staged render workspace. Chart membership and order use configured disease names as keys, never translated labels; two different names with the same label remain separate. Uncatalogued source labels remain visible unchanged. If an approved label exists in the other language but is absent from the selected language, rendering fails instead of switching languages. Update both language/domain dictionaries when adding a configured disease name.

Run options¶

Set options in parameters.yaml. Common choices:

pdf_validation.rules supports client_id_presence, exactly_two_pages, signature_overflow, and envelope_window_1_125. The first compares the extracted client ID to the expected render job; the others use page count or native Typst markers. An error-level finding stops the run. The validation report is written under metadata/. PDF validation explains the measurements.

Bundle manifests record group_by as size, school, or board, matching bundling.group_by. A null configuration value means size: split the whole cohort into bundles of the requested size. School and board grouping apply that size limit within each group.

For school matching, set school_validation.enabled: true, target_phu to the exact key in school_reference.json, and reference_file to that selected-directory-relative or absolute path. unmatched_behavior can be warn, error, or skip; skip excludes unmatched records. Per-run match CSVs distinguish exact, inexact, and no match results. Refresh the school reference when its source changes. The bundled reference records its original PHIX workbook in _meta; the pipeline reads only the prepared JSON list. Reports are school_exact.csv, school_inexact.csv, and school_no_match.csv, and added columns use the default school_ prefix.

Excluding agents from the history chart¶

ignore_agents lists exact, case-sensitive agent names to omit from the received immunization history. The bundled list contains RSVAb, VarIg, HBIg, RabIg, and Ig. Set it to [] to retain all named agents; unspecified placeholder labels are still cleaned during preparation.

This setting only changes history rows. It does not change overdue diseases, overdue agents, or notice eligibility. Source validity checks still examine the complete source history before display exclusions are applied.

QR and password placeholders¶

QR payloads and passwords are outside document presentation. Their supported fields are client_id, first_name, last_name, name, date_of_birth_iso, date_of_birth_iso_compact, school, board, street_address, city, province, postal_code, and language_code. Dates are YYYY-MM-DD and YYYYMMDD, respectively. The default password remains the compact birth date.

qr:
  enabled: true
  payload_template: "https://example.ca/update?id={client_id}&dob={date_of_birth_iso}&lang={language_code}"
encryption:
  enabled: true
  password:
    template: "{date_of_birth_iso_compact}"

The former {date_of_birth} placeholder is ambiguous because it meant a localized display value. Configuration validation rejects it early and names the two explicit ISO alternatives. Review and edit existing QR or password templates yourself; the pipeline does not silently reinterpret them.

Versions and notice selection¶

Every run takes one CSV cohort and exactly one selector: --notice-assignments PATH for explicit per-client assignments, or --template PATH for one named Typst entry point used by every accepted client. The selected version must be registered in a mapping-shaped notice_versions.yaml with integer schema_version: 1:

schema_version: 1
versions:
  overdue_diseases_v1:
    kind: overdue
  overdue_agents_v1:
    kind: overdue
  affirmative_schedule_v1:
    kind: affirmative

Kinds overdue, affirmative, and informational imply has_overdue, no_overdue, and any eligibility. A version can set requires explicitly to one of those values. Eligibility always follows the overdue disease list, even when a template displays vaccine agents. The catalog does not choose a language or assign a version to a client. The affirmative version's no_overdue rule checks an empty overdue_diseases list from the source assessment. An affirmative notice is selected only by an explicit manifest row or --template; it is not inferred from an empty list. An eligibility conflict fails preflight.

For per-client selection, the JSON manifest is an array with one client_id and one template filename for every accepted client:

[
  {"client_id": "1009876545", "template": "overdue_agents_v1.fr.typ"},
  {"client_id": "2001234567", "template": "affirmative_schedule_v1.en.typ"}
]

The template value is a basename, not a path. It resolves only within the packaged or selected complete template directory. Both selection routes parse <version_id>.<language>.typ with supported ISO 639-1 language codes en and fr; missing or unsupported language codes and path components are rejected. The filename supplies version_id and language. The authored Typst entry point independently asserts that same identity. Optional experiment_id and experiment_arm are retained as provenance. An explicit source version_id must agree with the filename. Missing client rows, unknown versions, conflicting assignments, invalid catalogs, and eligibility failures stop before rendering, with client-linked findings in the run output. Set notice_versioning.extra_manifest_rows to error or warn for rows without a matching source client.

For one version and language across the accepted cohort, pass the entry file:

immuknow students.csv \
  --template /path/to/my-phu/overdue_diseases_v1.en.typ

The filename must be <version_id>.<language>.typ, with a version in the catalog. The file's containing template tree supplies its helpers and assets. Each accepted client must satisfy that version's eligibility rule. The --template option cannot be combined with --notice-assignments or --templates.

Manifest selection uses packaged entry points by default, or --templates DIRECTORY for an external complete tree. The maintained examples include disease and agent overdue notices in English and French, and an English affirmative notice. A missing version/language pair fails; no other language or PHU directory is substituted. Every entry point declares its own version and language and rejects mismatched JSON. See template authoring for the native contract.

Updating reference data¶

vaccine_reference.json maps vaccine codes to configured disease names. disease_normalization.json maps source disease names to configured disease names. Keep their output names consistent with the chart and translations. Translation files map each configured disease name to one approved display label; chart and overdue contexts may use different wording. Update reference data and the relevant real-render tests together. A new language also needs an authored and reviewed entry point; adding dictionaries alone does not create a notice.