1 Doelstelling van dit document

Voor het invoeren en onderhouden van informatie in RIO door de instellingen wordt een geautomatiseerde koppeling ingevoerd. De koppeling is gebaseerd op de Open Onderwijs API (OOAPI)-standaard, en voor het transport wordt gebruik gemaakt van SURFeduhub. Vanuit het SIS kan op deze wijze informatie over de opleidingen in RIO worden aangebracht en bijgehouden.

Op het moment dat een instelling in productie wil met de koppeling staat er al data in RIO. Enerzijds de onderwijserkenningen vanuit het CROHO en anderzijds is het mogelijk dat een instelling op enigerlei wijze, handmatig via de SelfService portal van RIO of via EDU-DEX, gegevens met betrekking tot de onderwijsinrichting heeft opgevoerd. De aanwezige data in RIO moet, voordat de geautomatiseerde koppeling van start gaat, gesynchroniseerd worden met de opleidingsinformatie in het SIS om daarmee duplicaten in RIO te voorkomen en ervoor te zorgen dat nieuw opgevoerde data aan de juiste entiteiten in RIO gekoppeld kan worden.

2 Verantwoordelijkheid synchronisatie

De instelling die met een OOAPI koppeling informatie vanuit het SIS naar RIO wil koppelen is verantwoordelijk voor het eerst op orde brengen, dus synchroniseren van de SIS en RIO informatie.

Als een instelling géén synchronisatie uitvoert voorafgaande aan de eerste OOAPI koppeling, dan ontstaan mogelijk dubbele gegevens in RIO. Dit is onwenselijk en vereist acties van de instelling om dit in RIO weer te “repareren”.

Instellingen die handmatig RIO vullen en beheren en géén OOAPI koppeling gebruiken hoeven ook niet te synchroniseren.

Dit document kan als handreiking worden gezien naar de instellingen om, gebruikmakend van de aanwezige faciliteiten, de synchronisatie uit te voeren.

3 Te synchroniseren RIO gegevens

3.1 Opleidingseenheid

Alle geaccrediteerde opleidingen worden dagelijks vanuit het CROHO-register gepushed naar het deel onderwijserkenningen in RIO.

De instelling kan een aantal velden van de opleidingseenheid bewerken via de OOAPI koppeling. Opdat de wijziging in een opleiding in het SIS op de juiste opleidingseenheid in RIO wordt aangebracht is het noodzakelijk dat beide entiteiten elkaars unieke code kennen.

Deze situatie geldt voor álle instellingen in het HO-veld.

3.2 HoOpleiding, HoOpleidingsonderdeel, AangebodenHoOpleiding, AangebodenHoOpleidingsonderdeel & Cohorten

Deze entiteiten worden in principe in het SIS aangemaakt en onderhouden en via de OOAPI koppeling in RIO ingevoerd en onderhouden. Bij het opvoeren van deze entiteiten in RIO wordt het vanuit SIS opgegeven unieke ID opgeslagen in RIO waardoor er een match blijft tussen het SIS en RIO t.b.v. latere wijzigingen.

Er zijn instellingen die al een deel van hun gegevens in RIO hebben ingevoerd via bijvoorbeeld de SelfService portal van RIO of via EDU-DEX t.b.v. STAP. De reeds in RIO ingevoerde gegevens die nadien via OOAPI onderhouden zullen worden, moeten vóór de eerste productie aansluiting middels de OOAPI, gesynchroniseerd worden tussen het SIS en RIO.

Gegevens die via EDU-DEX of handmatig in RIO zijn opgevoerd en waarvan het beheer ook via EDU-DEX of handmatig blijft plaats vinden (dus niet via de OOAPI) zijn geen onderdeel van deze synchronisatie. Hierover later meer in dit document.

3.3 Waarop te synchroniseren

Elke entiteit in de koppeling krijgt vanuit het SIS een unieke sleutel die vervolgens in RIO wordt vastgelegd op het moment dat een entiteit wordt aangemaakt. Het betreft de volgende items:

• OpleidingsEenheid: eigenOpleidingsEenheidSleutel
• AangebodenOpleiding: eigenAangebodenOpleidingSleutel
• AangebodenHoOpleidingsonderdeel: eigen AangebodenOpleidingSleutel
• Cohorten: cohortCode

De synchronisatie moet er voor zorgen dat de unieke sleutel uit het SIS in RIO bij het overeenkomstige gegeven wordt geplaatst. Daarmee zal de OOAPI koppeling precies de juiste RIO gegevens weten te vinden wanneer daarvoor in de koppeling gegevens worden gestuurd.

