Interfaces ACT/VWI Server

ACT/VWI Interface

Algemeen

Base endpoint en FHIR-versions

De waarde van de base-URL van de FHIR endpoints die de ACT/VWI Server biedt t.b.v. de ACT/VWI Interface ( [base] dus ), dient voor alle FHIR-interacties gelijk te zijn aan "https://<FQDN>[/<path-extension>]/fhir/<fhir-version>". De waarde van <fhir-version> is dan bijvoorbeeld "R4" of "R5".

T.b.v. de ACT/VWI Interface worden de volgende FHIR-versions ondersteund:

• R4

HTTP-request headers

AOF.AVS-I.ACI.200.v1

Bij iedere interactie, worden in ieder HTTP-request, de volgende HTTP headers meegezonden:

Authorization: Bearer <AORTA access_token>

Een AORTA access_token is altijd een JSON Web Token (JWT).

Een JWT bestaat uit een aantal base64 strings, die aan elkaar zijn gekoppeld met punten. Indien een token een SAML Assertion zou zijn, dan dient het altijd base64url te worden gecodeerd conform RFC 4648. Omdat een base64url geëncodeerde SAMLv2 Assertion geen punten kan bevatten, is de ontvanger altijd in staat om het type token bepalen.

In het token, dat wordt ontvangen in een Authorization header, is informatie opgenomen over welke type inhoudelijk token het betreft en welke versie, dus bijvoorbeeld dat het gaat om een AORTA access_token.

Het BSN van de patient waarop een entry betrekking heeft wordt bij alle interacties meegegeven in het AORTA access_token. Alle interacties hebben dus betrekking op een en dezelfde patiënt. Dit geldt ook voor interacties die worden verstuurd in een batch of transaction Bundle.

AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>

Het initialRequestID attribuut bevat het ID van het allereerste request in de hele keten en dient te worden opgenomen in de logbestanden van alle partijen in de keten, zodat bij foutopsporing de verschillende logbestanden aan elkaar kunnen worden gerelateerd.

Het requestID is voor iedere request message uniek. In requests wordt deze gegenereerd door de client. Ook het requestID dient te worden opgenomen in de verschillende logbestanden, zodat altijd duidelijk is op welk bericht een log entry van toepassing is.

AORTA-Version: contentVersion=<versienummer>; acceptVersion=<versienummer>

Wanneer een Resource Server een FHIR interactie ontvangt, dan kan het a.d.h.v. de syntax van het ontvangen request afleiden om welke interactie het gaat, bijvoorbeeld "een FHIR-search naar Obervations", of "een FHIR-read van een Binary". Daarnaast is iedere interactie voorzien van een versienummer. Voor versienummering wordt gebruik gemaakt van semantic versioning.

De acceptVersion geeft aan conform welke versie(s) de interactie mag worden verwerkt en beantwoord. Het versienummer in de acceptVersion wordt gespecificeerd conform semver, dus bijvoorbeeld "2.x" of "~1.2.3 || ^2.1.0". In het algemeen geldt dat een resource server een interactie dient te verwerken conform de hoogst aangegeven acceptVersion die het zelf op dat moment kan toepassen.

De contentVersion geeft aan welke versie van de interactie daadwerkelijk is gehanteerd. In de contentVersion dient het versienummer de exacte versie van de interactie te bevatten die is gehanteerd, dus zonder wildcards of ranges, bijvoorbeeld “1”, of "2.2". De versie van een FHIR-interactie is opgenomen in het interactie-id.

HTTP-response headers

AOF.AVS-I.ACI.300.v1

Bij iedere interactie, worden in iedere HTTP-response, de volgende HTTP headers meegezonden:

AORTA-Version: contentVersion=<versienummer>

De contentVersion geeft aan welke versie van de interactie daadwerkelijk is gehanteerd. In de contentVersion dient het versienummer de exacte versie van de interactie te bevatten die is gehanteerd, dus zonder wildcards of ranges, bijvoorbeeld “1”, of "2.2". De versie van een FHIR-interactie is opgenomen in het interactie-id.

Generieke parameters

AOF.AVS-I.ACI.400.v1

Het gewenste formaat (JSON of XML) kan op de gebruikelijke manier via de Accept Header opgegeven worden, maar kunnen ook via de FHIR _format parameter doorgegeven worden. 

Ondersteunde waarden voor de _format parameter zijn voor alle interacties, waar van toepassing:

• de mogelijke opties die duiden op het FHIR JSON formaat of op het FHIR XML formaat.

Indien beide (Accept header en _format parameter) in een request voorkomen, geldt de waarde van de _format parameter. Indien geen enkele voorkomt, dan geldt het formaat van het Content-Type.

Search parameters

In het algemeen ziet een request met search parameters (conditional-update, conditional-delete of search) er als volgt uit:

[HTTP verb] [base url]/List?source:Device.identifier=http://fhir.nl/fhir/NamingSystem/aorta-app-id|[app id]&code=[codesystem url]|[value]{&_format=[mime-type]}

De vereiste vulling is hieronder beschreven:

Voorbeeld voor gegevenssoort 'Huisartswaarneemgegevens' en application ID 12345

[PUT|DELETE] [base url]/List?source:Device.identifier=http://fhir.nl/fhir/NamingSystem/aorta-app-id|12345&code=urn:oid:2.16.840.1.113883.2.4.15.4|460320

Voorbeeld voor bouwsteentype 'Contactverslag' en application Id 12345

[PUT|DELETE] [base url]/List?source:Device.identifier=http://fhir.nl/fhir/NamingSystem/aorta-app-id|12345&code=urn:oid:2.16.840.1.113883.2.4.3.111.15.3|CONTACTVERSLAG

