Notify

/in /door

Ysis kan geïnformeerd worden van wijzigingen. In reactie haalt Ysis dan de gegevens op bij het Bronsysteem.

Inleiding

De meeste integraties tussen Ysis en andere zorgsystemen werken momenteel met een Notify/Fetch pattern. Het idee is dat het bron systeem een signaal geeft naar het afnemende systeem. Het afnemende systeem haalt deze gegevens vervolgens op.
Dit heeft een aantal voordelen ten opzichte van ‘push’ methoden:

  • Het bronsysteem hoeft zich niet te verdiepen in de businesslogica, validaties en mapping van het afnemende systeem. Het afnemende systeem heeft zelf de controle over het valideren en verwerken van de gegevens.
  • De meeste zorgsystemen hebben al een API om gegevens op te halen, deze kan (her)bruikt worden, zodat er minder custom software nodig is voor elke individuele integratie.
  • Door het ‘notify’ principe is schaalbaarheid eenvoudig. Ysis bijvoorbeeld plaatst alle binnenkomende notifies op een queue, die continue wordt verwerkt: dit maakt het eenvoudig om piekbelastingen op te vangen zonder dat de API vertraagd.
  • Het is ook eenvoudig om – als er bij het afhandelen van de notify fouten ontstaan –  operaties te herhalen en datacorrectie te doen zonder dat inzet van de partner nodig is.

Opmerkingen:

  • De meeste Notificatie typen zijn 1:1 (bijvoorbeeld administratieve gegevens: er is per patiënt maar 1 set). Het is dan voldoende om aan Ysis alleen het BSN door te geven: Ysis haalt de volledige set gegevens van de patient op en overschrijft deze in Ysis. Een identifier, mutatietype, en timestamp zijn daarom niet vereist. Uitzonderingen zijn rapportages, metingen en berichten: hier zijn de aantallen te groot en worden we graag geïnformeerd over welk rapport is gewijzigd, en of het een nieuw rapport, een gewijzigd rapport of een verwijdering betreft.
  • De identifier is een vrije waarde die in Ysis als ‘external identifier’ bij de gegevens wordt opgeslagen (voor de 1:n koppelingen rapportages, metingen en berichten). Het is wel belangrijk dat de waarde uniek is binnen de patiënt, en dat latere notificaties over mutaties op dezelfde gegevens ook weer dezelfde identifier bevat.
  • timestamp is optioneel, maar wordt wel geadviseerd: er kan een verschil zijn tussen het moment waarop de waarde is ingevoerd, en het moment waarop deze bij Ysis wordt aangeleverd. Als de timestamp niet wordt meegegeven wordt het moment van de aanroep van deze methode gebruikt in Ysis.

De volgende notificatietypes zijn beschikbaar. Let op dat deze alleen worden ondersteund als ze in gezamenlijk overleg met Gerimedica zijn geïmplementeerd voor uw systeem:

  • ADMINISTRATIVE Informeer Ysis dat de administratieve gegeven van de patient zijn gewijzigd (persoonsgegevens, adres, contactpersonen, verzekering of huisarts).  Verplichte parameters: BSN en Mutatietype.
  • CHECKUP Informeer Ysis dat er een meting voor de patiënt is ingevoerd (temperatuur, pols, glucose, gewicht etc.).  Verplichte parameters: BSN, ID en Mutatietype.
  • REPORT Informeer Ysis dat er een rapport/verslag voor de patiënt is ingevoerd.  Verplichte parameters: BSN, ID en Mutatietype.
  • MESSAGE Informeer Ysis dat er een bericht voor de patiënt is ingevoerd.  Verplichte parameters: BSN, ID en Mutatietype.
  • INTOLERANCE Informeer Ysis dat er een intolerantie (medicatie allergie) voor de patiënt is ingevoerd.  Verplichte parameters: BSN.
  • OVZ Informeer Ysis dat er 1 of meer Onvrijwillige zorg maatregelen (OVZ) van de wet WZD zijn gewijzigd. Verplichte parameters: BSN.  
  • CAREPLAN  Informeer Ysis dat het zorgplan voor de patiënt is gewijzigd.  Verplichte parameters: BSN.
  • CAREPATH  Informeer Ysis dat er een wijziging is in de zorgprogramma’s / logistics planning templates.  Verplichte parameters: geen.

