Association API

Titel	Association API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 0.9.1
Versie	schemaVersion: 0.9.1
Datum	27 September 2024
Auteurs	Architectenraad Edu-V
Acties	Review en doorontwikkeling op basis van input LAS leveranciers

De Association API wordt gebruikt om informatie over uit het Administratiesysteem onderwijsdeelnemer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsinrichting met het Administratiesysteem onderwijsdeelnemer als Bron.

Scope: werkingsgebieden funderend onderwijs en vavo

De afspraken met betrekking tot de gegevensdiensten uit de administratiesystemen zijn van toepassing op de werkingsgebieden:

Primair onderwijs
Gespecialiseerd onderwijs
Voortgezet onderwijs
Voortgezet algemeen volwassenenonderwijs (vavo)

De gegevensdiensten zijn niet ontwikkeld voor het middelbaar beroepsonderwijs. In het middelbaar beroepsonderwijs wordt gebruik gemaakt van OOAPI.

De technische specificatie bestaat uit:

1 Samenvatting
2 Object: SchoolPeriod (SchoolPeriode)
3 Object: Enrollment (Inschrijving)
4 Object: Assignment (Toewijzing)
5 Object: Group (Stamgroep of Lesgroep)
6 Event processor: Aanspraakmanager
7 Status- en foutcodes
8 Technisch: API specificatie
9 Release notes

Samenvatting

Gegevensdienst	Onderwijsinrichting
Scopes	eduv.association
Entiteiten	SchoolPeriod Enrollment Assignment Group
Bron	Administratiesysteem onderwijsdeelnemer
Afnemer	Bestelomgeving leermiddelen Aanspraakmanager Identitietsbeheervoorziening
Endpoints	Administratiesysteem onderwijsdeelnemer GET SchoolPeriod GET SchoolPeriods for School GET Enrollment GET Enrollments for School POST Get Enrollments for Student at School GET Assignment GET Assignments for School POST Get Assignments for Employee at School GET Group GET Group for School
Notifications	De Notifications API kan gebruikt worden om als afnemer een notificatie te ontvangen bij een wijziging in de stand (nieuw/gewijzigd/verwijderd). Hiervoor dient zowel de bron als de afnemer dan de Berichteninfrastructuur en de Notifications API te hebben geïmplementeerd. Berichteninfrastructuur voor het versturen en ontvangen van berichten Notifications API

Object: SchoolPeriod (SchoolPeriode)

Het object SchoolPeriod beschrijft de periodes waarin onderwijs wordt gegeven binnen de onderwijsaanbieder. De velden uit het object zijn gebaseerd op een AcademicSession zoals ook beschreven in de internationale 1EdTech standaard OneRoster.

Optioneel

De gelaagde structuur van schoolperiodes is optioneel voor de Association API. Op basis van expliciete behoeften van onderwijsaanbieders en/of ketenprocessen kunnen schoolperiodes benut worden.

In de eerste versie voldoet een schoolperiode van het type schoolYear, bijvoorbeeld ‘23-’24.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
schoolPeriodId	string	string	Een unieke identifier voor het object		V
title	string	string	Naam van de schoolperiode	2021-2022 2022H1	V
type	string	ENUM	Het type schoolperiode. Hierbij wordt een ENUM gehanteerd bestaande uit: gradingPeriod schoolYear semester term	schoolYear	O	De waardelijst is overgenomen vanuit OneRoster voor SessionType van een AcademicSession.
superSchoolPeriod	string	string	Een referentie naar een bovenliggend SchoolPeriod object.		O	De superSchoolPeriod van een semester is bijvoorbeeld het schoolYear
subSchoolPeriod	array	string	Referenties naar onderliggende SchoolPeriod objecten.		O	De subSchoolPeriods van een schoolYear zijn bijvoorbeeld de semesters
startDate	string	date	Startdatum van de schoolperiode	2022-08-01	V
endDate	string	date	Einddatum van de schoolperiode	2023-07-31	V
status	string	ENUM	De status van dit object.	active tobedeleted	V	De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.
dateCreated	string	datetime	Datum en tijdstip waarop de entiteit is aangemaakt	2017-07-21T17:32:28Z	V
dateLastModified	string	datetime	Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd	2022-08-11T15:31:12Z	V

Object: Enrollment (Inschrijving)

