For each case to code, the HIS opens a coding session, embeds the returned URL in an iframe, and either receives the result via webhook or pulls it from a GET endpoint.

Open a coding session

The HIS POSTs the patient SPIGES XML wrapped as data. instanceId is HIS-supplied — it correlates the submission (one POST), not each case inside it. The data payload can carry one or many SPIGES <Fall> elements; they all belong to the same coding session and share the same instanceId. The id MUST be unique — a second POST with an instanceId still in use returns 409 Conflict with the existing sessionId in the body; the id becomes free once the original session completes. KodeMed echoes it back in the webhook so the HIS matches the result against its original submission. sessionId is server-generated.

The 201 response carries sessionId (UUID v4) and redirectUrl. The HIS embeds the redirectUrl in an iframe.

Pull the result (fallback when not using a webhook)

Two identifiers, one source of truth

• instanceId — HIS-supplied correlator for the submitted data payload. One instanceId maps to one POST; the payload may carry one or many SPIGES <Fall> cases — all share this id. MUST be unique across active sessions (duplicate → 409 Conflict). Echoed back in the webhook for HIS-side matching.
• sessionId — UUID v4 generated by KodeMed when accepting the session. Used by the iframe URL, the result GET, and the webhook payload. Use it for KodeMed-side tracing.

There is no separate correlationId in the contract — only the two above. The OpenAPI spec (linked below) is the source of truth.

For HIS REST integrations, KodeMed fires the webhook server-side when the coder clicks Apply or Discard. The URL, signing strategy, retry schedule and event filter are configured per-IntegrationProfile via the admin API; there are no env vars for this flow. The payload below is the canonical v1.0 wire and validates against WebhookPayload-1.0.schema.json.

For the legacy DLL flow, the HTTP POST is fired by the DLL itself and configured via the KODEMED_HOOK_* env vars on the Server. See the Configuration Reference → DLL Webhook for that path.

Outbound payload

If you submit more than one case per POST, read caseResults[], not codingResult. One POST may carry many SPIGES <Fall> cases (up to 50 <Standort>), and the singular codingResult describes only the first one — it is byte-identical to caseResults[0].codingResult. A partner submitting ten cases and reading only codingResult books one result and silently loses nine: the coded SPIGES in data still contains all ten, so nothing errors.

The identity is the pair (siteId, caseId), not caseId alone. SPIGES scopes fall_id to a single <Standort>, so two sites of the same operator may legitimately carry the same one. Key your HIS-side booking on the pair. Both fields are additive and optional — a single-case integrator needs no change — but a receiver validating against a pinned pre-2026-09-25 copy of the canonical schemas will reject them; re-fetch the schemas when you upgrade. Full contract: HIS REST Integration Spec §5.3.

Retry schedule

• 4 attempts: ~30s, ~2min, ~10min between attempts (configurable per profile).
• HTTP 5xx, 408, 429, network errors → retried.
• HTTP 4xx (except 408, 429) → terminal → payload moves to the dead-letter queue (DLQ).
• DLQ replay through the admin API: POST /api/v1/admin/webhook-failures/{id}/replay.

Signature verification (HMAC-SHA256)

When webhook.signing=HMAC_SHA256 is set on the IntegrationProfile, the HIS reads the Authorization: HMAC-SHA256 t=<unix>,v1=<hex> header and re-computes HMAC-SHA256 over <t>.<raw body> with the shared secret. Reject the request if the timestamp is older than 5 minutes (replay protection).

Node receiver:

Python receiver:

The HIS keeps its own OIDC-compliant Identity Provider — Keycloak, Azure AD, Okta, Auth0, Ping, Authelia, KodeMed’s bundled Keycloak, any vendor that implements OpenID Connect Discovery + RS256-signed JWTs. KodeMed validates the JWT against the configured issuer; no second login on the KodeMed side, no federation, no token exchange.

Issuer configuration

