Employees API

Titel

Employees 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 Employees API wordt gebruikt om persoonsgegevens over onderwijsmedewerkers uit het Administratiesysteem onderwijsmedewer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsmedewerker met het Administratiesysteem onderwijsmedwerker 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

Onderwijsmedewerkers
Onderwijsmedewerkers Communicatie
Onderwijsmedewerkers Organisatierollen

Scopes

  • eduv.employee.basic

  • eduv.employee.communication

  • eduv.employee.roles

Objecten

  • Employee

    • EmployeeCommunication

    • EmployeeRoles

Bron

Administratiesysteem onderwijsmedewerker

Afnemer

  • Administratiesysteem onderwijsdeelnemer

  • Bestelomgeving leermiddelen

  • Dienst met SSO

  • Authenticerende Dienst

  • Authenticerende Identity Provider

  • Delegerende Identity Provider

Endpoints

Administratiesysteem onderwijsmedewerker

  • POST Search Employee

  • GET Employee

  • GET Employees 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: Employee (Onderwijsmedewerker)

Het object Employee beschrijft de identifiers, de namen van de onderwijsmedewerker en overige kenmerken. Dit object is beschikbaar vanuit de scope employee.basic.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

userMasterIdentifier

string

string

De primaire identifier voor de onderwijsmedewerker.

 

V*

De werkingsregels is dat de primaire identifier wordt gehanteerd in het object.

Er is nog geen primaire identifier voor onderwijsmedewerkers. Enkel secundaire identifiers worden gehanteerd.

In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.

userIds

array

userId

Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.

[{userId: ‘pietjepukkelen@petteflatcollege', userIdType: 'nlEduPersonRealId’}]

Zie referentie naar eindgebruiker

V*

Zodra een secundaire identifier voor een uitzonderingssituatie gehanteerd wordt dan wordt naast het Id ook het Type gespecificeerd.

Zie de pagina Identiteiten voor de toegestane secundaire identifiers.

givenName

string

string

De voornaam (of voornamen) van de onderwijsmedewerker

 

V

 

preferredFirstName

string

string

De roepnaam van de onderwijsmedewerker

 

V

 

familyName

string

string

De achternaam van de onderwijsmedewerker

 

V

 

familyNamePrefix

string

string

Het tussenvoegsel uit de achternaam van de onderwijsmedewerker

 

O

 

sourceId

string

string

Een unieke identifier die gegenereerd is door het Administratiesysteem onderwijsmedewerker en binnen dit systeem uniek is.

 

V

De sourceId wordt gebruikt om informatie over dit object op te vragen in de koppelvlakspecificatie.

Deze identifier is betekenisloos en daarmee geen persoonsgegeven.

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

 

Attributen : EmployeeCommunication

De attributen EmployeeCommunication bevatten het mailadres en de telefoonnummers van de onderwijsmedewerker bij de onderwijsaanbieder. Deze attributen alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope employee.communication.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

email

string

string

Het e-mailadres van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder

employee@school.nl

O

 

phone

string

string

Het vaste telefoonnummer van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder

010-1234567

O

 

mobile

string

string

Het mobiele telefoonnummer van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder

06-12345678

O

 

Attributen: EmployeeRoles

De EmployeeRoles attributen bevatten de organisatiefuncties die een onderwijsmedewerker vervult bij een onderwijsaanbieder. Dit attribuut is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope employee.roles.

Optioneel

Organisatiefuncties zijn een optioneel onderdeel van de Employees API. Op basis van expliciete behoeften in ketenprocessen kunnen deze functies worden benut.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

organisationRoles

array

OrganisationRole

Een lijst met organisatierollen die de onderwijsmedewerker vervult bij onderwijsaanbieders.

 

O

 

Object: OrganisationRoles

De organisatierol (organisationRole) van een onderwijsmedewerker betreft een rol die wordt vervuld op een onderwijsaanbieder..

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

organisation

string

SchoolReference

Een referentie naar een onderwijsaanbieder.

Zie referentie onderwijsorganisatie

V

 

organisationRole

string

ENUM

De organisatiefunctie die de onderwijsmedewerker vervult bij de onderwijsaanbieder.

Het betreft een ENUM bestaande uit:

  • administratief-medewerker

  • applicatiebeheerder

  • begeleider

  • invalkracht

  • ibp-er

  • leermiddelencoordinator

  • leraar

  • mentor

  • onderwijsbestuurder

  • onderwijsdirecteur

  • stagiair

leraar

V

Er wordt één organisatiefunctie gekozen.

De organisatiefuncties zijn gebaseerd op de functies zoals beschreven op de pagina Onderwijsorganisaties en actoren.

beginDate

string

date

Begindatum van de organisatiefunctie bij de onderwijsaanbieder.

2022-08-01

V

 

endDate

string

date

Einddatum van de organisatiefunctie bij de onderwijsaanbieder.

2023-07-31

O

 

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 Rostering 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 Employees 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: 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.

  • 0.0.4: De separate endpoints voor de diverse scopes zijn gecombineerd in een enkel endpoint. Ook is een endpoint toegevoegd om een onderwijsmedewerker op te vragen op basis van een userId en een userIdType.

  • 0.0.5: Typo’s in de YAML. preferredFirstName toegevoegd aan attribuut Employee.

  • 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.