Het object Enrollment beschrijft de inschrijving van een onderwijsdeelnemer op een AangebodenOpleiding of een AangebodenVak voor een schoolperiode op een onderwijsaanbieder.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
enrollmentId	string	string	Een unieke identifier voor het object		V
student	object	UserReference	Een referentie naar een onderwijsdeelnemer.	Zie referentie Eindgebruiker	V
enrollmentType	string	ENUM	Het type inschrijving. Hierbij wordt een ENUM gehanteerd bestaande uit: `study` `subject`	`study`	V	Inschrijvingen op AangebodenOpleidingen worden minimaal beschikbaar gesteld. De vullingsregels voor inschrijvingen op vakken moet nog bepaald worden.
study	string	string	Een referentie naar een AangebodenOpleiding (StudyOffering) object waarop de onderwijsdeelnemer is ingeschreven.		V*	Verwijzing naar studyOfferingId Verplicht indien het enrollmentType `study` betreft.
subject	string	string	Een referentie naar een AangebodenVak (SubjectOffering) object waarop de onderwijsdeelnemer is ingeschreven.		V*	Verwijzing naar subjectOfferingId Verplicht indien het enrollmentType `subject` betreft.
schoolPeriod	string	string	Een referentie naar een Schoolperiode (SchoolPeriod) object waarbinnen de inschrijving valt.		V	Verwijzing naar schoolPeriodId Waarde mag niet gewijzigd worden
beginDate	string	date	Begindatum van de inschrijving	2022-08-01	V	De begindatum van de inschrijving kan afwijken van de startdatum van de schoolperiode.
endDate	string	date	Einddatum van de inschrijving	2023-07-31	O	De einddatum is een verplicht veld indien de inschrijving eerder afloopt dan de schoolperiode.
status	string	ENUM	De status van dit object.	active tobedeleted	V	De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.
dateCreated	string	datetime	Datum en tijdstip waarop de entiteit is aangemaakt	2017-07-21T17:32:28Z	V
dateLastModified	string	datetime	Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd	2022-08-11T15:31:12Z	V

Object: Assignment (Toewijzing)

Het object Assignment beschrijft de toewijzing van een onderwijsmedewerker aan een groep of individu voor een schoolperiode op een onderwijsaanbieder.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
assignmentId	string	string	Een unieke identifier voor het object		V
employee	object	UserReference	Een referentie naar een onderwijsmedewerker.	Zie referentie Eindgebruiker	V
assignmentType	string	ENUM	Het type inschrijving. Hierbij wordt een ENUM gehanteerd bestaande uit: `class-teacher` `teacher` `coach`	`teacher`	V	Het toewijzingstype betreft één van: Klassendocent (in het primair onderwijs ook wel leerkracht en in het voortgezet onderwijs mentor) Vakdocent (in het primair onderwijs ook wel leerkracht voor een vak en in het voortgezet onderwijs de vakdocent) Begeleider (in het primair onderwijs de individueel begeleider van een leerling en in het voortgezet onderwijs bijvoorbeeld de persoonlijke mentor)
group	string	string	Een referentie naar een Groep (Group) object waar de onderwijsmedewerker aan is toegewezen.		V*	Verwijzing naar groupId Verplicht indien het assignmentType `class-teacher` of `teacher` betreft.
subject	string	string	Een referentie naar een AangebodenVak (SubjectOffering) object dat wordt onderwezen in de groep		V*	Verwijzing naar subjectOfferingId Dit is een verplicht veld indien het assignmentType `teacher` betreft én de onderwijsmedewerker voor een enkel AangebodenVak toegewezen is aan de groep.
student	string	UserReference	Een referentie naar een onderwijsdeelnemer waar de onderwijsmedewerker aan is toegewezen.	Zie referentie Eindgebruiker	V*	Verplicht indien het assignmentType `coach` betreft.
schoolPeriod	string	string	Een referentie naar een Schoolperiode (SchoolPeriod) object waarbinnen de inschrijving valt.		V	Verwijzing naar schoolPeriodId Waarde mag niet gewijzigd worden
beginDate	string	date	Begindatum van de toewijzing	2022-08-01	V	De begindatum van de toewijzing kan afwijken van de startdatum van de schoolperiode.
endDate	string	date	Einddatum van de toewijzing	2023-07-31	O	De einddatum is een verplicht veld indien de toewijzing eerder afloopt dan de schoolperiode.
status	string	ENUM	De status van dit object.	active tobedeleted	V	De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.
dateCreated	string	datetime	Datum en tijdstip waarop de entiteit is aangemaakt	2017-07-21T17:32:28Z	V
dateLastModified	string	datetime	Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd	2022-08-11T15:31:12Z	V

