OSO:2018/Algemene Eisen

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken

Algemene eisen en randvoorwaarden

De verzendende school is verantwoordelijk voor het afwegen welke gegevens er al dan niet verstrekt moeten worden aan de aanvragende partij. Het bronsysteem dient deze keuze te ondersteunen. OSO faciliteert alleen het beveiligd transport van deze gegevens.

Bewuste gebruikershandeling

(Eind)gebruikersacties binnen het uitwisselingsproces ('klaarzetten van een dossier', 'opvragen van een dossier', 'ouder inzage') moeten een ‘bewuste gebruikershandeling’ zijn; gestart door de eindgebruiker (en niet automatisch afgehandeld door een systeem). Een uitzondering hierop is het automatisch ophalen van een Dossier bij de PaO uitwisseling na ontvangst van een Notificatie met Koppelsleutel.

Inzage Dossiers

Voorafgaand aan verzending dient (voor een aantal typen overstap) het Dossier in te worden gezien door de ouders/verzorgenden. De eisen en randvoorwaarden die hiervoor gelden worden hier beschreven.

Bewaartermijn Dossiers

Het overstapdossier doet specifiek dienst voor de overstap van een leerling van de huidige naar een nieuwe school. Nadat de overstap is gerealiseerd, en de gegevens van de leerling in het LAS van de nieuwe school zijn ingevoerd en verwerkt, is advies om het overstapdossier (het complete xml bericht inclusief bijlagen) nog twee jaar te bewaren. Daarna dient het dossier te worden vernietigd.

Bewaartermijn Dossier verzoeken tbv Notficatie

In OSO'18 wordt deze termijn ingesteld tot het einde van het OSO'18 'seizoen' (juli 2018). De verzoeken tot levering hoeven niet meegenomen te worden naar de OSO'19 administratie (maar vervallen na juli 2018).

Bewaartermijn KoppelSleutel

De bewaartermijn van KoppelSleutels ingesteld op 'geldig gedurende de looptijd van een regeling'. Omdat de status van een regeling niet bekend is binnen de OSO contect én omdat een koppelsleutel een zeer precieze en kleine scope kent, mogen koppelsleutels geldig blijven. Koppelsleutels moeten daarom bewaard en meegenomen naar het nieuwe OSO seizoen(!).

Overige technische randvoorwaarden

Foutmeldingen

In OSO'18 worden standaard foutmeldingen voor Eindgebruikers aanbevolen. Als een fout of uitzondering optreedt dan moet een systeem zowel:

  • de code uit de 'Melding' kolom
  • én de foutmelding uit de kolom 'Melding aan Eindgebruiker'

