OKAPI onderdelen

OKAPI kent een drietal kernonderdelen: onboarding, activeren / configureren van diensten en aanmelden van patiënten. Daarnaast biedt OKAPI een interface aan voor het opvragen van events, bijvoorbeeld voor het inrichten van logging / audit doeleinden.

Binnen de OKAPI specificatie worden twee rollen gedefinieerd:

1. Zorginformatiesysteem (client)

   Met zorginformatiesysteem wordt het systeem bedoeld dat patientinformatie beheert voor een zorgverlener en dat gebruik wil maken van een dienst om bepaalde functionaliteit te implementeren dat het zelf niet kan of wil implementeren. De zorginformatiesysteem is het systeem dat het client gedeelte van OKAPI implementeert.

2. Dienstverlener (server)

   Met dienstverlener wordt het systeem bedoeld dat een leverancier aanbiedt om bepaalde functionaliteit te implementeren (diensten aan te bieden) voor het zorginformatiesysteem. De dienstverlener is het systeem dat het server gedeelte van OKAPI implementeert. Dit moet niet verward worden met het feit dat de dienstverlener na het opzetten van een koppeling met OKAPI de rol van client zal vervullen. D.w.z. nadat de koppeling is opgezet met OKAPI zal de dienstverlener informatie ophalen van, en opsturen naar, het zorginformatiesysteem.

Voor elk component heeft OKAPI een aantal methodes gedefinieerd. De verschillende onderdelen en bijbehorende methodes worden hieronder uiteengezet.

info

OKAPI vereist dat een applicatie die de OKAPI specificatie implementeert zijn GRPC interface alleen over een TLS verbinding aanbiedt.

Onboarding - de koppelprocedure

Het onboarding onderdeel heeft als doel een zorginformatiesysteem te koppelen met een dienstverlener zodat het zorginformatiesysteem en de dienstverlener hierna op een gestandariseerde manier en over een veilig kanaal informatie kunnen uitwisselen.

De onboarding bevat twee methodes (strikt genomen drie maar de GetMetadata methode is niet noodzakelijk voor de koppelprocedure). Deze twee methodes moeten in een bepaalde volgorde worden aangeroepen om de koppelprocedure succesvol te doorlopen. Als eerste moet de Register methode moeten worden aangeroepen.

Register methode

De Register methode wordt gebruikt door het zorginformatiesysteem om een verzoek om te koppelen in te dienen bij de dienstverlener. Met een koppeling wordt hier een veilig (versleuteld en geauthenticeerd) kanaal bedoeld waarover kan worden gecommuniceerd. Het zorginformatiesysteem geeft bij het aanroepen van de Register methode aan welke organisatie het vertegenwoordigt en welk authenticatiemiddel het zal gaan gebruiken om zichzelf te authenticeren richting OKAPI.

Hieronder een voorbeeld van hoe een aanroep van de Register methode eruit kan zien.

    RegisterRequest{
        OrganisationFormalName: "Voorbeeld zorgaanbieder",
        OrganisationDisplayName: "Voorbeeld zorgaanbieder",
        OrganisationIdentifier: "11119999-0000",
        OrganisationIdentifierType: "http://kvk.nl/kvk-nummer",
        Auth: XISAuthConfiguration{
            Method: XISAuthMethod.MTLS,
            MTLSConfigurationParams: MTLSConfig{
                PublicKey: "{\"crv\":\"P-256\",\"kty\":\"EC\",\"x\":\"PZlyqX3XAhvBE..."
            }
        }
    }

Client credentials

De Register call kan nog worden aangeroepen zonder client credentials. Alle navolgende calls MOETEN worden aangeroepen met de client credentials zoals aangegeven in de XISAuthConfiguration. De dienstverlener is ook VERPLICHT om deze te controleren / valideren.

info