4 Werkwijze synchronisatie

Op hoofdlijnen voert de instelling de volgende acties uit:

• vergaren gegevens uit RIO
• vergaren gegevens uit het SIS
• match de gegevens uit SIS en RIO
• breng de unieke sleutel uit het SIS aan in RIO bij het overeenkomstige item

De uitwerking in details is afhankelijk van de wijze waarop een instelling de OOAPI koppeling heeft gerealiseerd. Enerzijds kan de koppeling gerealiseerd zijn via het SIS van een leverancier en anderzijds kan het zijn dat een instelling een eigen OOAPI-endpoint heeft gerealiseerd. Voor deze situaties gelden andere instructies, met uitzondering van het vergaren van de RIO informatie.

4.1 Vergaren RIO informatie

Er bestaat geen RIO rapportage om alle van een instelling in RIO aanwezige gegevens voor de synchronisatie op één overzicht te krijgen. Daarom is een Excel tool ontwikkeld die op basis van de DUO Open Onderwijsdata het gewenste overzicht maakt.

De Excel tool is naast deze handleiding parallel beschikbaar gesteld: Downloaden sheet RIO aanbod

• Op het tabblad “Introductie” staat hoe de tool werkt;
• Op het tabblad “Instellingen” moeten “Onderwijsbestuur ID” en “Locatie bronbestanden” worden ingevuld voor de eigen instelling. Hier staan ook de links naar de te downloaden bestanden die op de “Locatie bronbestanden” moeten worden geplaatst;
• Na uitvoering van de tool bevatten de tabbladen “HO” en “NFO” de gegevens van je eigen instelling. Daarop staan alle HO en NFO opleidingen met daarbij de aangeboden opleidingen en de cohorten;
• Er is een afzonderlijke Leeswijzer waarin beschreven staat hoe de gegevens van alle bronbestanden zijn verwerkt tot het overzicht. Deze beschrijving is redelijk technisch van aard. Mogelijk moet aanvullende informatie worden gezocht in de beschrijving van het RIO informatiemodel;

Selecteer uit het resultaat van de Excel tool alle opleidingseenheden en aangeboden opleidingen die vanaf de start van de OOAPI koppeling onderhouden moeten worden via de OOAPI koppeling. Deze gegevens moeten gesynchroniseerd worden.

Let op:

1. In het resultaat van de Excel tool kunnen ook gegevens in staan die door de instelling met EDU-DEX zijn aangeboden. Bepaal of die gegevens met EDU-DEX beheerd moeten blijven óf dat ze vanaf nu met de OOAPI koppeling beheerd zullen worden. Voorkom dat een gegeven door beide koppelingen wordt beheerd. Dubbel beheer veroorzaakt ook dubbele gegevens in RIO en dat moet voorkomen worden. Gegevens die in de toekomst met EDU-DEX beheerd moeten blijven, moeten dus NIET gesynchroniseerd worden. Moet het gegeven vanaf nu met de OOAPI koppeling worden beheerd, dan moet het wél gesynchroniseerd worden, maar LET OP: dan moet dat gegeven UIT de EDU-DEX koppeling worden gehaald.
   1. EDU-DEX aangeboden opleidingen kun je herkennen door:

AangebodenOpleiding.Code (dus NIET eigen sleutel) = '[ED0C]{4}[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}' , m.a.w. een UUID die start met “ED0C” en met uitsluitend hoofdletters

1. EDU-DEX opleidingseenheid kun je herkennen door:

EigenOpleidingseenheidSleutel = '[ED0B]{4}[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}', m.a.w. een UUID die start met “ED0B” en met uitsluitend hoofdletters