Opmerking: de OVZ optie komt beschikbaar in februari 2021. Hij is al wel beschikbaar op de acceptatie1 testomgeving

Zie de WSDL voor de exacte specificatie van de input en output.
WSDL: https://acceptatie1-webservice.ysis.nl/20180505/org/notify?wsdl
Endpoints:
Acceptatie1: https://acceptatie1-webservice.ysis.nl/20180505/org/notify
Acceptatie2: https://acceptatie2-webservice.ysis.nl/20180505/org/notify
Productie:  https://webservice.ysis.nl/20180505/org/notify

Mogelijke foutcodes:
Y001 – BSN unknown  (BSN niet bekend in deze organisatie)
Y004 – BSN not valid (BSN voldoet niet aan de 11-proof nummer validatie)
Y011 – BSN, ID and MutationType mandatory for this NotificationType
Y012 – BSN mandatory for this NotificationType

Voorbeeld Requests:
Voorbeeld voor Zorgplan
“Zorgplan gewijzigd voor Patient 123456782”

<soapenv:Body>
   <con:notifyRequest>
      <con:bsn>123456782</med:bsn>
      <con:notificationType>CAREPLAN</con:notificationType>
   </med:notifyRequest>
</soapenv:Body>

Voorbeeld voor rapportages.
“Rapportage met ID 12345 voor patiënt 123456782 is verwijderd”

<soapenv:Body>
   <con:notifyRequest>
      <con:bsn>123456782</med:bsn>
      <con:notificationType>REPORT</con:notificationType>
      <con:identifier>12345</con:identifier>
      <con:mutationType>DELETE</con:mutationType>
      <con:timestamp>2016-12-15T16:20:31.000+01:00</con:timestamp>
   </con:notifyRequest>
</soapenv:Body>

Voorbeeld Response
“notificatie ontvangen (resulteert daarna in Ysis tot een actie om de gegevens op te halen)”

<SOAP-ENV:Body>
   <record:notifyResponse xmlns:admin=etc.>
      <record:status>OK</record:status>
      <record:log>Notification Received.</record:log>
   </med:notifyResponse>
</SOAP-ENV:Body>

“deze patiënt is niet bekend in Ysis: er wordt vanuit Ysis verder geen actie ondernomen om de gegevens op te halen.”

<SOAP-ENV:Body>
   <record:notifyResponse xmlns:admin=etc.>
      <ns17:status>FAILED</ns17:status>
      <ns17:errorCode>Y001</ns17:errorCode>
      <ns17:errorText>BSN unknown</ns17:errorText>
   </med:notifyResponse>
</SOAP-ENV:Body>

“Geen valide BSN: (voldoet niet aan de BSN 11-proof validatie).”

<SOAP-ENV:Body>
   <record:notifyResponse xmlns:admin=etc.>
      <ns17:status>FAILED</ns17:status>
      <ns17:errorCode>Y004</ns17:errorCode>
      <ns17:errorText>Not a valid BSN</ns17:errorText>
   </med:notifyResponse>
</SOAP-ENV:Body>

“Missende parameters bij het sturen van een ADMINISTRATIVE notificationtype.”

<SOAP-ENV:Body>
   <record:notifyResponse xmlns:admin=etc.>
      <ns17:status>FAILED</ns17:status>
      <ns17:errorCode>Y022</ns17:errorCode>
      <ns17:errorText>BSN and MutationType mandatory for this NotificationType</ns17:errorText>
   </med:notifyResponse>
</SOAP-ENV:Body>