De voorbeelden zijn geschreven in een versimpelde vorm van Go. De syntax van Go wordt voor een groot gedeelte aangehouden maar om de leesbaarheid te bevorderen zijn bepaalde onderdelen wat simplificeerd of weggelaten. Dit omdat de voorbeelden voornamelijk illustreren hoe de verschillende datatypes in de verschillende methodes gevuld zullen / moeten worden en niet zo zeer om implementatie voorbeelden te geven. Zo worden onder andere imports, variabelen en package declarations weggelaten en is de instantiering van bepaalde types versimpeld.

Een voorbeeld hiervan is wanneer een in protobuf definieerd Struct datatype wordt gebruikt. Dit wordt in de voorbeelden om de volgende manier gedaan:

Auth{
  Config: protobuf.Struct{
    "key": "value",
  }
}

In de realiteit zou dit er als volgt uitzien:

package ...

import (
  "google.golang.org/protobuf/types/known/structpb"
)

//...

auth := Auth{}

cfg, err := structpb.NewStruct(map[string]interface{}{
  "key": "value",
})

auth.cfg = cfg

//...

In reactie op het aanroepen van de Register methode wordt een unieke identifier teruggeven voor deze registratie. Deze is noodzakelijk om later in het proces de registratie om te zetten in een koppeling.

    RegisterResponse{
        Reference: "1234-abcd-...",
    }

Eventueel kan voordat de Register methode aangeroepen wordt de GetMetadata methode worden aangeroepen om informatie over de dienstverlener op te vragen. Dit om feedback te kunnen geven aan een eindgebruiker over welke dienstverlener het gaat. Bijvoorbeeld door deze informatie in een UI te tonen voordat de eindgebruiker doorgaat met het daadwerkelijk registreren ¹.

Nadat het registratieverzoek is aangekomen, zal een beheerder aan de kant van de dienstverlener het registratieverzoek moeten valideren. Bijvoorbeeld door de informatie over de verantwoordelijke organisatie achter het zorginformatiesysteem op te zoeken in het KvK register, contact op te nemen met deze organisatie en zodoende te controleren of het verzoek daadwerkelijk vanuit deze organisatie is verstuurd.

Eenmaal gevalideerd zal de eindgebruiker een autorisatiecode genereren voor het koppelverzoek en deze via een out-of-band kanaal, bijvoorbeeld via de post of zorgmail, doorgeven aan een eindgebruiker van het zorginformatiesysteem. Naast het genereren van een autorisatiecode wordt de status van de registratie geüpdate zodat deze omgezet kan worden naar een werkende koppeling met de CompleteRegistration methode.

info

Dit is een goed moment voor de dienstverlener om de aangeboden diensten in te richten voor gebruik door het zorginformatiesysteem, indien nodig. Bijvoorbeeld het aan- of uitzetten van bepaalde diensten voor deze specifieke koppeling. Hoe dit proces wordt ingericht is geen onderdeel van de OKAPI specificatie. Wel deel van de specificatie is de wijze waarop het zorginformatiesysteem de verschillende diensten die de dienstverlener aanbiedt kan configureren. Dit wordt in de sectie Configureren van diensten uiteengezet.

Als de autorisatiecode in handen is van een eindgebruiker van het zorginformatiesysteem, kan de koppeling gecompleteerd worden d.m.v. de CompleteRegistration methode.

CompleteRegistration methode

CompleteRegistration wordt door het zorginformatiesysteem gebruikt om een registratie om te zetten in een werkende koppeling. Bij het aanroepen van de CompleteRegistration methode wordt de verkregen autorisatiecode meegegeven evenals de unieke identifier (reference) voor de openstaande registratie.

Voor deze call en alle navolgende calls MOET het client credential gebruikt worden dat aangegeven werd in de Register call (XISAuthConfiguration).

Hieronder een voorbeeld van hoe de argumenten van een aanroep van de CompleteRegistration methode eruit ziet.

    CompleteRegistrationRequest{
        Reference: "1234-abcd-...",
        AuthorisationToken: "4567-CDEF-..."
    }

Na validatie van de unieke identifier in combinatie met de autorisatiecode wordt de registratie omgezet in een geactiveerde koppeling en kan deze gebruikt worden door het zorginformatiesysteem.

