Association API

Titel

Association API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.9.1

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:

Samenvatting

Gegevensdienst

Onderwijsinrichting

Scopes

  • eduv.association

Entiteiten

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.

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.

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.

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.