Medical cabinets

Medical cabinet integrations need to know which patients are relevant for a physical medication cabinet location. In Open Aidn this is solved by configuring each cabinet with the department ID that represents its location, then searching EpisodeOfCare for care episodes managed by that department.

Scenario

The cabinet 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 system periodically requests the patients relevant for that location so medication workflows can be limited to the correct care context.

Required setup

Configuration	Owner	Description
Integration enabled for municipality	Municipality or Aidn administrator	The medical cabinet integration must be enabled before OAuth clients can be created.
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.

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 location

Use the configured department ID as the organization search parameter.

GET /EpisodeOfCare/_search?organization=<DEPARTMENT_ID>&_include=EpisodeOfCare:patient HTTP/1.1
Host: <OPEN_AIDN_FHIR_HOST>
Accept: application/fhir+json
Authorization: Bearer <ACCESS_TOKEN>

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.

GET /EpisodeOfCare/_search?organization=<DEPARTMENT_ID>&type=<IPLOS_CODE>&_include=EpisodeOfCare:patient HTTP/1.1
Host: <OPEN_AIDN_FHIR_HOST>
Accept: application/fhir+json
Authorization: Bearer <ACCESS_TOKEN>

Only use service type filtering when this has been agreed during onboarding. If no type is supplied, Open Aidn does not 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 the homepage