API-aanpassingen: endpoint-overrides en hooks

Waar u het vindt

Module Beheer, scherm Import/Export, onderdeel API-aanpassingen, knop API.

Het scherm is voorbehouden aan Premium-accounts en beschermd door een aanvullende authenticatie: Omniscol vraagt het wachtwoord van de beheerder opnieuw op voordat het venster opengaat. Omdat alles wat u op dit scherm doet het technische contract van uw integratie raakt, gebeurt de inrichting ervan in overleg met Omniscol.

Algemene configuratie

Hier definieert u HTTP-headers (formaat sleutel1:waarde1;sleutel2:waarde2) die op alle hooks worden toegepast. Dit is de aangewezen plek om een authenticatietoken naar uw eigen server mee te sturen (bijvoorbeeld een Authorization: Bearer … die uw server verwacht). Bij een override hoort de authenticatie juist thuis in de headers van het endpoint zelf (zie hieronder).

Override van een endpoint

Een override herdefinieert een endpoint van de Omniscol-API, zodat de webapplicatie in plaats daarvan een andere URL aanroept. Drie toepassingen, van de krachtigste naar de eenvoudigste.

Gegevens live uit uw informatiesysteem aanleveren

Dit is de krachtigste toepassing. U leidt een leesendpoint om naar een externe URL — meestal een ETL die het interne informatiesysteem van uw instelling ontsluit. De webapplicatie haalt de gegevens dan live uit dat systeem, in plaats van uit de lokale kopie die Omniscol bijhoudt.

Concreet: is de omleidings-URL een absoluut extern adres, dan roept de webapplicatie die rechtstreeks aan, zonder omweg via de servers van Omniscol, en verwerkt het antwoord ongewijzigd — precies alsof het van Omniscol kwam. De enige voorwaarde is dat uw systeem antwoordt in het formaat dat Omniscol voor dat endpoint verwacht (dezelfde JSON-structuur): er is geen tussenliggende omzetting. Voor dat endpoint wordt de lokale kopie van Omniscol niet meer geraadpleegd; wat u ziet, zijn de actuele gegevens uit uw systeem.

Voorbeeld: de vakkencatalogus van de instelling wordt rechtstreeks uit uw informatiesysteem aangeleverd, zodat elke bijwerking aan de kant van de school meteen zichtbaar is in Omniscol, zonder nieuwe import.

De authenticatie naar uw systeem gaat hier mee in de headers van het endpoint zelf (bijvoorbeeld een Authorization: Bearer …), die u op de regel van de override invult. Ook de HTTP-methode kan per endpoint worden opgelegd.

Een endpoint van de applicatie zelf omleggen naar een live externe bron is even krachtig als veeleisend: doe dit samen met uw ICT-afdeling en in overleg met Omniscol.

Uw eigen server of een proxy ertussen plaatsen

U kunt de aanroepen ook via uw eigen server of een proxy laten lopen — bijvoorbeeld om cross-origin resource sharing (CORS) mogelijk te maken, of om eigen logica tussen de webapplicatie en Omniscol te schuiven.

Een endpoint uitschakelen

U schakelt een endpoint uit door er geen omleidings-URL aan te geven (methode null).

Weeg het effect op de interface goed af. Omniscol is een single-page webapplicatie (SPA) waarvan de interface-elementen worden aangestuurd door de beschikbare endpoints: knoppen, tabbladen en menu's verschijnen alleen als het endpoint waarvan ze afhangen bestaat. Een endpoint uitschakelen laat de interface-elementen die ervan afhangen bij de volgende weergave dus dynamisch verdwijnen — en schakelt u alle endpoints van een module uit, dan verdwijnt de hele module uit de navigatie. Die elementen worden verwijderd, niet alleen verborgen, en dat alles gebeurt zonder enige ingreep in de code: u wijzigt de configuratie en herlaadt de applicatie.

De tabel toont per endpoint: de sleutel (de interne code van de bewerking), de oorspronkelijke URL, de HTTP-methode, de nieuwe URL van de omleiding en specifieke headers. Met een zoekveld vindt u het endpoint terug waarvoor u een override wilt instellen.

Hooks (uitgaande aanroepen)

Een hook vraagt Omniscol om een HTTP-verzoek naar uw URL te sturen, nadat een bewerking geslaagd is. Dit is het mechanisme om een extern systeem realtime op de hoogte te houden — een informatiescherm, een elektronische leeromgeving, een hr-systeem, een eigen synchronisatie…

Een hook sluit u op twee manieren aan:

• op een specifiek endpoint (de sleutel van de bewerking);
• op een gegroepeerde gebeurtenis, die in één keer een hele familie bewerkingen dekt. Er bestaan drie gegroepeerde gebeurtenissen:
  • roosterwijziging — een wijziging die het geldende rooster raakt, neveneffecten inbegrepen: het opslaan van een rooster, het aanmaken, verplaatsen of verwijderen van lessen, het publiceren van een rooster, afwezigheden van een docent of een klas zodra er een datum geraakt wordt, en structurele verwijderingen (een lokaal, een vak…) op een gepubliceerd rooster — een vak verwijderen wist de lessen die het gebruikten, en dat is op zich al een wijziging. Bewerkingen die beperkt blijven tot een niet-gepubliceerd conceptrooster activeren de gebeurtenis niet;
  • wijziging van een docent (toevoegen, bijwerken of verwijderen);
  • wijziging van een vak (aangepaste vakken).

Voor elke hook vult u de callback-URL in, de HTTP-methode, het vakje “met gegevens” (moet de body van het oorspronkelijke verzoek meegestuurd worden?) en eigen headers.

Wat uw server ontvangt

De aanroep wordt verstuurd als application/json en bevat, naast uw eigen headers:

• de body van het oorspronkelijke verzoek als de optie “met gegevens” aanstaat;
• een blok metagegevens van Omniscol: de aangeroepen URL, de code van het endpoint, de methode, de parameters, het authenticatietoken van de gebruiker, de identificatie van de instelling en de configuratie van de hook zelf;
• headers voor traceerbaarheid: X-OS-original-query, X-OS-original-endpoint, X-OS-auth en X-School.

Voor de gebeurtenis roosterwijziging bevat de aanroep, wanneer de optie “met gegevens” actief is, bovendien een verschillenlijst van de lessen (toegevoegde, gewijzigde en verwijderde lessen) — handig om alleen door te geven wat er veranderd is.

Gedrag

Hooks worden op de achtergrond verstuurd, nadat de bewerking van de gebruiker geslaagd is: ze vertragen de interface niet en blokkeren die niet als uw server het laat afweten. Een uitgaande aanroep die mislukt, wordt gelogd, zonder het werk in Omniscol te onderbreken. Elke aanroep heeft een korte time-out (enkele seconden): uw server moet snel de ontvangst bevestigen en de rest aan zijn kant afhandelen.

Goed om te weten

• De Omniscol-API stelt een deel van de bewerkingen beschikbaar; een override of een hook geldt alleen voor de endpoints die daadwerkelijk beschikbaar zijn. Zie Omniscol-API voor de lijst en de authenticatie.
• Voor een integratie met een softwarepakket (ERP, hr-systeem, elektronische leeromgeving) is de speciale synchronisatie vaak geschikter — zie Synchronisatie met externe systemen. Intern wordt hetzelfde hooksysteem gebruikt.
• Wilt u dat een AI-agent uw gegevens raadpleegt zonder ontwikkelwerk, zie dan MCP — een externe AI-agent aansluiten.