Activeren / configureren van diensten

Een dienst is bepaalde functionaliteit die wordt geimplementeerd door de dienstverlener, vaak in de context van een set patiënten. Een dienstverlener kan dus meerdere diensten aanbieden binnen diens systeem. De dienstverlener kan er ook voor kiezen bepaalde diensten in of uit te schakelen voor specifieke zorginformatiesystemen (zie infoblok hierboven).

Als er een koppeling is opgezet en als de set diensten is ingericht door een beheerder van de dienstverlener kunnen de beschikbaar gestelde diensten geconfigureerd worden door het zorginformatiesysteem. Het activeren / deactiveren van een dienst, en het inregelen van welke protocollen gebruikt worden voor het ophalen en / of terugsturen van patiëntinformatie door de dienstverlener richting het zorginformatiesysteem, is een explicite stap die moet worden genomen door het zorginformatiesysteem of diens beheerder of gebruiker.

Om te weten te komen welke diensten de dienstverlener aanbiedt kan het zorginformatiesysteem de ListServices methode aanroepen.

ListServices methode

De ListServices methode geeft een datastructuur terug met daarin een lijst van welke diensten deze aanbiedt aan het zorginformatiesysteem.

Hieronder een voorbeeld van de datastructuur die de ListServices methode teruggeeft met als voorbeeld een MedMij DVZA dienst.

ListServicesResponse{
  Services: []Service{
    Id: "dvza",
    Name: "MedMij DVZA",
    Description: "MedMij DVZA implementatie"
    SubscriptionPolicy: SubscriptionPolicy.optout,
    ConsentPolicy: ConsentPolicy.none,
    FetchProtocols: []ProtocolDefinition{
        Protocol: "https://decozo.org/proto/fetch/fhir",
        AuthMethods: ["http://decozo.org/proto/auth/jwt"]
    }, {
        Protocol: "http://decozo.org/proto/fetch/example",
        AuthMethods: ["http://decozo.org/proto/auth/mtls", "http://decozo.org/proto/auth/bearer-token"]
    },
    // Lege lijst, geen pushback protocollen beschikbaar
    PushProtocols: []ProtocolDefinition{},
    // Lege configuratie, geeft aan dat er niks geconfigureerd is voor het
    // ophalen van patient informatie
      FetchConfiguration: CallbackConfiguration{},
    // Lege configuratie, geeft aan dat er niks geconfigureerd is voor het
    // terugsturen van patient informatie
      PushConfiguration: CallbackConfiguration{},
    // De dienst is nog niet geactiveerd
      Enabled: false
  }
}

In de response wordt aangeven dat de dienstverlener een MedMij DVZA dienst aanbiedt met de volgende eigenschappen:

• Id
  De dienst heeft de identifier dvza, gebruikt om binnen het de dienstverlener deze dienst aan te duiden.
• Name, Description
  Naam en omschrijving voor het tonen aan een eindgebruiker ter identificatie van deze dienst
• SubscriptionPolicy
  De dienst verwacht dat patiënten worden aangemeld onder een opt-out policy, wat betekend dat elke patiënt wordt aangemeld tenzij aangeven dat deze dat niet wil.
• ConsentPolicy
  De waarde van het ConsentPolicy veld is het geval van een opt-out subscription policy altijd ConsentPolicy.none. Zie hieronder meer informatie over policies.