in de tabellen bij de Use Case beschrijvingen tonen aan de Eindgebruiker.
De lijst met standaard foutmeldingen geldt als 'referentie implementatie'. In plaats van de standaard foutmelding mag een Leverancier kiezen eigen foutmeldingen toe te passen (ook in dat geval moet de code's uit de Resultaat kolom getoond worden.)

De complete en bijgewerkte lijst met foutmeldingen is hier te vinden. Deze lijst is de toe te passen lijst(!). De meldingen zijn ook toegevoegd in de use case beschrijvingen onder de kop 'Uitzonderingen en meldingen', maar de meldingen in de (xls-)lijst zijn leidend(!).

Adressering

In de adressering van OSO berichten worden altijd vier velden gebruikt (die afhankelijk van het bericht en zender gevuld worden):

  • bronBRIN
  • bronAPindex
  • doelBRIN
  • doelAPindex

Hierbij worden twee uitgangspunten toegepast:

  1. Doel en Bron worden hier absoluut gebruikt, volgens de rol die het desbetreffende systeem uitvoert in de transactie
  2. De velden worden ingevuld wanneer dit mogelijk is (en zijn anders leeg). (Bijvoorbeeld: In het geval van een overdrachtRequest kunnen alleen de doelBRIn, doelAPindex en bronBRIN ingevuld zijn, omdat het doelsysteem dat dit request verstuurd nog geen idee heeft welke aanleverpunten afgelopen moeten worden).

Logging

Een op OSO aangesloten systeem moet gegevens over verzonden en ontvangen berichten en opgetreden fouten opslaan en beschikbaar kunnen maken voor twee doelen:

  • het kunnen achterhalen welk dossier wanneer tussen welke systemen is uitgewisseld en welk gebruikersaccount daar opdracht toe gaf (juridische eis)
  • zodat ze in geval van calamiteiten door de leverancier op te zoeken zijn.


De gelogde informatie moet redelijkerwijs voldoende zijn om technische problemen op te lossen en in speciale gevallen het verloop van de interacties te reconstrueren (operationele toepassing)

Richtlijnen Logging

Om aan beide eisen te kunnen voldoen gelden de volgende richtlijnen voor de logging binnen doel- en bron- systemen:

  • De BRIN, uit het PKI certificaat van het systeem waarmee gecommuniceerd wordt, wordt gelogd
  • De SessieID en gebruikersaccount (binnen het systeem) worden gelogd
  • De informatie in een logregel voor de gebruiker is voldoende zelfbeschrijvend om zonder contextinformatie uit het bronsysteem de actie te kunnen herleiden tot de verantwoordelijke (rechts)persoon.
  • Log regels bevatten altijd het geldige sessie-id (wanneer dit is toegekend).
  • In de logregels moet of de ZoekSleutel of de Koppelsleutel (indien van toepassing) worden vastgelegd.
  • Een systeem registreert logregels voorzien van datum en tijd, met een nauwkeurigheid van ten minste 1 seconde.
  • Een systeem garandeert een maximale afwijking van de UTC + 01:00 tijd (de tijdzone waarin Nederland valt) van 5 seconden.
  • Logregels voor de gebruiker kunnen na creatie niet worden aangepast of verwijderd.
  • Logregels voor de gebruiker worden duurzaam bewaard en beschermd tegen verlies en verandering tot 2 jaar na het moment van overdracht van het dossier.

Timing

  • Een OSO sessie heeft, indien niet eerder afgemeld, een duur van maximaal 10 minuten.
  • Initiator van een interactie ontvangt binnen 30 seconden na het versturen van een request een response van het bevraagde systeem. Indien er binnen deze tijd geen response wordt ontvangen, moet de initiator een time-out (fout) afhandelen (en melden aan eindgebruiker en TC).
    • Een systeem dat een interactie start, wacht gedurende minimaal de gespecificeerde responstijd op antwoord.
    • Een systeem dat een interactie moet beantwoorden, doet dit binnen de gespecificeerde maximale responstijd.

Omvang berichten

Door de invoering van Passend Onderwijs en andere ontwikkelingen is er een behoefte om meer informatie in dossiers en met name bijlagen op te slaan. Anderzijds is het loslaten van een bovengrens aan de dossiergrootte onverstandig uit praktische overwegingen. De volgende bestandsgrootte's zijn daarom afgesproken:

  • Bijlage: maximaal 10MB
  • Compleet dossier: maximaal 30MB.

'Zippen' van bijlagen

Documenten die als bijlage aan een dossier worden toegevoegd, worden als een in Base64 gecodeerd zip bestand opgenomen in het dossier. In OSO wordt hiervoor de MIME Base64 content-transfer-encoding standaard, zoals beschreven in RFC 2045, toegepast. Deze variant maakt gebruik van dezelfde tekenset als ‘Standaard’ Base64 (zoals beschreven in RFC 4648, hoofdstuk 4 variant 1), maar kapt regels af op 76 tekens of minder, gescheiden door een CRLF(“\r\n”). Daarnaast worden bij het decoderen alle ‘vreemde’ tekens genegeerd. NB: Deze codering wijkt af van die toegepast voor de zoeksleutel(!).