• Issuer URL format: whatever your IDP publishes. Common shapes — Keycloak: https://<host>/realms/<realm>; Azure AD: https://login.microsoftonline.com/<tenant>/v2.0; Okta: https://<org>.okta.com/oauth2/default. The exact value is what appears in the iss claim of issued tokens.
• JWKS auto-discovery via <issuer>/.well-known/openid-configuration — no manual key exchange. KodeMed reads jwks_uri from the discovery document and refreshes keys on rotation.
• Algorithm: RS256 (asymmetric). HS256 / symmetric secrets are not accepted — they require sharing the signing key with KodeMed, which defeats the IDP boundary.
• Audience (aud) check: optional; configurable per IntegrationProfile (oidc.audience).
• Multi-issuer: KodeMed can validate tokens from N issuers (test + prod, or several HIS partners). Each issuer corresponds to one IntegrationProfile — different partners can run different IDP products side by side.
• The KodeMed host needs HTTPS reachability to the issuer URL.

Required token claims

Required role names

Configure the following role (or group) names in your IDP so authorisation works by default. On Keycloak that’s a realm role; on Azure AD an app-role mapped through groups; on Okta a group claim. Override the names per profile if the partner cannot use these defaults.

• kodemed-coder — access to the coding UI and POST /api/v1/coding/session.
• kodemed-admin — access to admin endpoints (/api/v1/admin/*) including DLQ replay.
• kodemed-viewer — read-only access (optional; not enforced today, planned).

The HIS opens KodeMed’s redirectUrl in an <iframe>. KodeMed sets Content-Security-Policy: frame-ancestors to allow only the configured HIS hostnames; everything else is blocked.

It takes two settings, and only the first one unblocks the browser. The framed document is the CodingUI, served by its own proxy — and browsers honour the framed document’s CSP, not the API’s. Setting only the IntegrationProfile leaves the iframe blank with the UI still sending frame-ancestors 'none'.

1. On the server host — this is the one that unblocks it. Put KODEMED_EMBED_ALLOWED_ORIGINS="https://your-his.example.com" in .env and re-run setup.sh. That single key writes both the UI proxy’s frame-ancestors and the allowlist for the cross-origin token-refresh channel. Unset, the behaviour is today’s: DENY everywhere. Wildcards, bare schemes and paths abort the setup rather than widening the allowlist silently. Full guide: EMBEDDING.md.
2. Then per IntegrationProfile: embed.cspFrameAncestors: ["https://your-his-test.example.com", "https://your-his.example.com"] (admin API) — the same list, so the API origin’s CSP agrees. Keep the two consistent; GET /api/v1/integration/csp reports what the server believes.

• Cookies on the KodeMed UI are already SameSite=None; Secure, so cross-origin iframe sessions work without changes on the HIS side.
• Legacy: the demo deployment historically used X-Frame-Options: DENY. The new flow replaces this with the per-profile CSP frame-ancestors.

The full contract is published as OpenAPI 3.1 by every service. Same paths apply on a self-hosted installation — substitute your KodeMed hostname.

The Authorize button on Swagger UI accepts a test JWT directly, once your realm issuer is configured.

Which component talks to which. Use this to size a deployment, open firewall holes, or scope a security review. Read each section for a different concern — A is what to expose externally, B is egress your network must allow, C is intra-host wiring (Docker compose / OpenShift), D is local-machine COM bridges.

A. Customer-facing — partner / browser ↔ KodeMed via Caddy on port 443

Open these in the partner firewall. The Public URL column shows illustrative production names (kodemed.ch subdomains); the live demo uses demo-* prefixes, and your on-prem install substitutes its own hostnames.

B. Outbound from KodeMed — egress rules

Allow these in the KodeMed host's outbound firewall. Endpoints reach the public internet (or partner-side webhooks).

C. Internal — container ↔ container on the host network

These ports are NOT exposed externally. Docker compose wires them on the kodemed network; OpenShift wires them via Services. Open them in firewall ONLY if you split components across hosts.

D. Local-machine — COM DLL bridge (Windows host only)

In-process COM activation + a loopback WebSocket between the COM DLL and the CodingClient tray. Nothing leaves the workstation.

Auth column conventions — OIDC JWT (user) is the browser-bearer access token (audience: kodemed-ui). service JWT (internal) is the audience-restricted token issued by KodeMed Server to call DataServer / Grouper. HMAC-SHA256 applies only to HIS webhooks. All HTTPS hops carry standard security headers (HSTS, CSP, X-Frame-Options) enforced by SecurityConfig. See Roles & Permissions for the role-name table.

Happy-path flow from HIS-initiated session create to webhook delivery + result fetch.

sequenceDiagram
    autonumber
    participant HIS as HIS
    participant IDP as Partner OIDC IDP
    participant S as KodeMed Server
    participant UI as KodeMed UI
    participant WH as HIS webhook

    HIS->>IDP: client_credentials
    IDP-->>HIS: JWT
    HIS->>S: POST /api/v1/coding/session
{ data, format:"spiges", source:"API", instanceId }
    S->>S: validate JWT (JWK)
    S->>S: persist session
    S-->>HIS: 201 { sessionId, instanceId, redirectUrl, expiresAt }
    HIS->>UI: load redirectUrl in iframe
    Note over UI: coder edits, presses Apply
    UI-->>S: result
    S->>WH: HMAC-sign + POST (Authorization + X-KodeMed-Signature)
{ eventType, sessionId, instanceId, occurredAt,
format, data, codingResult }
    WH-->>S: 2xx
    opt HIS without webhook
        HIS->>S: GET /api/v1/coding/session/{id}/result/data
        S-->>HIS: 200 data (SPIGES)
    end

If the webhook gets a 5xx/timeout, KodeMed retries with the per-tenant webhookRetryDelaysSeconds (default 30s, 2m, 10m) and persists to the dead-letter queue if all attempts fail (replay via POST /api/v1/admin/webhook-failures/{id}/replay).

In-process integration via the COM DLL for HIS that cannot make HTTPS calls but can load a Windows DLL. Same end-state (modified SPIGES returned to HIS) but the transport is COM ↔ loopback WebSocket ↔ KodeMed Server.

sequenceDiagram
    autonumber
    participant HIS as HIS process
    participant DLL as COM DLL
    participant CC as CodingClient (tray)
    participant S as KodeMed Server
    participant B as Browser

    HIS->>DLL: StartCoding(spiges)
    DLL->>CC: ws://127.0.0.1:9876
    CC->>S: wss /ws/dll
(Authorization: Bearer JWT)
    S-->>CC: dll.connected
    CC->>S: app.coding_session_launch
{ sessionId, data, format }
    S->>B: open in browser
    Note over B: coder edits, presses Apply
    S-->>CC: case.coded
{ sessionId, payload: { action:"APPLIED", data, codingResult } }
    CC-->>DLL: result
    DLL-->>HIS: result (SPIGES)

The DLL writes the modified SPIGES back to the HIS in-process. No outbound webhook is fired in this flow — the HIS already has the result by the time StartCoding returns.

Failure path. Server retries on 5xx / 408 / 429 / network errors with the per-tenant webhookRetryDelaysSeconds schedule; after the last attempt the payload is persisted to the WebhookFailure dead-letter table and an admin can replay it.

sequenceDiagram
    autonumber
    participant S as KodeMed Server
    participant WH as HIS webhook
    participant DLQ as WebhookFailure (DLQ)
    participant ADM as Admin

    S->>WH: attempt 1 (POST)
    WH-->>S: 503
    Note over S: wait 30s
    S->>WH: attempt 2 (POST)
    WH-->>S: timeout
    Note over S: wait 2m
    S->>WH: attempt 3 (POST)
    WH-->>S: 502
    Note over S: wait 10m
    S->>WH: attempt 4 (POST)
    WH-->>S: 502
    S->>DLQ: persist row
{ profileSlug, sessionId, instanceId,
eventType, payload, attempts:4,
lastError, lastHttpStatus }
    ADM->>DLQ: GET /api/v1/admin/webhook-failures
    DLQ-->>ADM: 200 [ {id,…}, … ]
    ADM->>S: POST .../{id}/replay
    S->>WH: replay POST
    WH-->>S: 200
    S->>DLQ: mark row delivered

Retry schedule + max attempts are stored on the IntegrationProfile per partner. Default is 4 attempts at 30s / 2m / 10m (3 delays = retryMax − 1). Idempotency: the Idempotency-Key header is stable across retries so the HIS can dedupe.

For HIS that cannot host a public webhook endpoint. Create the session, poll for completion. Same end-state as the webhook flow but driven by the HIS.

sequenceDiagram
    autonumber
    participant HIS as HIS
    participant S as KodeMed Server
    participant UI as KodeMed UI

    HIS->>S: POST /api/v1/coding/session
    S-->>HIS: 201 { sessionId, instanceId, redirectUrl, expiresAt }
    HIS->>UI: open redirectUrl in iframe
    Note over UI: coder edits, presses Apply
    UI-->>S: result
    loop poll every 5-30s
        HIS->>S: GET /api/v1/coding/sessions/{sessionId}/status
        S-->>HIS: 200 { status:"COMPLETED", action:"APPLIED" }
    end
    HIS->>S: GET /api/v1/coding/session/{id}/result/data
    S-->>HIS: 200 data (SPIGES)

Recommended poll interval: 5s while the iframe is visible, 30s after it closes. The expiresAt on the create response upper-bounds how long the session is pollable.

For native desktop integrations that already speak WebSocket. Skip the DLL transport; speak /ws/dll directly to the Server. Same message vocabulary as the DLL flow.

sequenceDiagram
    autonumber
    participant NC as Native client
    participant S as KodeMed Server
    participant B as Browser (UI)

    NC->>S: wss /ws/dll
(Authorization: Bearer JWT
or Sec-WebSocket-Protocol: kodemed.bearer.JWT)
    S-->>NC: dll.connected { instanceId }
    NC->>S: app.coding_session_launch
{ instanceId, data:SPIGES, format:"spiges" }
    S-->>NC: session.created { sessionId }
    S->>B: open in browser
    Note over B: coder Apply
    B-->>S: result
    S-->>NC: case.coded
{ sessionId, payload: { action:"APPLIED", data, codingResult } }

Token auth: prefer Authorization: Bearer <JWT> (server-to-server clients); browsers SHOULD use Sec-WebSocket-Protocol: kodemed.bearer.<JWT> instead. The legacy ?token=<JWT> query param is still accepted but logs a WARN — tokens land in access logs as plaintext. The token is validated at the WebSocket handshake (not per frame). After expiry or any disconnect, reconnect with a refreshed token; the server holds the session-id mapping in-memory for sessionExpiryMinutes.

For HIS that wants to autocomplete ICD-10 / CHOP / ATC codes in its own UI before opening a coding session. Direct REST call against the DataServer.

sequenceDiagram
    autonumber
    participant UI as HIS UI
    participant DS as DataServer
    participant PG as PostgreSQL

    UI->>DS: GET /api/thesaurus/search?q=J96.0
Authorization: Bearer JWT
    DS->>PG: SELECT … LIMIT 20
    PG-->>DS: rows
    DS-->>UI: 200 [ { code, label, version, … } ]
    UI->>DS: GET /api/thesaurus/rules/code/ICD10/J96.0?version=2026
    DS->>PG: SELECT rules WHERE code=$1 AND version=$2
    PG-->>DS: rows
    DS-->>UI: 200 { rules:[ { kind:"INCLUSION", text:"…" }, … ] }

Cached at If-None-Match / ETag; year-versioned so a 2026 lookup can never silently fall back to 2025 data. Full schema in the DataServer Swagger UI.

For HIS that wants to run a real-time SwissDRG / TARPSY / ST Reha grouping without involving a coder. Direct REST call against the Grouper.

sequenceDiagram
    autonumber
    participant HIS as HIS
    participant G as Grouper
    participant DS as DataServer

    HIS->>G: POST /api/v1/grouper/group
{ tariff:"SWISSDRG", version:"15.0",
patientCase:{ fallId, administratives, diagnosen:[…], behandlungen:[…] } }
    G->>G: load specs + catalogue (cached)
    G->>DS: POST /api/zusatzentgelt/match
    DS-->>G: supplements []
    G-->>HIS: 200 { drg:"E77C", pccl:0,
effectiveCostWeight:0.638, supplements:[…], flags:[…] }

Three tariffs: SWISSDRG (acute), TARPSY (psychiatric), STREHA (rehab) — set tariff in the body. Entry points: POST /api/v1/grouper/group (one case), /group/batch (many cases, JSON), and /spiges/xml/{tariff} (raw SPIGES XML, parses every <Fall>). These are server-to-server calls — a backend HTTP client sends no browser Origin header, so CORS never applies; the CORS allow-list only governs browser-origin calls. GET /api/v1/grouper/versions lists the loaded tariff × version combinations. Response fields (per GroupingResponse): drg, mdc, pccl, baseCostWeight/effectiveCostWeight, supplements, flags, grouperStatus.

How the clinician's JWT becomes a same-site cookie that survives the iframe load when the UI is embedded inside the HIS page.

sequenceDiagram
    autonumber
    participant B as Browser (HIS page)
    participant IDP as Partner OIDC IDP
    participant UI as KodeMed UI
    participant S as KodeMed Server

    B->>UI: iframe src=redirectUrl
    UI->>S: /actuator/info
    S-->>UI: 200
    UI->>UI: load runtime-config (issuer URL, etc.)
    B->>IDP: (silent) /authorize?prompt=none
    IDP-->>B: 302 with code
    B->>IDP: /token (PKCE)
    IDP-->>B: id_token + access_token + refresh
    B->>UI: set SameSite=None Secure cookie
    UI->>S: REST + WS calls
Authorization: JWT

The HIS site must be listed in IntegrationProfile.embedCspFrameAncestors for the browser to accept the iframe. The SameSite=None cookie attribute is mandatory for cross-origin iframe sessions and is the default for HIS REST integrations.

Validate every wire payload your integration touches against the published schemas. All four wire transports (HIS REST request/response, HIS REST webhook, WebSocket /ws/dll, COM GetResults()) share the same field names + types — one parser per concept on the HIS side. The repo's scripts/test/test-schemas-uniformity.py enforces this on every CI run; partners SHOULD validate their code against the same schemas.

HIS REST (request → response → webhook)

• SessionCreate-1.0.schema.json — POST /api/v1/coding/session request
• SessionResponse-1.0.schema.json — 201 Created response (sessionId + instanceId + redirectUrl + expiresAt)
• WebhookPayload-1.0.schema.json — outbound webhook (case.coded / case.discarded / session.expired)

WebSocket (CodingClient ↔ Server, full-duplex)

• Message-1.0.schema.json — /ws/dll envelope (eventType + occurredAt + payload)

COM DLL (in-process integration, IKodeMed.GetResults())

• GetResults-1.0.schema.json — JSON variant
• GetResults-1.0.xsd — XML variant (when OutputFormat=Xml)

Case data envelope (SPIGES XML carried inside data)

• SPIGES 1.5 · do-d-14.04-SPIGES-2025-02.xsd (“1.5” is KodeMed’s label; the XSD targetNamespace is http://www.bfs.admin.ch/xmlns/gvs/spiges-data — no version suffix)

Shared building blocks (referenced via $ref from the flow schemas above)

• _common/Identifier.schema.json — UUID (sessionId, caseId)
• _common/OpaqueIdentifier.schema.json — partner-controlled string (instanceId)
• _common/Timestamp.schema.json — ISO-8601 + Z (occurredAt, expiresAt)
• _common/EventType.schema.json — canonical event-name enum
• _common/CaseData.schema.json — data + format + dataHash + schemaVersion (composable via allOf)
• _common/CodingResult.schema.json — grouper output (DRG, PCCL, cost weight, diagnoses, procedures, supplements, warnings)
• _common/CaseResult.schema.json — per-case bundle (CaseData + CodingResult, used inside GetResults cases[])

Canonical samples (validator-checked on every CI run)

• session-create.json
• session-response.json
• webhook-payload.json
• message.json — WS case.coded
• get-results.json
• get-results.xml

See schemas/README.md for the 15 uniformity rules (R1–R15) and the canonical-vs-legacy migration notes. C# / Java / Python validator examples live in the Test.UI partner sample below.

Real test data — the same SPIGES / BFS payloads we use ourselves (CodingUI public landing page + installer demo). Pipe these through your integration end-to-end without inventing your own fixtures. See the data/ README for the full curl walkthrough.

• data/session-create-request.json — full REST request body (POST /api/v1/coding/session) with 3-case SPIGES embedded — validates against SessionCreate-1.0
• data/sample-spiges.xml — minimal SPIGES 1.4 / 1.5 demo, 3 cases (acute / surgical / rehab)
• data/test-data-full.xml — realistic Swiss medical cases, ICD-10-GM CH + CHOP 2026 codes (the "Load realistic test data" payload on the CodingUI public page)
• data/test-data-anonymized.bfs.dat — BFS pipe-delimited format (MX/MB/MD lines). Set format=bfs on the REST call to exercise BfsTransformer.

Negative examples — one per flow, each intentionally invalid. Use them to validate that your receive-side validator correctly REJECTS malformed input (R10 in the drift detector enforces this end-to-end).

• failing/session-create.json — missing required instanceId
• failing/session-response.json — sessionId not a UUID
• failing/webhook-payload.json — snake_case event_type (legacy drift)
• failing/message.json — non-canonical "CONNECTED" enum value
• failing/get-results.json — legacy codingAction top-level field
• failing/get-results.xml — non-UUID sessionId + case_coded underscore drift

A single-window C# WinForms app that exercises the COM DLL integration surface end-to-end (SendConfig + DoCoding + DoCodingWithFormat + GetResults). The DLL handles REST session create, iframe embed, and WebSocket signalling internally on the partner's behalf — partners reading this sample see only the COM call site. Partners integrating via the HIS REST contract directly (server-to-server, no DLL) MUST implement their own webhook receiver per KodeMed_HIS_REST_Integration_Spec §5.3 and validate against WebhookPayload-1.0.schema.json — the sample's README has the receive-side validator snippets.

• kodemed/KodeMed.Test.UI on GitBucket — canonical source, fork it / open PRs / track upstream
• KodeMed.Test.UI · offline sources (.csproj + .cs + .ico) — .NET 9, no bin/obj
• KodeMed.dll — the signed assembly the standalone build references; goes in lib/
• KodeMed.xml — IntelliSense documentation for it; same folder

It does not build straight out of the zip. Outside our monorepo the project file references lib\KodeMed.dll, which is deliberately not in the archive — it is a signed binary published separately, above. The bundled script fetches it for you:

# Option 1 — clone the GitBucket repo (always up to date)
git clone ssh://git@www.mieresit.com:7777/kodemed/KodeMed.Test.UI.git
cd KodeMed.Test.UI
run-sample.cmd                 # pulls, downloads KodeMed.dll, builds, runs

# Option 2 — offline zip
unzip KodeMed.Test.UI-sources.zip
cd KodeMed.Test.UI
run-sample.cmd

# Option 3 — by hand, if you would rather not run the script
curl -fLo lib\KodeMed.dll https://<this-portal>/windows/KodeMed.dll
curl -fLo lib\KodeMed.xml https://<this-portal>/windows/KodeMed.xml
dotnet restore
dotnet run

Needs the .NET 9 SDK on Windows x64. run-sample.cmd -SkipDll -SkipPull is the fast rebuild once the DLL is in place.

The Server forwards user feedback to GitBucket (issues) and SMTP (email). All keys can be left empty in environments where neither is desired. Disable the entire subsystem with KODEMED_FEEDBACK_ENABLED=false.

For HIS REST integrations the Server fires the webhook itself. Configuration is per-IntegrationProfile in the database (set via the admin API). There are no env vars for this flow — the values below are profile fields, not .env entries. Field names are camelCase (Spring Boot Jackson default), matching the IntegrationProfileDtos.WebhookRequest DTO.

For the full payload shape, retry semantics, DLQ replay path and HMAC signature verification snippets, see Integration → Webhook Contract.

Data import/export service — ICD-10, CHOP, thesaurus, hot-folder import.

DRG grouper — stateless service for SwissDRG, TARPSY, ST Reha grouping. No database required.

React frontend served via nginx. Configured at runtime via runtime-config.js.

These variables shape Caddyfile.* and the per-service routing in docker-compose.caddy.yml. They have no effect on KodeMed services themselves — only on the TLS / hostname layer.

The portal pages (downloads demo + prod) are protected by oauth2-proxy sidecars in docker-compose.demo.yml. Two distinct OIDC clients allow demo-portal and prod-portal to live behind the same Keycloak realm without sharing cookies.

Used by the wizard’s localhost preset and by the optional docker-compose.keycloak.yml overlay. Customers using their own Keycloak (HIS REST integrations) do not need any of these — only the issuer URL matters then.

Windows desktop DLL integration. Config file: kodemed-client-config.json (next to DLL or %APPDATA%\KodeMed\).

Use these public endpoints (no authentication required) to verify your deployment:

HTTP 402 on any endpoint means the license is invalid or missing. Check KODEMED_LICENSE_FILE path and verify with: java -jar kodemed-license-cli.jar verify --public-key kodemed-public.pem --license kodemed.license