• FetchProtocols
  De dienst geeft aan dat het twee protocollen (https://decozo.org/proto/fetch/fhir, http://decozo.org/proto/fetch/example) kent voor het ophalen van patiëntgegevens. Dit betekent dat de dienst werkende implementaties heeft voor deze twee protocollen. Per protocol staat aangegeven welke authenticatie / autorisatie methodes voor de deze protocollen beschikbaar zijn (AuthMethods). De waardes (https://decozo.org/proto/fetch/fhir, http://decozo.org/proto/fetch/example, http://decozo.org/proto/auth/mtls etc) zijn slechts indentifiers voor een protocol of authenticatie / autorisatie methode. Zie het info blok hieronder voor meer informatie over identifiers en protocollen.
• PushProtocols
  Hierin wordt aanggeven welke protocollen deze dienst kent voor het terugsturen van informatie (pushback). Voor deze dienst is dat geen enkele.
• FetchConfiguration Hierin wordt aangegeven hoe de dienst momenteel geconfigureerd is
• PushConfiguration Hierin wordt aangegeven hoe de dienst momenteel geconfigureerd is
• Enabled Hierin wordt aangegeven of de dienst momenteel geactiveerd is

info

Het is wenselijk dat identifiers in URI vorm zijn. In dit voorbeeld zijn de identifiers in de vorm van een URL. Als de identifiers in URL vorm zijn is het verplicht om deze ook te kunnen resolven. Dit biedt een manier om extra informatie over het protocol beschikbaar te stellen. Het belangrijkste is dat zowel dienstverlener en zorginformatiesysteem een protocol identificeren met dezelfde identifier en weten hoe deze te implementeren. In het OKAPI standariseringsproces zal aandacht besteed worden aan het opnemen van enkele standaard protocollen en het standariseren van de namen (URIs) daarvan.

De werking van deze protocollen (en authenticatie / autorisatie methodes) wordt niet gespecificeerd binnen OKAPI. Er zullen vanuit Decozo een aantal protocollen worden gespecificeerd maar het is voor andere partijen ook mogelijk om protocollen te ontwikkelen / specificeren. Het is wenselijk dat deze specificaties online gepubliceerd worden, en zoals eerder aangegeven het protocol dan ook te identificeren met de URL waarop deze informatie gepubliceerd is.

Aanmeld- en toestemmingsopties

In het bovenstaande voorbeeld worden twee voorbeeld policies voor aanmelden en toestemming gegeven (SubscriptionPolicy en ConsentPolicy). De mogelijke opties zijn:

Subscription policy

1) SubscriptionPolicy.optin Met een opt-in policy wordt aangegeven dat patiënten expliciet moeten worden aangemeld voor deze dienst. 2) SubscriptionPolicy.optout Met een opt-out policy wordt aangegeven dat patiënten automatisch moeten worden aangemeld voor deze dienst. Als een patiënt dat niet wilt moet deze expliciet worden uitgeschreven.

Consent policy

Een consent policy geeft aan of een patient toestemming moet geven voordat een aanmelding mag plaatsvinden. De consent policy heeft alleen invloed op hoe een opt-in dienst werkt. Bij een opt-out subscription policy MOET de ConsentPolicy.none worden meegegeven.

1) ConsentPolicy.explicit Met een explicit policy wordt aangegeven dat patiënten expliciet toestemming moeten geven voor deze mogen worden aangemeld bij deze dienst. 2) ConsentPolicy.presumed Met een presumed policy wordt mogen patienten worden aangemeld onder veronderstelde toestemming. D.w.z. ... [Guido aanvullen]

EnableService methode

Voordat de dienstverlener informatie op kan halen of terug kan sturen naar het zorginformatiesysteem moet de dienst door het zorginformatiesysteem worden geactiveerd en daarmee ook worden ingeregeld hoe de dienstverlener op een later moment het zorginformatiesysteem kan aanroepen. De configuratie betreft (een van) de fetch en push protocollen uit de ListServices lijst.

Hieronder een voorbeeld van een aanroep van de EnableService methode waarin de in het vorige voorbeeld gebruikte dvza dienst wordt geconfigureerd.

EnableService

EnableServiceRequest{
  ServiceId: "dvza",
  Fetch: CallbackConfiguration{
    Protocol: "https://decozo.org/proto/fetch/fhir",
    Configuration: protobuf.Struct{
        "endpoint": "https://fhir-api.zorginformatiesysteem.nl"
    },
    Auth: ProtocolAuthConfiguration{
        Method:  "http://decozo.org/proto/auth/jwt",
        Configuration: protobuf.Struct{}
    }
  },
  // Lege configuratie, geen push protocol
  // gewenst of beschikbaar
  Push: CallbackConfiguration{}
}

• ServiceId
  De identifier van de dienst die wordt geconfigureerd, in dit geval dvza.
• Fetch
  Hierin wordt aangegeven hoe informatie kan worden opgehaald door de dienstverlener bij het zorginformatiesysteem. Meestal (zoals hier) betreft dit een endpoint (URL, domeinnaam/poort) van de bevraagbare interface.
• Push
  Hierin wordt aangegeven hoe informatie kan worden teruggestuurd door de dienstverlener naar het zorginformatiesysteem. In de regel als een URL van het endpoint. Dit KAN hetzelfde endpoint zijn als de Fetch interface. Het protocol bepaalt hoe de service op het endpoint aangeroepen moet worden om informatie naar het zorginformatiesysteem te sturen.

In de EnableServiceRequest hierboven zien we dat de dvza dienst wordt geactiveerd en er wordt aangegeven dat het zorginformatiesysteem een zoals in het https://decozo.org/proto/fetch/fhir protocol gedefinieerd de FHIR interface aanbiedt, welke het http://decozo.org/proto/auth/jwt authenticatie / autorisatie protocol ondersteunt.

Het configuratie onderdeel van EnableServiceRequest (de Fetch en Push velden) is een voorstel van het zorginformatiesysteem aan de dienstverlener waarin het aangeeft wat het wenst dat de 'state' is na het aanroepen van deze methode. Het is vervolgens aan de dienstverlener om hier mee akkoord te gaan en de configuratie eventueel aan te vullen. Een voorbeeld van aanvullen is bij de configuratie van de authenticatie / autorisatie methode. Het zorginformatiesysteem geeft in de EnableServiceRequest alleen aan dat het de http://decozo.org/proto/auth/jwt methode wenst te gebruiken maar is afhankelijk van de dienstverlener om informatie aan te vullen over welke sleutel er gebruikt gaat worden voor het ondertekenen van de JWT's. Het is immers de dienstverlener die dat gaat doen.

Hieronder een voorbeeld van wat de dienstverlener als antwoord kan geven op de bovenstaande aanroep.

EnableServiceResponse {
  ServiceId: "dvza",
  Enabled: true,
  Fetch: CallbackConfiguration{
    Protocol: "https://decozo.org/proto/fetch/fhir",
    Configuration: protobuf.Struct{
      "endpoint": "https://fhir-api.zorginformatiesysteem.nl"
    },
    Auth: ProtocolAuthConfiguration{
      Method:  "http://decozo.org/proto/auth/jwt",
      Configuration: protobuf.Struct{
        "signKey": "{\"kty\": \"EC\",\"use\": \"sig\",\"crv\": \"P-256\",\"kid\": \"8D2...\",\"x\": \"G6OnZzG...\",\"y\": \"Cdzg...\",\"alg\": \"ES256\"}"
      }
    }
  },
  // Lege configuratie, geen push protocol geconfigureerd
  Push: CallbackConfiguration{}
}

Je ziet in dit voorbeeld dat de dienstverlener het verzoek voor van het gebruik van het https://decozo.org/proto/fetch/fhir protocol en de http://decozo.org/proto/auth/jwt methode heeft geaccepteerd en daarnaast de configuratie voor de http://decozo.org/proto/auth/jwt methode heeft aangevuld met de sleutel waarmee de JWT's worden ondertekend.

info

Zoals al eerder in dit document aangegeven zijn de protocollen en authenticatie / autorisatie methodes niet binnen OKAPI gespecificeerd. De methodes zijn daarmee aan de zorginformatiesysteem / dienstverlener combinaties om in te vullen. De bedoeling is dat op termijn op https://docs.decozo.org/okapi een lijst gepubliceerd wordt met (open) protocollen die door alle leveranciers geïmplementeerd kunnen worden.

Om te controleren hoe diensten momenteel geconfigureerd zijn is er de hierboven beschreven ListServices methode.

De configuraties van services zullen niet verschillen met wat er wordt teruggegeven in de response van een EnableService call.

Als een dienst eenmaal geactiveerd en geconfigureerd is kan het zorginformatiesysteem patiënten aanmelden bij de dienst.

DisableService methode

Als het informatiesysteem om welke reden dan ook een bepaalde dienst wil uitzetten kan het gebruik maken van de DisableService methode. Als deze methode wordt aangeroepen moeten alle configuratie informatie en patient aanmeldingen aan voor deze service worden verwijderd aan de kant an de dienstverlener.

Hieronder een voorbeeld voor de situatie waarin het informatiesysteem de net geactiveerde dienst weer wil deactiveren. Zoals te zien wordt wordt alleen de id van de uit te schakelen dienst meegeven.

DisableServiceResponse {
  ServiceId: "dvza",
}

Zolang er geen error wordt teruggeven door de dienstverlener kan het informatiesysteem er van uit gaan dat alle informatie die het informatie systeem heeft aangeleverd betreft deze dienst is verwijderd door de dienstverlener. Het informatiessysteem kan dit ook nog controleren door de ListServices methode aan te roepen.

Aanmelden van patiënten

Een dienst implementeert altijd functionaliteit met betrekking op een set patiënten. Bijvoorbeeld het autoriseren van patiënten m.b.v. DigiD in het geval van een dvza (authorisatie server). Het is dan ook daarom dat het gestandariseerd aan- en afmelden van patiënten bij een dienst zodat een dienst weet op welke set patiënten het opereert onderdeel is van OKAPI.

Een dienst heeft pas toegang tot patiëntgegevens als deze patiënten aangemeld worden door het zorginformatiesysteem. D.w.z. de dienstverlener is dan pas op de hoogte van het bestaan van deze patiënt en heeft pas toegang tot de benodigde informatie om deze patiënt op te halen op het moment dat deze wordt aangemeld. Het is verplicht om aan de zorginformatiesysteem kant ook te controleren of dat de patiënt waarvan uiteindelijk informatie wordt uitgewisseld met een dienst ook daadwerkelijk is aangemeld bij deze dienst.

Patiënten worden aangemeld d.m.v. het aanroepen van de CreateOrUpdatePatientRegistrations methode.

CreateOrUpdatePatientRegistration methode

De CreateOrUpdatePatientRegistrations methode wordt gebruikt om een lijst van patiënten aan te melden bij een dienst en zo deze beschikbaar te maken voor de dient. Naast het aanmelden kan deze methode ook gebruikt worden om de metadata reeds aangemelde patient te wijzigen.

De lijst hoeft niet alle (bij de dienst aan te melden) patiënten te bevatten. Het kan ook een subset van de - of één - patiënt(en) betreffen.

Hieronder een voorbeeld waarbij een patiënt wordt aangemeld voor de hierboven geconfigureerde dvza dienst.

CreateOrUpdatePatientRegistrationsRequest{
  ServiceId: "dvza",
  Registrations: []PatientRegistrationCreateOrUpdateData{
    {
      Id: "00009999",
      Subject: PatientMeta{
        Identifier: [Identifier{
          Type: "http://fhir.nl/fhir/NamingSystem/bsn",
          Value: "00009999"
        }],
        Name: {
          Display: "Henk Slager",
          Given: []string{"Henk"},
          OwnName: "Slager",
          ...
        }
        ...
      }
      CallbackProtocolData: protobuf.Struct{
        "FHIRPatientID": "17fc696f-a204-4c4d-8ade-75441905faf1",
      },
      ServiceInput: protobuf.Struct{}, // Geen service input in dit geval
    }
  }
}