Object: Group (Stamgroep of Lesgroep)

In het Group object worden de stamgroepen en lesgroepen van een onderwijsaanbieder in een bepaalde schoolperiode uitgewisseld.

De werkingsregel is dat de onderwijsmedewerker die middels een toewijzing gekoppeld is aan de Group ook daadwerkelijk alle voortgang en resultaten van de onderwijsdeelnemers in het vak mag inzien. In de praktijk betekent dit het volgende:

Voor iedere groep waarbij de samenstelling aan onderwijsdeelnemers verschilt wordt een nieuwe Group uitgewisseld.
Lesgroepen in het voortgezet onderwijs met dezelfde samenstelling aan leerlingen kunnen verschillende vakken volgen. In de toewijzing wordt gespecificeerd welk vak de onderwijsmedewerker aan de groep geeft.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
groupId	string	string	De unieke identifier van de SchoolLesGroep		V	Waarde mag niet gewijzigd worden
groupName	string	string	Naam van de groep	A4bBiol	V
groupType	string	ENUM	The type groep. Hierbij wordt een ENUM gehanteerd: `class` `lesson-group`	`class`	V	`class` wordt gekozen indien het een stamgroep betreft. `lesson-group` wordt gekozen indien het een lesgroep is.
students	array	UserReference	Referentie naar de onderwijsdeelnemers die lid zijn van de stamgroep of de lesgroep	Zie referentie Eindgebruiker	V	Onderwijsdeelnemers worden aan het `Group` object toegevoegd conform de volgende regels: Als de requestdatum na de begindatum van de groep zit: alle onderwijsdeelnemers die op de datum van de requestdatum daadwerkelijk lid zijn van de groep. Dus niet de onderwijsdeelnemers die in de toekomst lid worden van de groep. Als de requestdatum voor de begindatum van de groep zit: voor alle onderwijsdeelnemers die vanaf de begindatum in de groep zitten. (Dit is vooral handig om de groepen voor het volgende schooljaar uit te wisselen).
assignments	array	string	Een referentie naar een Toewijzing (Assignment) waarin een onderwijsmedewerker is toegewezen aan deze groep.		V	Verwijzing naar assignmentId
schoolPeriod	string	string	Een referentie naar een Schoolperiode (SchoolPeriod) object waarbinnen de inschrijving valt.	2021-2022	V	Verwijzing naar schoolPeriodId Waarde mag niet gewijzigd worden
beginDate	string	date	Begindatum van de groep	2022-08-01	V	De begindatum van de groep kan afwijken van de startdatum van de schoolperiode.
endDate	string	date	Einddatum van de groep	2023-07-31	O	De einddatum is een verplicht veld indien de groep eerder afloopt dan de schoolperiode.
status	string	ENUM	De status van dit object.	active tobedeleted	V	De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.
dateCreated	string	datetime	Datum en tijdstip waarop de entiteit is aangemaakt	2017-07-21T17:32:28Z	V
dateLastModified	string	datetime	Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd	2022-08-11T15:31:12Z	V

Event processor: Aanspraakmanager

De Aanspraakmanager is bij het leveren van digitale leermiddelen verantwoordelijk voor het toekennen van aanspraken op basis van leveringsorders. Bij de levervarianten Opleiding, Vak en Groep wordt dit gedaan op basis van gegevens uit de Association API. In onderstaand overzicht wordt aangegeven hoe de Aanspraakmanager dient te reageren op basis van nieuwe of verwijderde inschrijven en groepen of gewijzigde groepssamenstellingen.

Bericht	Wijziging		Verwerking door Leermiddelenportaal
Enrollment	Nieuw	Nieuw	Voor iedere nieuwe inschrijving wordt gekeken of de school voor het gespecificeerde Opleidingsjaar of het Vak een leveringsorder heeft. Indien dit het geval is wordt er voor de onderwijsdeelnemer een aanspraak aangemaakt.
Enrollment	Verwijderd	Verwijderd	Voor iedere inschrijving die wordt verwijderd wordt gekeken of de aanspraak van de onderwijsdeelnemer die is gebaseerd op de inschrijving reeds in gebruik genomen is. Is dit niet het geval dan wordt de aanspraak geannuleerd.
Group	Nieuw	Nieuw	Zodra er een nieuwe groep wordt aangemaakt dan wordt er gekeken of de onderwijsaanbieder voor deze groep een leveringsorder heeft. Voor alle onderwijsdeelnemers die lid zijn van de groep wordt er een aanspraak aangemaakt.
	Verwijderd	Verwijderd	Zodra er een groep wordt verwijderd dan wordt er gekeken of er aanspraken zijn toegekend op basis van een leveringsorder voor de groep. De aanspraken die nog niet in gebruik zijn genomen worden geannuleerd.
	Students	Nieuw	Zodra er een onderwijsdeelnemer wordt toegevoegd aan een groep dan wordt er gekeken of de onderwijsaanbieder voor deze groep een leveringsorder heeft. Indien dit het geval is wordt er voor de onderwijsdeelnemer een aanspraak aangemaakt.
	Students	Verwijderd	Voor iedere onderwijsdeelnemer die wordt verwijderd uit een groep wordt gekeken of de aanspraak van de onderwijsdeelnemer die is gebaseerd op deelname aan de groep reeds in gebruik genomen is. Is dit niet het geval dan wordt de aanspraak geannuleerd.