Voorbeeld met zoeken op meerdere gegevenssoorten en bouwsteentypes

Voor het aanmaken, bijwerken en verwijderen van een entry geldt dat de actie alleen uitgevoerd wordt als de resultaat set tot 1 instantie leidt. Zoekacties kunnen meerdere resultaten opleveren. Hieronder staan voorbeelden waarbij gezocht wordt naar meerdere application-id's en meerdere gegevenssoorten en/of bouwsteentypes.

GET [base url]/List?source:Device.identifier=http://fhir.nl/fhir/NamingSystem/aorta-app-id|12345&code=urn:oid:2.16.840.1.113883.2.4.3.111.15.3|CONTACTVERSLAG,urn:oid:2.16.840.1.113883.2.4.15.4|460320

FHIR-profielen

Informatie over de gehanteerde FHIR-profielen op deze interface:

AOF.FP.VWI.100.v1

Voorbeelden:

• https://simplifier.net/vzvz/~resources?category=Example&exampletype=List&sortBy=RankScore_desc

• https://simplifier.net/vzvz/aorta-datareference-bundle-example

Interacties

Aanmaken of bijwerken entry

Deze interactie is gebaseerd op de FHIR conditional update interactie. Hierdoor is het niet nodig om een administratie van het resource ID bij te houden. De entry wordt geïdentificeerd m.b.v. zoekparameters applicatie-id en gegevenssoort/bouwsteentype. Als de entry nog niet bestaat in het Actualisatieregister, dan wordt het aangemaakt, anders wordt het bijgewerkt. Voor de specifieke fouten zie hieronder.

Een entry kan op de volgende wijze worden aangemaakt of bijgewerkt:

PUT [broker-base]/List?[search-parameters]
Content-Type: application/fhir+json

{
    "resourceType": "List",
	......
}

PUT [broker-base]/List?[search-parameters]
Content-Type: application/fhir+xml

<List xmlns="http://hl7.org/fhir">
....
</List>

Zie rejecting updates voor aanvullende foutsituaties.

AOF.RB-I.ACI.500.v1

Deze functionaliteit wordt pas in een latere versie dan 0.8 ondersteund.

Meerdere interactie van dit type kunnen, wanneer de entries betrekking hebben op eenzelfde patiënt, op de volgende wijze worden gebundeld in een Bundle van het type "batch":

POST [broker-base]
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "type": "batch",
  "entry": [
    {
      "resource": {
        "resourceType": "List",
...
      },
      "request": {
        "method": "PUT",
        "url": "/List?[search-parameters]"
      }
    },
    {
      "resource": {
        "resourceType": "List",
...
      },
      "request": {
        "method": "PUT",
        "url": "/List?[search-parameters]"
      }
    }
  ]
}

Verwijderen entry via RESTful API

Deze interactie is gebaseerd op de FHIR conditional delete interactie. Met de conditional delete is het niet noodzakelijk om een administratie van de Resource IDs aan te leggen in het bronsysteem.

Een entry kan op de volgende wijze worden verwijderd:

DELETE [broker-base]/List?[search params]

De search parameters bevatten minimaal het application ID van het bronsysteem. Het BSN van de patiënt in kwestie wordt altijd meegezonden in het AORTA transactietoken. 

Zie hiervoor de sectie Search parameters.

(zie: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE )

NB. wanneer en entry op deze wijze wordt verwijderd, dan blijft een eventueel abonnement bij Mitz gewoon bestaan. Indien verwijdering van een Mitz abonnement ook is gewenst, dan dient de FHIR operation te worden gebruikt.

AOF.RB-I.ACI.700.v1

Deze functionaliteit wordt pas in een latere versie dan 0.8 ondersteund.

Meerdere interactie van dit type kunnen, wanneer de entries betrekking hebben op eenzelfde patiënt, op de volgende wijze worden gebundeld in een Bundle van het type "batch":

POST [broker-base]
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "type": "batch",
  "entry": [
    {
      "request": {
        "method": "DELETE",
        "url": "/List?[search params]"
      }
    },
    {
      "request": {
        "method": "DELETE",
        "url": "/List?[search params]"
      }
    }
  ]
}

Verwijderen entries via een FHIR operation

Deze custom operation wordt als volgt aangeroepen:

POST [broker-base]/$delete-dossier

Zie ook FHIR Operations voor de wijze waarop wordt moet worden omgegaan met de parameters. Een HTTP POST is vereist, omdat de operation een wijziging tot stand brengt op de resource broker.

2023-05-02 De unsubscribe parameter wordt nog niet gebruikt

Voorbeeld

POST [broker-base]/$delete-dossier

<Parameters xmlns=http://hl7.org/fhir>
  <parameter>
    <name value="app-id"/>
    <valueString value="[application ID]"/>
  </parameter>
  <parameter>
    <name value="unsubscribe"/>
    <valueBoolean value="[true|false]"/>
  </parameter>
</Parameters>

Zoeken naar entries

Deze interactie is gebaseerd op de FHIR-search interactie. Er kan op de volgende wijze worden gezocht naar entries betreffende een specifieke patiënt:

GET [broker-base]/List{?[parameters]{&_format=[mime-type]}}

Zie de sectie Search parameters voor meer uitleg over de parameters.

De getEntries interactie maakt het mogelijk om:

• Verwijsindex entries op te vragen op basis van een BSN en een set van bouwsteentypen of gegevenssoorten. De response bevat een set van appID’s en per appID een set van bouwsteentypen of gegevenssoorten waarover de betreffende GBZ-applicatie, voor de gegeven patiënt, beschikt.