• ServiceId Identifier van de dienst waarvoor wordt aangemeld.
• PatientRegistration.Id Id voor deze patiënt registratie, uniek binnen deze dienst. In dit geval wordt de BSN van de patient gebruikt maar dit kan elke (binnen de dienst) unieke waarde zijn.
• PatientRegistration.Subject Patiëntgegevens: n.a.w., BSN etc zie specificatie voor details.
• PatientRegistration.CallbackProtocolData Protocol specifieke data, b.v. specifiek subpad of identifier. In dit geval wordt de id van patiënt meegegeven hoe deze bij de FHIR server bekend is.
• PatientRegistration.ServiceInput Dienst specifieke data, deze kan gebruikt worden om een dienst verdere instructies te geven. In dit voorbeeld wordt dit niet gebruikt.

De response op een CreateOrUpdatePatientRegistrations call bevat een lijst van resultaten. Elk lijstelement bevat het resultaat van het verwerken van een item en een optionele foutmelding. De resultaten zijn te koppelen aan de ingegeven registraties aan de hand van het `` veld. Hieronder een voorbeeld van een response op het voorbeeld request.

CreateOrUpdatePatientRegistrationsResponse{
  Results: []PatientRegistrationResult{
    {
      Id: "00009999",
      Error: ...
    },
  }
}

• Results.Id Id voor deze patiënt uniek binnen deze dienst. Deze wordt gevuld door de dienst als het een aanmelding betreft.
• Results.Error Eventuele opgetreden error bij de aanmelding / update
• Results.ServiceOutput Zie info blok hieronder

info

De serviceInput en serviceOutput bieden de mogelijkheid om dienst specifieke functionaliteit over OKAPI te implementeren. Een mogelijk voorbeeld van het gebruik van serviceOutput is, in het geval van een dienst die als patiëntenportaal functioneert, het teruggeven van een unieke registratie-URL voor de patient.

RemovePatientRegistration methode

De RemovePatientRegistrations wordt gebruikt om patiënten weer af te melden bij een dienst. Hieronder een voorbeeld hoe het informatiesysteem de in het vorige voorbeeld aangemelde patient weer af moet melden.

RemovePatientRegistrationRequest{
  ServiceId: "dvza",
  Registrations: []string{"00009999"},
}

• ServiceId Identifier van de dienst waarvoor wordt aangemeld.
• Registrations Lijst van id's van de af te melden registraties.

De dienstverlener geeft in de response aan of er eventuele fouten zijn opgetreden bij het afmelden, bijvoorbeeld in het geval dat de af te melden registratie niet bekend is bij de dienst.

ListPatientRegistrations methode

Door de ListPatientRegistrations methode aan te roepen kan het zorginformatiesysteem een lijst opvragen van de patiënten die momenteel voor een bepaalde dienst zijn aangemeld met als doel bijvoorbeeld controles uit te kunnen voeren en te synchroniseren.

De ListPatientRegistrations vereist maar een argument en dat is de identifier van de dienst waarvan de huidige registraties worden opgevraagd.

Hieronder een voorbeeld van een aanroep van de methode die de lijst opvraagt van patiënten die momenteel bij de 'dvza' dienst zijn aangemeld.

ListPatientRegistrationsRequest{
  ServiceId: "dvza",
  Query: nil,
}

info

De Query is in dit voorbeeld leeg maar kan gebruikt worden om een specifieke registratie of set van registraties op te halen. De filtering vindt plaats op basis van id en / of identifier van een bepaalde registratie. De velden in de query worden gecombineerd met een OR operator. D.w.z. als er meerdere waardes worden meegegeven worden alle registraties teruggegeven waarbij een van de meegegeven query waardes matcht.

Als reactie hierop wordt een lijst van aangemelde patiënten teruggegeven. Zoals je kunt zien is de patiënt de eerder in het voorbeeld is aangemeld (Henk Slager) terug te vinden in de lijst met aangemelde patiënten.

ListPatientRegistrationsResponse{
  PatientRegistrationData: []PatientRegistrationData{
    PatientRegistrationData{
      Id: "47fe1b4e-ff08-43a2-8bae-04ba8a72f4f9",
      Registered: true,
      CallbackProtocolData: protobuf.Struct{
        "FHIRPatientID": "17fc696f-a204-4c4d-8ade-75441905faf1",
      },
      Subject: PatientMeta{
        Identifier: [Identifier{
          Type: "http://fhir.nl/fhir/NamingSystem/bsn",
          Value: "00009999"
        }],
        Name: {
          Display: "Henk Slager",
          Given: []string{"Henk"},
          OwnName: "Slager",
          ...
        }
      }
      ...
    },
    ...
  }
}