1. Gegevens die eerder handmatig in RIO zijn aangeboden en niet met de OOAPI koppeling beheerd zullen worden hoeven NIET gesynchroniseerd te worden.
2. Selecteer enkel de meest recente opleidingseenheden en aangeboden opleidingen.
3. Ook de cohorten staan vermeld. Controleer of deze overeenkomen met de cohorten in het SIS. Zorg er voor dat de cohorten in het SIS, het aanbiedende systeem, correct en volledig zijn. De koppeling overschrijft namelijk alle cohorten in RIO. Daardoor bestaat het risico dat cohorten in RIO verloren gaan wanneer deze niet in het aanbiedende systeem geregistreerd zijn.
4. De Excel tool wordt mogelijk nog aangescherpt:
   1. Op dit moment staan er niet veel HO opleidingsvarianten in RIO. (momenteel maar bij 4 instellingen) Mogelijk wordt toegevoegd WAARVAN (welke HO-opleiding (ISAT-code)) het een variant is om een match te kunnen maken.
   2. (Aangeboden) HO Opleidingsonderdelen (Onderwijseenheid en Onderwijseenhedenclusters) ontbreken nog. Er is een aantal instellingen die in totaal 200+ opleidingsonderdelen hebben geregistreerd. Deze zullen ook met het SIS gematched moeten worden. Tot de aanpassing van de tool helpen mogelijk deze losse downloads: ho_opleidingsonderdelen & aangeboden_ho_opleidingsonderdelen
5. Tijdens het testen is gebleken dat met name de grote bestanden niet of niet geheel werden gedownload. In het laatste geval lijkt het bestand compleet maar is dat niet zo. De Excel tool werkt dan wel maar de resultaten zijn niet goed. Neem dus de tijd om de downloads volledig te laten afwerken en let met name op de omvang van de grotere bestanden. DUO heeft aangegeven dat dit probleem is opgelost door enkele aanpassingen op de omgeving DUO Open Onderwijsdata. Mogelijk dus dat dit probleem niet meer zal optreden. Hier een indicatie van de omvang ten tijde van onze testen:

4.2 Synchronisatie tooling SURFeduhub

SURFeduhub biedt de in de OOAPI koppeling twee API’s aan, een om te linken en een om te unlinken. Deze API’s kunnen verschillend gebruikt worden afhankelijk van de situatie bij een instelling. (meer info op de OOAPI wiki)

4.2.1 Synchronisatie voor instellingen via het SIS van een leverancier

De leverancier heeft het linken ingebouwd in het SIS of biedt een aparte migratie aan.

• Per te synchroniseren opleidingseenheid of aangeboden opleiding uit RIO wordt in het SIS de overeenkomstige RIO code toegevoegd. Selecteer daartoe bij elk RIO te synchroniseren gegeven het overeenkomstige gegeven in het SIS. Voeg de RIO codering toe aan het gegeven in het SIS en geef vervolgens het SIS de opdracht om de gegevens te synchroniseren. Doe dit vervolgens voor álle te synchroniseren gegevens in RIO. De leverancier van het SIS zal mogelijk een uitgebreidere handleiding hebben voor deze actie.
• Vanuit enerzijds het overzicht van alle gegevens uit RIO (mogelijk via bijvoorbeeld de Excel tool) en anderzijds het overzicht van alle data in het SIS kan een script worden gemaakt en uitgevoerd welke alle benodigde links in een keer aanbrengt. Feitelijk hoeft dit script maar één keer te worden uitgevoerd vóórdat een instelling de OOAPI koppeling in productie gaat gebruiken.

4.2.2 Synchronisatie voor instellingen met een eigen OOAPI-endpoint

De instelling kan het linken ingebouwd in het aanleverende systeem of via aan aparte migratie job aanroepen.

• Vanuit het aanleverende systeem (SIS/Datahub, …) aan te roepen waarmee per opleiding de informatie wordt gelinkt via SURFeduhub
• Door een script te bouwen en via SURFeduhub in bulk te laten uitvoeren. Dit is qua opzet gelijk aan punt 2) in de vorige paragraaf.

5 Enkele aandachtspunten

5.1 FOUTIEF gesynchroniseerd?

SURFeduhub biedt een “unlink” job aan. Deze job doet niets anders dan het verwijderen van een “eigenSleutel” uit een OpleidingsEenheid of een AangebodenOpleiding in RIO, zodat de “eigenSleutel” volgens het proces beschreven bij 4.2 of 4.3 alsnog aan de juiste entiteit in RIO gekoppeld kan worden.

1. Synchroniseer je via het SIS dan biedt het SIS een mogelijkheid tot unlinken die vervolgens de SURFeduhub unlink job aanroept.
2. Heeft de instelling een eigen OOAPI-Endpoint dan moet de functie “unlink” daarin worden aangeboden.

5.2 CROHO/Loket Erkenningen Opleidingen HO

Vanuit het CROHO worden dagelijks de geaccrediteerde opleidingen geconverteerd naar RIO. De reeds aanwezige opleidingen in RIO worden door het proces van de hier beschreven synchronisatie gelijkgetrokken tussen RIO en het SIS.

