Page Comparison

Titel

Employees API

Status

Purple

colour	title	In ontwikkeling

Status

title	In ontwikkelingROSA-Architectuurscan

Status

title	BEsluitvorming

Status

colour	Yellow
title	implementatie

Status

title	in beheer

Versie

Documentatie: 0.9.1

schemaVersion: 0.29.1

Datum

15 maart 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.

Tip

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:

...

Gegevensdienst	Onderwijsmedewerkers Onderwijsmedewerkers Communicatie Onderwijsmedewerkers Organisatierollen
Scopes	eduv.employee.basic eduv.employee.communication eduv.employee.roles
EntiteitenObjecten	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 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. Berichteninfrastructuur voor het versturen en ontvangen van berichten Notifications API

Anchor

...

employee

...

employee

...

Object: Employee (Onderwijsmedewerker)

Het object Student Employee beschrijft de identifiers en , de namen van de onderwijsdeelnemeronderwijsmedewerker 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 de berichtenhet 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.
schemaVersiongivenName	string	string	Het versienummer De voornaam (of voornamen) van de berichtdefinitie die wordt gehanteerd.	0.0.2	V	Conform Semantic Versioning 2.0.0	givenName	onderwijsmedewerker	V
preferredFirstName	string	string	De voornaam 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		VO
sourceId	string	uuidstring	Een GUID 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

Anchor
employee-communication
employee-communication

...

Attributen : EmployeeCommunication

Het object De attributen EmployeeCommunication bevat bevatten het mailadres en de telefoonnummers van de onderwijsmedewerker bij de onderwijsorganisatie. Dit object is onderwijsaanbieder. Deze attributen alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen en gegevensafnemer zijn van de gegevensdienst Onderwijsmedewerkers Communicatiedeze attributen. Voor deze attributen geldt een separate scope employee.communication.

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.

schemaVersion

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

0.0.2

V

Conform Semantic Versioning 2.0.0

email

string

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

employee@school.nl

VO

phone

string

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

010-1234567

O

mobile

string

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

06-12345678

O

Anchor
employee-roles
employee-roles

...

Attributen: EmployeeRoles

Het object De EmployeeRoles bevat attributen bevatten de organisatiefuncties die een onderwijsmedewerker vervult bij een onderwijsorganisatieonderwijsaanbieder. Dit object attribuut is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen en gegevensafnemer zijn van de gegevensdienst Onderwijsdeelnemers Organisatierollen. Voor deze attributen geldt een separate scope employee.roles.

Info

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.

schemaVersion

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

0.0.2

V

Conform Semantic Versioning 2.0.0

organisationRoles

array

organisationRoleOrganisationRole

Een lijst met organisatierollen die de onderwijsmedewerker vervult bij onderwijsorganisatiesonderwijsaanbieders.

VO

Anchor
organisation-roles
organisation-roles
Object:

...

OrganisationRoles

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

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
organisation	string	SchoolReference	Een referentie naar een onderwijsorganisatieonderwijsaanbieder.	Zie referentie onderwijsorganisatie	V
organisationRole	string	ENUM	De organisatiefunctie die de onderwijsmedewerker vervult bij de onderwijsorganisatieonderwijsaanbieder. 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 onderwijsorganisatieonderwijsaanbieder.	2022-08-01	V
endDate	string	date	Einddatum van de organisatiefunctie bij de onderwijsorganisatieonderwijsaanbieder.	2023-07-31	O

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.

...

Open api

filter	none
supportedSubmitMethods	none
showDownloadButton	true

