Employees API

Titel	Employees API
Status	IN ONTWIKKELING BESLUITVORMING IN BEHEER
Versie	Documentatie: 0.0.3
Versie	schemaVersion: 0.0.3
Datum	18 April 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.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst	Onderwijsmedewerkers Onderwijsmedewerkers Communicatie Onderwijsmedewerkers Organisatierollen
Scopes	employee.basic employee.communication employee.roles
Entiteiten	Employee EmployeeCommunication EmployeeRoles
Bron	Administratiesysteem onderwijsmedewerker
Afnemer	Administratiesysteem onderwijsdeelnemer Bestelomgeving leermiddelen Identiteitsbeheervoorziening
Endpoints	Administratiesysteem onderwijsmedewerker GET Employee GET Employees for School GET Employee Communication GET Employees Communication for School GET Employee Roles GET Employees Roles 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

Berichtdefinitie: Employee (Onderwijsmedewerker)

Het object Student beschrijft de identifiers en de namen van de onderwijsdeelnemer.

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 de berichten. 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 van de onderwijsmedewerker		V
familyName	string	string	De achternaam van de onderwijsmedewerker		V
familyNamePrefix	string	string	Het tussenvoegsel uit de achternaam van de onderwijsmedewerker		V
sourceId	string	uuid	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 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

Berichtdefinitie: EmployeeCommunication

Het object EmployeeCommunication bevat het mailadres en de telefoonnummers van de onderwijsmedewerker bij de onderwijsaanbieder. Dit object is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen en gegevensafnemer zijn van de gegevensdienst Onderwijsmedewerkers Communicatie.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
sourceId	string	uuid	De referentie naar het sourceID van de onderwijsmedewerker.		V	Er is in dit bericht bewust gekozen voor het sourceID om op deze manier een betekenisloze identifier te hebben in de uitwisseling.
email	string	string	Het e-mailadres van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder	employee@school.nl	V
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

Berichtdefinitie: EmployeeRoles

Het object EmployeeRoles bevat de organisatiefuncties die een onderwijsmedewerker vervult bij een onderwijsaanbieder. Dit object is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen en gegevensafnemer zijn van de gegevensdienst Onderwijsdeelnemers Organisatierollen.

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
sourceId	string	uuid	De referentie naar het sourceID van de onderwijsdeelnemer.		V	Er is in dit bericht bewust gekozen voor het sourceID om op deze manier een betekenisloze identifier te hebben in de uitwisseling.
organisationRoles	array	organisationRole	Een lijst met organisatierollen die de onderwijsmedewerker vervult bij onderwijsaanbieders.		V

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

Endpoints combineren?

In de huidige opzet is er voor iedere scope een separaat endpoint. Een andere inrichtingskeuze is om twee endpoints te behouden:

GET Employee
GET Employees for School

Afhankelijk van de scope die je hanteert krijg je vervolgens meer of minder attributen in de response.

Voordeel van deze inrichting is dat een Client via één request alle relevante informatie op kan vragen.

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: Berichtdefinities 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.
  - Bericht 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 bericht 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: Berichtdefinities 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 berichtspecificaties.
  - 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.