Medical cabinets

Medical cabinet integrations need to identify which patients are served by each cabinet. In Open Aidn, configure each cabinet with the department ID for its location, then search EpisodeOfCare for care episodes managed by that department.

Scenario

The vendor operates one or more medication cabinets for a municipality. Each cabinet is installed at a physical location. Such as a department or ward. The vendor’s system periodically requests the patients served at that location, so medication workflows can be limited to the relevant care context.

Required setup

Configuration	Owner	Description
OAuth client	Municipality or Aidn administrator	Client configured for the vendor and environment. See Municipality setup.
Client private key	Vendor	Private key corresponding to the registered public key. The vendor can generate this key pair, or the admin portal can generate it during client setup. Store it securely.
Scope	Municipality or Aidn administrator	The client needs `episodeofcare.search`. Add `episodeofcare.read` only if the integration must read individual resources by ID.
Department ID	Municipality	The department ID representing the cabinet’s physical location.
Integration enabled for municipality	Municipality or Aidn administrator	The municipality must enable the medical cabinet integration before it can receive requests.

Data flow

sequenceDiagram
    participant Admin as Municipality admin
    participant Vendor as Cabinet vendor
    participant IdP as Aidn identity provider
    participant FHIR as Open Aidn FHIR API

    Admin->>Admin: Enable integration for municipality
    Admin->>Admin: Create OAuth client and select scopes
    Admin->>Vendor: Provide client ID, key ID, environment, and department ID
    Vendor->>IdP: Request access token using private_key_jwt
    IdP-->>Vendor: Access token with approved scopes
    Vendor->>FHIR: Search EpisodeOfCare by department ID
    FHIR-->>Vendor: FHIR Bundle with matching care episodes and optional patients

Fetch patients for a cabinet

Use the configured department ID as the organization search parameter.

POST /EpisodeOfCare/_search HTTP/1.1
Host: <OPEN_AIDN_FHIR_HOST>
Accept: application/fhir+json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <ACCESS_TOKEN>

organization=<DEPARTMENT_ID>&_include=EpisodeOfCare:patient

The response is a FHIR Bundle:

EpisodeOfCare entries with search.mode = match represent care episodes for the configured department.
Patient entries with search.mode = include are returned when _include=EpisodeOfCare:patient is requested.
EpisodeOfCare.patient.reference points to the matching Patient resource.
EpisodeOfCare.managingOrganization.identifier.value contains the department ID used for the location.

Filtering by service type

If the integration should only include selected service types, add one or more type parameters. Current values map to IPLOS codes where applicable.

POST /EpisodeOfCare/_search HTTP/1.1
Host: <OPEN_AIDN_FHIR_HOST>
Accept: application/fhir+json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <ACCESS_TOKEN>

organization=<DEPARTMENT_ID>&type=<IPLOS_CODE>&_include=EpisodeOfCare:patient

Filter by service type only if agreed during onboarding. If no type is supplied, Open Aidn doesn’t filter by service type.

Validation checklist

Before production rollout, validate the setup with the municipality:

The configured department ID represents the cabinet’s physical location.
The OAuth client belongs to the correct municipality and environment.
The client can request episodeofcare.search.
The search returns only patients expected for the configured department.
The vendor handles empty search results without treating them as an error.
Key rotation and incident contacts are agreed.

Back to home