openapi: 3.0.0
info:
  title: Employees API
  version: '0.09.21'
  description: |-
    The Employees API is implemented by the `Administratiesysteem onderwijsmedewerker`.
    
    Employee data is split into the following objects with corresponding attributes:
    - Basic data: identifiers and name
    - Communication: email, phone, and mobile
    - Roles: organisation roles of the employee within the school
    
    Not all Employee attributes are available to all consuming reference components.
    All objects have a different security scope which allows the `Administratiesysteem onderwijsmedewerker` to share the attributes only with the reference components that are allowed to receive the attributes.
    
    All consunming reference components require consent to request data from the Employees API.
    The Notifications API can be used by consuming reference components to receive notifications about new, modified, or deleted entitities within the Employees API.

    The Employees API has a scope of primary and secundarysecondary education. Vocational education is out of scope. For Vocational Education we advice to use the [Open Education API (OOAPI)](https://openonderwijsapi.nl/).
  contact:
    name: Edu-V
    url: www.edu-v.org/afsprakenstelsel
    email: info@edu-v.org
components:
  schemas:
  
    schemaVersion:
      type: string
      description: '|
        Schema version of this event/objectAPI using semantic versioning 2.0.0'.
      default: 0.0.2 The API version number is communicated in the header.
      Employee:  The major version is communicated in title:the EmployeeURI.
      description: 'The EmployeeFor objectmore withinformation itssee identifiers and name information.'the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      typedefault: object0.9.1
      x-tags:     
   - Employee:
      propertiestitle: Employee
       userMasterIdentifierdescription: |
        The type:Employee stringobject with its identifiers and name information.

   description: |    Based on the scopes additional attributes can be included Thein primarythis identifierobject.
for
the  Employee.      ### employee.communication
     For Employees this valueCommunication isdata empty.of Therethe isEmployee. noFor primaryEmployees identifierthis foris Employees.the `e-mail` address, `phone` number or `mobile` phone number userIds:as provided by the School.

     type: array  ### employee.roles
       description: |`organisationRoles` of the Employee within the school.
      Atype: secundaryobject
identifier for the Employee. This value isx-tags:
used whenever the primary identifier is not available. - Employee
      properties:
   For Employees this value is mandatory.userMasterIdentifier:
          itemstype: string
           typedescription: object|
            properties:The primary identifier for the Employee.
           userId: For Employees this value is empty. There is no primary identifier for Employees.
   type: string    userIds:
          userIdTypetype: array
          description: |
   type: string        A secondary identifier for a User. This value is used whenever the enum:primary identifier is not available.
            For Employees -this nlPersonProfileIdvalue is mandatory.
            (either userMasterIdentifier or userIds -is nlPersonRealIdrequired)
          items:
       - Las-key    type: object
            properties:
- BasispoortId             requireduserId:
              -  userIdtype: string
             - userIdType:
        schemaVersion:        type: string
   $ref: '#/components/schemas/schemaVersion'             givenNameenum:
          type: string       - NEPPI familyName:# nlPersonProfileId – value can be used for students and employees
type: string         familyNamePrefix:        - BPI # type:Basispoort stringID – value can be used for students and sourcedId:employees
          type: string       - eduID # eduID format:identifier uuid– value can be used for students and employees
  description: |             The Source Identifier- ofeckId the# object.ECK ThisiD is– avalue GUIDcan Systembe IDused for anemployees object.only, eckId is userIdType for userMasterIdentifier for students
     This is the GUID that   required:
Consumers will refer to when making API calls, or when needing to identify an object.- userId
           It is RECOMMENDED that- systemsuserIdType
are able to map whichever local ids (e.g. database key fields), userMasterIdentifier or userIds they use to SourceId.
   givenName:
          type: string
        preferredFirstName:
The sourcedId of an object is considered an addressable property oftype: anstring
entity and as such will not be treated asfamilyName:
Personally Identifiable Information (PII).       type: string
        familyNamePrefix:
        The sourceId attributetype: isstring
based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).   email:
          statustype: string
          description: |'E-mail address hosted by school (e.g. L123456@school.nl).'
      The status fieldphone:
gives an indication to Consumers about the status of an object.type: string
          description: Consumers'Phone cannumber deleteas objectsprovided thatby arethe flaggedschool.'
`tobedeleted`  as such if they wish.  mobile:
          type: Thestring
status attribute is  based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
          type: stringdescription: 'Mobile phone number as provided by the school.'
        organisationRoles:
     enum:     type: array
      - active   description: 'The organisation roles the Employee has within the organisation.'
- tobedeleted         dateCreateditems:
            type: object
 string           descriptionproperties:
'Indicates the date and time the object was first created. Format: Conform openapi in ZULUorganisation:
time zoals gespecificeerd in RFC 3339, section 5.6.'           format: date-time$ref: '#/components/schemas/SchoolReference'
          example: "2017-07-21T17:32:28Z"   organisationRole:
     dateLastModified:           type: string
                description: 'IndicatesThe organisation role the dateEmployee andhas timewithin the objectorganisation.'