Opvragen van events (logging)

Naast de drie kernonderdelen biedt OKAPI ook een interface voor het opvragen van Events. Een Event is een registratie van een bepaalde gebeurtenis binnen, of uitgevoerde handeling door, de dienstverlener.

Via events kan het zorginformatiesysteem op de hoogte blijven van het werk dat de dienstverlener heeft uitgevoerd. Een voorbeeld hiervan, in het voorbeeld van de dvza dienst, is het vastleggen van het feit dat een patiënt een PGO heeft gemachtigd om zijn of haar gegevens in te zien. Het zorginformatiesysteem kan hier nu dus van op de hoogte blijven, puur voor audit doeleinden, maar wellicht ook om deze informatie te tonen aan een arts in de UI van het zorginformatiesysteem. Welke events worden vastgelegd is dienst specifiek en is daarom niet vastgelegd binnen OKAPI.

Event {
    Timestamp: 1665574438242,
    Type: "PGOAuthorized",
    ServiceId: "dvza",
    PatientId: "47fe1b4e-ff08-43a2-8bae-04ba8a72f4f9",
    Payload: protobuf.Struct{
      "PGO": "https://mijnpgo.nl",
      ...
    }
}

• Timestamp Tijdstip waarop het event heeft plaatsgevonden als Unix timestamp in milliseconden.
• Type Type van het event. Er hangen geen verplichtingen aan het type van een event en kan elke willekeurige geldige reeks van karakters zijn. Gewenst is wel dat uit het type opgemaakt kan worden wat het Event representeert.
• ServiceId Id van de dienst die het event heeft geregistreerd.
• PatientId Id van de patiënt waarop dit event betrekking heeft (als van toepassing, bijvoorbeeld niet in het geval van een XIS koppel event).
• Payload Event type afhankelijke data.

Voor deze werkwijze zijn twee methodes ingericht, een voor het gepagineerd ophalen van Events (GetEvents) en een om Events (GetEventsStream) te streamen. Deze laatste methode kan gebuikt worden om realtime op de hoogte gehouden te worden van gebeurtenissen.

Ongeacht de methode die gebruikt wordt wordt bij het opvragen een Query meegestuurd om de terug gegevens events te kunnen filteren.

// Definitie in protobuf
message Query {
    uint64 start = 1;
    uint64 end = 2;
    string type = 3;
    string serviceId = 4;
    string patientId = 5;
}

• start Als dit veld is ingevuld wordt er een filter toegepast en worden allen events teruggegeven die hebben plaatgevonden na of op de opgegeven waarde (Event.timestamp >= Query.start). De waarde die kan worden ingegeven is een Unix timestamp in milliseconden.
• end Als dit veld is ingevuld wordt er een filter toegepast en worden allen events teruggegeven die hebben plaatgevonden voor de opgegeven waarde (Event.timestamp < Query.end). De waarde die kan worden ingegeven is een Unix timestamp in milliseconden.
• type Als dit veld is ingevuld worden alleen events terug gegeven van het aangegeven type (Event.type).
• serviceId Als dit veld is ingevuld worden alleen events terug gegeven die zijn aangemaakt door deze dienst.
• patientId Als dit veld is ingevuld worden alleen events terug gegeven die zijn gerelateerd aan deze patiënt.

De Query bevat vijf velden op te filteren op specifieke Events. Geen van de velden is verplicht, een volledig lege Query betekent dat alle Events worden meegenomen zonder daar een filter op toe te passen.

Kijk in de specificatie voor details over de twee methodes om Events op te halen.

---

1. Zo kan (ook) gecontroleerd worden of de organisatienaam die teruggeven wordt met de GetMetadata methode overeenkomt met de organisatie in het TLS server certificaat.↩