Het kan voorkomen dat er ná de synchronisatie een nieuwe opleiding geaccrediteerd wordt en vervolgens via het CROHO in RIO wordt geplaatst. Dan ontstaat een nieuwe opleiding dus nog niet gesynchroniseerd is met de opleiding in het SIS.

1. Voor de instellingen die via het SIS synchroniseren kan deze nieuwe opleiding alsnog gesynchroniseerd worden;
2. Voor de instellingen met een eigen OOAPI-endpoint kan ook, gebruikmakend van de LINKapi achteraf gesynchroniseerd worden.

Deze situatie is niet meer van toepassing wanneer LEO HO wordt geïmplementeerd als vervanger voor aCROHO. De verwachting is dat dit einde Q1 2024 zal gebeuren.

Het aantal nieuwe onderwijserkenningen is gemiddeld genomen niet groot. Als voor een instelling een nieuwe geaccrediteerde opleiding wordt opgenomen in het CROHO ontvangt de instelling een bericht van DUO.  In dit bericht wordt gewezen op het uitvoeren van de synchronisatie tussen de nieuwe geaccrediteerde opleiding en de opleiding in het SIS.

5.3 Mutaties in RIO tijdens synchronisatie

Gegevens die via EDU-DEX worden beheerd staan los van de synchronisatie en mogen gedurende dit proces gewijzigd worden.

Omdat het vergaren van de RIO informatie een momentopname is moeten mutaties in RIO met aandacht worden uitgevoerd voor dié gegevens die nog niet zijn gesynchroniseerd. Wijzigingen, met name toevoegingen, zou kunnen betekenen dat deze niet in de synchronisatie worden opgemerkt omdat ze ten tijde van het vergaren van de RIO informatie nog niet bestonden.

5.4 RIO gegevens nog niet in het SIS?

Komt een gegeven wél voor in RIO maar niet in het SIS, en moet het gegeven later wél met de OOAPI koppeling worden beheerd dan moet het gegeven alsnog in het SIS worden aangemaakt en gesynchroniseerd worden met het gegeven in RIO.

5.5 Cohorten

De cohorten kunnen vanuit de OOAPI koppeling voorzien worden van de cohortCode zoals die ook al handmatig is opgevoerd in RIO. Wanneer de opleiding beschikbaar wordt gesteld in het kader van de STAP-regeling hoeft in dat geval geen rekening te worden gehouden met de regelmatige koppeling naar het UWV.

Bij het aanleveren van een opleiding worden de eventueel aanwezige cohorten in RIO overschreven door de nieuw aangeboden cohorten. Daarmee is de expliciete synchronisatie van de cohorten niet noodzakelijk omdat een cohort afzonderlijk toch niet wordt gewijzigd en impliciet vanwege de synchronisatie van de aangeboden opleiding wordt bijgewerkt.

LET OP: Het kan voorkomen dat in RIO andere cohort informatie bij de opleiding staat dan in het SIS. Controleer vóórdat een opleiding met cohorten wordt gesynchroniseerd welke situatie correct is. Pas daar de inhoud van het SIS eventueel op aan vóórdat de synchronisatie voor deze opleiding wordt uitgevoerd.

6 Vragen?

Zijn er vragen rondom de synchronisatie, werkwijze, tooling o.i.d., gebruik dan de aanwezige kanalen om je vraag te stellen.

SURFeduhub, OOAPI endpoint of de specifieke Link- en Unlink API:

• Helpdesk SURFeduhub
• per mail naar surfeduhub@surf.nl
• of telefonisch via 0787-3000, op werkdagen van 9.00 – 17.00 uur
• Kijk ook eens op de OOAPI wiki

De synchronisatie in mijn SIS werkt (deels) niet of zijn er vragen hoe de synchronisatie via het SIS toe te passen:

• Stel je vraag aan je SIS leverancier of
• Aan de ontwikkelgroep binnen je eigen instelling in geval van een eigen OOAPI endpoint

Vragen en/of hints voor de Excel tooling:

• Stel je vraag per mail aan STAP@ORG.hanze.nl

Vragen betreffende RIO:

• Zoek de informatie in het RIO informatiemodel
• Of anders in de Kennisbank RIO
• Kijk op de DUO Open Onderwijsdata
• Mail de helpdesk RIO op rio@duo.nl
• Of bel de helpdesk RIO op 050-5997738, optie 4, op werkdagen van 9.00 – 13.00 uur