was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.' enum:
         format: date-time        - administratief-medewerker
 example: "2022-08-11T15:31:12Z"       required:         - userIdsapplicatiebeheerder
        - schemaVersion         - givenNamebegeleider
        - familyName         - invalkracht
status         - sourceId        - ibp-er
dateCreated         - dateLastModified        - leermiddelencoordinator
EmployeeCommunication:       title: EmployeeCommunication       description: 'Communication data of- theleraar
Employee. For Employees this is the e-mail address, phone number or mobile phone number as provided by the School.'- mentor
     type: object       x-tags:     - onderwijsbestuurder
  - EmployeeCommunication       properties:        - sourceId:onderwijsdirecteur
          type: string       - stagiair
  format: uuid           descriptionbeginDate:
'The Source Identifier of the Employee.'         schemaVersion:  type: string
       $ref: '#/components/schemas/schemaVersion'         emaildescription: 'The start date on which the role becomes active (inclusive). typeFormat: string
  YYYY-MM-DD (according to RFC3339).'
       description: 'E-mail address hosted by school (e.g. L123456@school.nl).'  format: date
     phone:           typeexample: string'2022-07-31'
          description: 'Phone number as providedendDate:
by the school.'         mobile:     type: string
    type: string           description: 'MobileThe phoneend numberdate ason provided bywhich the school.'role becomes inactive     required:
   (exclusive). Format: YYYY-MM-DD (according to RFC3339).'
       - sourceId        format: -date
schemaVersion         - email      EmployeeRolesexample: '2024-08-31'
      title: EmployeeRoles      required:
        description: 'Roles of the Employee within the- school.'organisation
      type: object       x-tags: organisationRoles
       - EmployeeRoles      - properties:beginDate
        sourceId:
          type: string
          format: uuid
          description: 'The|
Source Identifier of the Employee.'        The schemaVersion:Source Identifier of the object. This is a GUID System ID $ref: '#/components/schemas/schemaVersion'
for an object.
       organisationRoles:     This is the GUID that Consumers type:will arrayrefer to when making API calls, or when needing to identify description: 'The organisation roles the Employee has within the organisation.'an object.
            It is RECOMMENDED that systems are items:able to map whichever local ids (e.g. database key fields), userMasterIdentifier or userIds type:they objectuse to SourceId.
          properties:  The sourcedId of an object is considered an addressable property of an entity organisation:and as such will not be treated as Personally Identifiable Information (PII).
     $ref: '#/components/schemas/SchoolReference'      
        organisationRole:    The sourceId attribute is based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
  type: string     status:
           description: 'The|