Status- en foutcodes

Voor alle APIs uit het Afsprakenstelsel Edu-V zijn de status- en foutcodes beschreven op de pagina Status- en foutcodes. Hierbij is onderscheid gemaakt in algemene en voor de API specifieke status- en foutcodes.

Technisch: API specificatie

Release notes

0.0.1: De Association API was voorheen een onderdeel van de SIS API. Hierin waren de volgende wijzingen gedaan:
- 0.0.1: Eerste draft van de API.
- 0.0.2: Objecten en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.
- 0.0.3: De technische specificatie is verder uitgewerkt. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:
  - GET all endpoints zijn toegevoegd voor alle objecten.
  - Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van regie op gegevens en de M2M identificatie en authenticatie.
  - Object Teacher is hernoemd naar Employee inclusief het attribuut role. In dezelfde lijn is ook teacherReference hernoemd naar employeeReference
  - De waardelijst studyYear is verduidelijkt.
  - Het attribuut class van de Student is een separaat object geworden inclusief employees.
  - De status- en foutcodes zijn toegevoegd aan de documentatie en de YAML.
  - In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
  - De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.
- 0.0.4: Objecten geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader.
- 0.0.5: Terminologie in YAML bijgewerkt.
- 0.0.6: Gegevensdiensten van SIS API opgesplitst in:
  - Onderwijsorganisatie
  - Adresgegevens fijndistributie
  - Onderwijsaanbod
0.0.2: De Association API is opgesteld op basis van een herziening van de SIS API. In deze herziening is aansluiting gezocht bij de best practices uit bestaande standaarden en een uiteenzetting van ontwerpeisen vanuit de flexibilisering van het onderwijs.
0.0.3: Rostering API is hernoemd naar Association API. De informatie in de objecten Inschrijving, Toewijzing en Groep zijn gewijzigd:
- Het AangebodenVak is gekoppeld aan de toewijzing en verwijderd uit de groep.
- De groep is enkel de samenstelling van onderwijsdeelnemers en de toewijzingen vanuit onderwijsmedewerkers.
- De toewijzingsrol is verwijderd en verwerkt in het toewijzingstype. Dit is aangepast naar klassendocent, docent en begeleider.
0.0.4: De volgende wijzigingen zijn gedaan:
- Wijzigingen in de architectuur:
  - Attribuut schemaVersion is verwijderd uit de objecten.
  - Query parameter schemaVersion is verwijderd uit de koppelvlakken.
  - Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
  - Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
- Wijzigingen in de documentatie en de YAML:
  - De documentatie van het Groep object en de YAML kwamen niet overeen.
0.0.5: Typo’s in de YAML.
0.0.6: / verwijderd aan einde van endpoints.
0.0.7: de attributen children en parent van het object SchoolPeriod zijn hernoemd naar respectievelijksubSchoolPeriods en superSchoolPeriod. Dit wijkt af van OneRoster maar voorkomt semantische misverstanden over ouders en kinderen. Op deze manier is het duidelijk dat het gaat om hiërarchische relaties tussen SchoolPeriod objecten. Ook zijn de vullingsregels voor het opnemen van students in het Group object duidelijker gespecificeerd.
0.9.0: Het Bestuurlijk Overleg heeft tijdens de bijeenkomst van 27 juni 2024 het Afsprakenstelsel Edu-V als versie 0.9.0 goedgekeurd voor implementatie.
0.9.1: Wijzigingen naar aanleiding van RFC’s:
- Op basis van RFC002 is de scope aangepast met een prefix eduv.. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.
- De parameters voor paginering zijn uit de koppelvlakspecificatie verwijderd. Binnen het afsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.
- De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.