organisation role the Employee has within the organisation.'     The status field gives an indication to Consumers about the status of enum:an object.
            Consumers can delete objects that -are administratief-medewerkerflagged `tobedeleted`  as such if they wish.

          - applicatiebeheerder The status attribute is based on the [Base Class          - begeleiderfrom OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
          type: string
       - invalkracht  enum:
            - active
  - ibp-er         - tobedeleted
        -dateCreated:
leermiddelencoordinator          type: string
       - leraar  description: 'Indicates the date and time the object was first created. Format: Conform openapi in ZULU time -zoals mentorgespecificeerd in RFC 3339, section 5.6.'
          format: date-time
 - onderwijsbestuurder        example: "2017-07-21T17:32:28Z"
        dateLastModified:
- onderwijsdirecteur         type: string
        - stagiair description: 'Indicates the date and time the object was last modified. Format: Conform openapi beginDate:in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
       type: string  format: date-time
             description: 'The start date on which the role becomes active (inclusive). Format: YYYY-MM-DD (according to RFC3339).'
 example: "2022-08-11T15:31:12Z"
      required:
        - userIds
        - givenName
    format: date   - familyName
        - status
  example: '2022-07-31'     - sourceId
        endDate:- dateCreated
        - dateLastModified

    type:# stringThis UserReference might not be necessary for the Employees API. References are made based on the sourceId description:of 'Thethe endEmployee dateobject.
on which the role becomesUserReference:
inactive (exclusive). Format: YYYY-MM-DD (according to RFC3339).'
 type: object
      title: UserReference
       formatproperties:
date        userMasterIdentifier:
        example: '2024-08-31'
  type: string
          requireddescription: |
            The -primary organisationidentifier for a User.
           - organisationRolesFor Students the ECK iD is used.
        - beginDate   For Employees this value required:is empty. There is no primary identifier for Employees.
- sourceId         - schemaVersion (either userMasterIdentifier or userIds is required)
  - organisationRoles     userIds:
# This UserReference might not be necessary for the Employees API.type: Referencesarray
are made based on the sourceId of the Employee object. description: |
  UserReference:       type: object  A secondary identifier for a title:User. UserReferenceThis value is used whenever the primary properties:identifier is not available.
     userMasterIdentifier:       For Employees this value type:is stringmandatory.
          description: | (either userMasterIdentifier or userIds is required)
      The primary identifier for aitems:
User.            type: Forobject
Employees this value is empty. There is no primary identifier for Employees. properties:
           (either userMasterIdentifier or userIdsuserId:
is required)         userIds:      type: string
   type: array           descriptionuserIdType:
|             A secundary identifier fortype: astring
User. This value is used whenever the primary identifier is not available.     enum:
       For Employees this value is mandatory.      - NEPPI # nlPersonProfileId – value can (eitherbe userMasterIdentifierused orfor userIdsstudents isand required)employees
          items:        - BPI # Basispoort ID type:– objectvalue can be used for students and employees
     properties:             - eduID userId:# eduID identifier – value can be used for students and employees
     type:    string         - NEPRI # nlPersonRealId – value userIdType:can be used for students only
           type: string      - ASI # Las-key – value can be used for students enum:only
                  - nlPersonProfileIdeckId # ECK iD – value can be used for employees only, eckId is userIdType for userMasterIdentifier for students
- nlPersonRealId           required:
       - Las-key      - userId
           - BasispoortId  - userIdType
      required:
        - MedewerkernummeruserIds
    
    SchoolReference:
  required:    type: object
      title: SchoolReference
 - userId    description: 'A reference to a School organisation.'
    - userIdType properties:
        SchoolReferenceorganisationMasterIdentifier:
      type: object       title: SchoolReference
      description: 'A reference to a School organisation'
      properties:
        organisationMasterIdentifier:
          type: string
          description: |
            The primary identifier for a School. For Schools the `Onderwijsaanbiedercode``OnderwijsaanbiederId` is used.
            (either organisationMasterIdentifier or organisationIds is required)
          example: '104A158' # De Mariënborn
        organisationIds:
          type: array
          description: |
            A secundarysecondary identifier for the School. This value is used whenever the primary identifier is not available.
            (either organisationMasterIdentifier or organisationIds is required)
          items:
            type: object
            properties:
              organisationId:
                type: string
              organisationIdType:
                type: string
                enum:
                  - InstellingserkenningOIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - VestigingserkenningBP_ID # e.g. 09QQ00 (Marienbornschool) Basispoort gegenereerde identifier voor de school.
                  - BasispoortIdDD_ID # Door Basispoort de Centrale Registratie van Edu-iX gegenereerde identifierDigiDeliveryId voorvan de school.
                  - DigiDeliveryIdAS_ID # Door de Centrale Registratie van Edu-iX gegenereerde identifier van de school.
                  - LAS-key # Door het Leerlingadministratiesysteem gegenereerde identifier van de school.
            required:
              - organisationId
              - organisationIdType

    StatusResponse:
      title: StatusResponse
      type: object
      description: 'Functional status code and status message.'
      properties:
        status:
          type: integer
          description: 'See functional status codes within the Documentation.'
        statusMessage:
          type: string
          description: 'See functional status messages within the Documentation.'
      required:
        - status
  
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
          refreshUrl: https://api.example.com/oauth2/token
          scopes:
            eduv.employee.basic: 'a scope that gives access to employee identifersidentifiers and name.'
            eduv.employee.communication: 'a scope that gives access to employee communication attributes.'
            eduv.employee.roles: 'a scope that gives access to employee organisation roles attributes.'
            
paths:
  
  /employees/:
    parameterspost:
      -summary: schema:Search Employee
      x-tags:
  type: string     - Employee
  name: edu_org_id   tags:
     in: query  - Administratiesysteem onderwijsmedewerker
    required: true operationId: search-employee
      description: |'Request an Employee object for a specified Employee at a School.'
All data from the Employees API requiresrequestBody:
a consent from the School.    content:
      The `edu_org_id` parameter is mandatoryapplication/json:
to request information from the `Administratiesysteem onderwijsmedewerker`.      schema:
    This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.type: object
             - schemaproperties:
          type: string         nameschool:
sourceId         in: query         required$ref: true'#/components/schemas/SchoolReference'
        description: 'Reference to the sourceId of the Employee object.'employee:
      - schema:           type$ref: string'#/components/schemas/UserReference'
         name: schemaVersion    required:
    in: query         required: false - school
      description: 'Optional parameter to request a response in a specific schema- version.employee
If none supplied, the server will chooseresponses:
its default schema version.'     get'200':
      summary: 'Get Employee'  description: OK
   x-tags:       content:
 - Employee       tags:   application/json:
     - Administratiesysteem onderwijsmedewerker       operationIdschema:
get-employee       description: |        type: Requestarray
an Employee object based on its sourceId.         The Sourceitems:
Identifier is the GUID System ID for an object. This is the GUID that Consumers will refer to when making API calls.
        The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
      responses:
        '200$ref: '#/components/schemas/Employee'
        '400':
          description: OKBad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeStatusResponse'
        '400401':
          description: BadUnauthorized
Request           content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401403':
          description: UnauthorizedForbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403404':
          description: Not ForbiddenFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - '404'OAuth2:
          description:  Not Found- eduv.employee.basic
          content:  - eduv.employee.communication
         application/json:   - eduv.employee.roles

  /employees/{sourceId}:
    parameters:
 schema:     - schema:
          $reftype: '#/components/schemas/StatusResponse' string
        securityname: sourceId
       - OAuth2in: path
        required: true
   - employee.basic    /employees/school/description: 'Reference to the sourceId of the Employee parameters:object.'
      - schema:
          type: string
        name: edu_org_idorgMasterId
        in: query
        required: truefalse
        description: |
          AllThe dataorganisationMasterIdentifier fromof the Employeesschool.
API requires a consent from the School.    This parameter is used when the primary The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
  This allows the `Administratiesysteem onderwijsmedewerker` to check if thetype: requestingstring
client has an active data exchange (consent) for thename: specified edu_org_id.orgId
       - schemain: query
         $refrequired: '#/components/schemas/SchoolReference'false
        namedescription: school|
          The in:organisationIdentifier query(secondary identifier) of the school.
    required: true     This parameter is used description:in 'Referencecombination towith the primaryorgIdType orwhen secundarythe identifierorganisationMasterIdentifier ofis anot schoolavailable.'
      - schema:
          type: integerstring
        name: start example: DD_ID
      in: query   enum:
     description: 'Start point for pagination of results, defaults- to 0,'OIE_CODE
         examples:   - BP_ID
      default:      - DD_ID
     value: 0      - AS_ID
     summary: The start pointname: fororgIdType
pagination       - schemain: query
         typerequired: integerfalse
        description: |
maximum: 100         name:The limittype of the organisationIdentifier.
     in: query    This parameter is used in description:combination 'Limitwith ofthe numberorgId ofwhen resultsthe returnedorganisationMasterIdentifier byis page,not defaultsavailable.
to 20 with max 100.'get:
      summary: 'Get examples:Employee'
      x-tags:
   default:     - Employee
      valuetags:
20        - Administratiesysteem onderwijsmedewerker
  summary: The default value if none is providedoperationId: get-employee
      description: |
    max:    Request an Employee object based on its sourceId.
 value: 100      The Source Identifier is the GUID System summary:ID Thefor largestan recommendedobject. pageThis sizeis the GUID that Consumers will refer -to schema:when making API calls.
       type: stringThe sourcedId of an object is considered an addressable property of format: date-time
        in: query
 an entity and as such will not be treated as Personally Identifiable Information (PII).
      nameresponses:
since        '200':
required: false         description: OK
 'Request  all objects modified after the specified timestamp. Formatcontent:
 Conform openapi in ZULU time as specified in RFC 3339, section 5.6' application/json:
        example: "2017-07-21T17:32:28Z"
       schema:
    - schema:           type$ref: string'#/components/schemas/Employee'
        name'400':
 schemaVersion         indescription: queryBad Request
       required: false  content:
      description: 'Optional parameter to request a responseapplication/json:
in a specific schema version. If none supplied, the server will choose its default schema:
version.'     get:       summary: Get Employees for School
$ref: '#/components/schemas/StatusResponse'
     x-tags:   '401':
     - Employee    description: Unauthorized
 tags:         -content:
Administratiesysteem onderwijsmedewerker       operationId: get-employees-for-school       descriptionapplication/json:
'Request all Employee objects including basic information (identifiers and names) for a specified school.'       responsesschema:
        '200':           description$ref: OK'#/components/schemas/StatusResponse'
          content'403':
            application/jsondescription: Forbidden
             schemacontent:
                typeapplication/json:
array                 itemsschema:

                 $ref: '#/components/schemas/EmployeeStatusResponse'
        '400404':
          description: BadNot RequestFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401'security:
        -  descriptionOAuth2:
Unauthorized           content: - eduv.employee.basic
          application/json:  - eduv.employee.communication
           schema: - eduv.employee.roles
  
  /employees/school:
        $refparameters:
'#/components/schemas/StatusResponse'      -   '403'schema:
          descriptiontype: Forbiddenstring
        name: orgMasterId
content:        in: query
   application/json:     required: false
        schemadescription: |
          The organisationMasterIdentifier of the school.
$ref: '#/components/schemas/StatusResponse'         '404':This parameter is used when the primary identifier for a school description:(being Notthe Found`OnderwijsaanbiederId`) is available.
      - schema:
 content:         type: string
  application/json:      name: orgId
        schemain: query
        required: false
      $ref: '#/components/schemas/StatusResponse'  description: |
        security:  The organisationIdentifier (secondary identifier) of the school.
- OAuth2:         This parameter is used -in employee.basiccombination with the  /employees/communication/:
    parameters:orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
        name  example: edu_org_idDD_ID
          inenum:
query         required: true  - OIE_CODE
     description: |      - BP_ID
   All data from the Employees API requires a  consent- fromDD_ID
the School.           The- `eduAS_org_id`ID
parameter is mandatory to request information from the `Administratiesysteemname: onderwijsmedewerker`.orgIdType
        in: query
This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.
required: false
        description: |
     - schema:    The type of the organisationIdentifier.
  type: string       This parameter name:is sourceIdused in combination with the orgId when the organisationMasterIdentifier in:is querynot available.
      - requiredschema:
true          descriptiontype: 'Referencestring
to the sourceId of the Employee object.'    format:   - schema:date-time
          typein: stringquery
        name: schemaVersionsince
        inrequired: queryfalse
        requireddescription: false'Request all objects modified after the specified timestamp. Format: description:Conform 'Optionalopenapi parameterin toZULU requesttime aas responsespecified in aRFC specific3339, schemasection version5.6'
If none supplied, the server will choose its default schema version.'example: "2017-07-21T17:32:28Z"
     get:
      summary: 'Get Employees Employeefor Communication'School
      x-tags:
        - EmployeeCommunicationEmployee
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employeeemployees-for-communicationschool
      description: |'Request all Employee objects including basic information (identifiers and Requestnames) thefor communicationa attributesspecified ofschool.'
Employee object based on its sourceId. responses:
       The Source'200':
Identifier is the GUID System ID for an object. This isdescription: theOK
GUID that Consumers will refer to when making API calls. content:
       The sourcedId of an object isapplication/json:
considered an addressable property of an entity and as such will not be treated asschema:
Personally Identifiable Information (PII).       responses:      type: array
 '200':           description: OK   items:
       content:             application/json:
              schema:
                $ref: '$ref: '#/components/schemas/EmployeeCommunicationEmployee'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.employee.communication

  /employees/communication/school/:basic
     parameters:       - schema:eduv.employee.communication
          type: string - eduv.employee.roles

x-tags:
   - name: edu_org_idEmployee
        in- name: queryEmployeeCommunication
        required: true
        description: |
          All data from the Employees API requires a consent from the School.
          The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.
          This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.
      - schema:
          $ref: '#/components/schemas/SchoolReference'
        name: school
        in: query
        required: true
        description: 'Reference to the primary or secundary identifier of a school.'
      - schema:
          type: integer
        name: start
        in: query
        description: 'Start point for pagination of results, defaults to 0,'
        examples:
          default:
            value: 0
            summary: The start point for pagination
      - schema:
          type: integer
          maximum: 100
        name: limit
        in: query
        description: 'Limit of number of results returned by page, defaults to 20 with max 100.'
        examples:
          default:
            value: 20
            summary: The default value if none is provided
          max:
            value: 100
            summary: The largest recommended page size
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
      - schema:
          type: string
        name: schemaVersion
        in: query
        required: false
        description: 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.'
    get:
      summary: Get Employees Communication for School
      x-tags:
        - EmployeeCommunication
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employees-communication-for-school
      description: 'Request communication attributes for all Employee objects for a specified school.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeCommunication'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.communication

  /employees/roles/:
    parameters:
      - schema:
          type: string
        name: edu_org_id
        in: query
        required: true
        description: |
          All data from the Employees API requires a consent from the School.
          The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.
          This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.
      - schema:
          type: string
        name: sourceId
        in: query
        required: true
        description: 'Reference to the sourceId of the Employee object.'
      - schema:
          $ref: '#/components/schemas/SchoolReference'
        name: school
        in: query
        required: false
        description: 'Optional filter to request the organsiation roles of the Employee at the specified school. Reference to the primary or secundary identifier of a school.'
      - schema:
          type: string
        name: schemaVersion
        in: query
        required: false
        description: 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.'
    get:
      summary: 'Get Employee Roles'
      x-tags:
        - EmployeeRoles
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employee-roles
      description: |
        Request the organiation roles attributes of Employee object based on its sourceId.
        The Source Identifier is the GUID System ID for an object. This is the GUID that Consumers will refer to when making API calls.
        The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeRoles'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.roles

  /employees/roles/school/:
    parameters:
      - schema:
          type: string
        name: edu_org_id
        in: query
        required: true
        description: |
          All data from the Employees API requires a consent from the School.
          The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.
          This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.
      - schema:
          $ref: '#/components/schemas/SchoolReference'
        name: school
        in: query
        required: true
        description: 'Reference to the primary or secundary identifier of a school.'
      - schema:
          type: integer
        name: start
        in: query
        description: 'Start point for pagination of results, defaults to 0,'
        examples:
          default:
            value: 0
            summary: The start point for pagination
      - schema:
          type: integer
          maximum: 100
        name: limit
        in: query
        description: 'Limit of number of results returned by page, defaults to 20 with max 100.'
        examples:
          default:
            value: 20
            summary: The default value if none is provided
          max:
            value: 100
            summary: The largest recommended page size
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
      - schema:
          type: string
        name: schemaVersion
        in: query
        required: false
        description: 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.'
    get:
      summary: Get Employees Roles for School
      x-tags:
        - EmployeeRoles
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employees-roles-for-school
      description: 'Request organisation roles attributes for all Employee objects for a specified school.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeRoles'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.roles

x-tags:
  - name: Employee
  - name: EmployeeCommunication
  - name: EmployeeRoles

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

...

- name: EmployeeRoles

...

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.

Versions Compared

Old Version 9

New Version Current

Key

Anchor

employee

employee

Object: Employee (Onderwijsmedewerker)

Anchor
employee-communication
employee-communication

Attributen : EmployeeCommunication

Anchor
employee-roles
employee-roles

Attributen: EmployeeRoles

Anchor
organisation-roles
organisation-roles
Object:

OrganisationRoles

Status- en foutcodes

Technisch: API specificatie

Release notes

Release notes

Page Comparison

Versions Compared

Old Version 9

New Version Current

Key

Anchor

employee

employee

Object: Employee (Onderwijsmedewerker)

Anchoremployee-communicationemployee-communication

Attributen : EmployeeCommunication

Anchoremployee-rolesemployee-roles

Attributen: EmployeeRoles

Anchororganisation-rolesorganisation-rolesObject:

OrganisationRoles

Status- en foutcodes

Technisch: API specificatie

Release notes

Release notes

Anchor
employee-communication
employee-communication

Anchor
employee-roles
employee-roles

Anchor
organisation-roles
organisation-roles
Object: