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

schemaVersion: 0.09.31

Datum

18 April 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 onderwijsdeelnemerde 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 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.
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		VO
sourceId	string	uuidstring	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

Anchor
employee-communication
employee-communication

...

Attributen : EmployeeCommunication

Het object De attributen EmployeeCommunication bevat bevatten het mailadres en de telefoonnummers van de onderwijsmedewerker bij de onderwijsaanbieder. Dit object is 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

sourceIdemail

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

Het e-string

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

employee@school.nl

VO

phone

string

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

010-1234567

O

mobile

string

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

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

organisationRoles

array

organisationRoleOrganisationRole

Een lijst met organisatierollen die de onderwijsmedewerker vervult bij onderwijsaanbieders.

VO

Anchor
organisation-roles
organisation-roles
Object:

...

OrganisationRoles

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

...

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.31'
  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 API using semantic versioning 2.0.0.
        The API version number is communicated in the header.
        The major version is communicated in the URI.
        For more information see the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      default: 0.09.31
          
    Employee:
      title: Employee
      description: ' |
        The Employee object with its identifiers and name information.'

     type: object  Based on the scopes additional x-tags:attributes can be included in this object.

 - Employee       properties:### employee.communication
         userMasterIdentifier:
          type: string
      Communication data of the Employee. For Employees this is the `e-mail` address, `phone` number or `mobile` phone number as provided by the School.

  description: |     ### employee.roles
      The primary identifier`organisationRoles` forof the Employee. within the school.
      type: object
  For Employees this value is empty. There is no primary identifier for Employees.
 x-tags:
        - Employee
      userIdsproperties:
          typeuserMasterIdentifier:
array           descriptiontype: |string
          description: |
 A secundary identifier for a User. This value is used whenever theThe primary identifier isfor notthe availableEmployee.
            For Employees this value is mandatoryempty. There is no primary identifier for Employees.
     (either userMasterIdentifier or userIds:
is required)           itemstype: array
           typedescription: object|
            properties:A secondary identifier for a User. This value is used whenever the primary identifier is userId:not available.
            For Employees this type:value stringis mandatory.
            (either userIdType:userMasterIdentifier or userIds is required)
          items:
 type: string          type: object
     enum:       properties:
           - NEPPI # nlPersonProfileIduserId:
– value can be used for students and employees        type: string
         - BPI # Basispoort ID –userIdType:
value can be used for students and employees         type: string
                enum:
                  - eduIDNEPPI # eduID identifiernlPersonProfileId – value can be used for students and employees
                  - eckIdBPI # ECKBasispoort iDID – value can be used for students and employees
only, eckId is userIdType for userMasterIdentifier for students           - eduID required:# eduID identifier – value can be used for students and employees
   - userId              - -eckId userIdType# ECK iD – value can be used for givenName:employees only, eckId is userIdType for userMasterIdentifier for students
  type: string         familyNamerequired:
          type: string    - userId
   familyNamePrefix:           type:- stringuserIdType
        sourcedIdgivenName:
          type: string
        preferredFirstName:
 format:  uuid           descriptiontype: |string
          familyName:
 The Source Identifier of the object. This is a GUIDtype: Systemstring
ID for an object.     familyNamePrefix:
       This is the GUIDtype: thatstring
Consumers will refer to when making API calls, or when needing to identify an object. email:
          type: string
    It is RECOMMENDED that systems are able to map whichever local idsdescription: 'E-mail address hosted by school (e.g. database key fields), userMasterIdentifier or userIds they use to SourceId.L123456@school.nl).'
        phone:
          type: string
The sourcedId of an object is considered an addressable property ofdescription: an'Phone entitynumber andas asprovided suchby willthe notschool.'
be treated as Personally Identifiable Information (PII).  mobile:
          type: string
          description: The'Mobile sourceIdphone attributenumber isas basedprovided onby the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).school.'
        statusorganisationRoles:
          descriptiontype: |array
          description:  'The statusorganisation fieldroles givesthe anEmployee indication to Consumers abouthas within the statusorganisation.'
of an object.        items:
    Consumers can delete objects that are flagged `tobedeleted` type: asobject
such if they wish.         properties:
    The 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).organisation:
          type: string     $ref: '#/components/schemas/SchoolReference'
    enum:          organisationRole:
  - active             -type: tobedeletedstring
        dateCreated:        description: 'The organisation type:role stringthe Employee has within the organisation.'
     description: 'Indicates the date and time the object was first created. Formatenum:
 Conform   openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'    - administratief-medewerker
     format: date-time           example: "2017-07-21T17:32:28Z" applicatiebeheerder
       dateLastModified:           type:- stringbegeleider
          description: 'Indicates the date and time the object was- lastinvalkracht
modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'     - ibp-er
    format: date-time           example: "2022-08-11T15:31:12Z" - leermiddelencoordinator
         required:         - userIdsleraar
        - givenName         - familyNamementor
        - status         - sourceIdonderwijsbestuurder
        - dateCreated         - onderwijsdirecteur
dateLastModified          EmployeeCommunication:       title: EmployeeCommunication- stagiair
     description: 'Communication data of the Employee. For Employees this isbeginDate:
the e-mail address, phone number or mobile phone number as provided by the School.'   type: string
  type: object       x-tags:      description: 'The start -date EmployeeCommunicationon which the role becomes active (inclusive). propertiesFormat: YYYY-MM-DD (according to RFC3339).'
    sourceId:           type: string format: date
           format: uuid    example: '2022-07-31'
     description: 'The Source Identifier of the Employee.'   endDate:
     email:           type: string
                description: 'E-mail address hosted by school (e.g. L123456@school.nlThe end date on which the role becomes inactive (exclusive). Format: YYYY-MM-DD (according to RFC3339).'
        phone:        format: date
    type: string           descriptionexample: 'Phone number as provided by the school.'2024-08-31'
            required:
  mobile:           type: string- organisation
         description:  'Mobile phone number as- providedorganisationRoles
by the school.'       required:     - beginDate
  - sourceId     sourceId:
   - email      EmployeeRolestype: string
     title: EmployeeRoles    format: uuid
 description: 'Roles of the Employee within the school.'  description: |
   type: object       x-tags: The Source Identifier of the object. This is -a EmployeeRolesGUID System ID for an object.
 properties:         sourceId:  This is the GUID that Consumers will refer to type:when stringmaking API calls, or when needing to identify an object.
 format: uuid          It description:is 'TheRECOMMENDED Sourcethat Identifiersystems ofare theable Employee.'to map whichever local ids (e.g. database key fields), organisationRoles:userMasterIdentifier or userIds they use       type: arrayto SourceId.
            description: 'The organisationsourcedId rolesof thean Employeeobject hasis withinconsidered thean organisation.'addressable property of an entity and as such will not be items:treated as Personally Identifiable Information (PII).
       type: object    
        properties:    The sourceId attribute is based on the [Base Class   organisation:
                $ref: '#/components/schemas/SchoolReference'from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
              organisationRolestatus:
          description: |
    type: string       The status field gives an indication to Consumers   description: 'The organisation role about the Employeestatus hasof withinan the organisationobject.'
            Consumers can delete objects enum:that are flagged `tobedeleted`  as such if they wish.

        - administratief-medewerker   The 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).
   - applicatiebeheerder      type: string
          enum:
- begeleider           - active
      - invalkracht     - tobedeleted
        dateCreated:
   - ibp-er      type: string
          description: -'Indicates leermiddelencoordinatorthe date and time the object was first created. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC -3339, leraarsection 5.6.'
          format: date-time
     - mentor    example: "2017-07-21T17:32:28Z"
        dateLastModified:
    - onderwijsbestuurder     type: string
          description: 'Indicates -the onderwijsdirecteurdate and time the object was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, - stagiairsection 5.6.'
          format: date-time
  beginDate:        example: "2022-08-11T15:31:12Z"
       typerequired:
string        - userIds
       description: 'The start date on which the role becomes active (inclusive). Format: YYYY-MM-DD (according to RFC3339).'- givenName
        - familyName
        - status
        - format:sourceId
date        - dateCreated
       example: '2022-07-31' dateLastModified

    # This UserReference might not be necessary for the endDate:Employees API. References are made based on the sourceId of the Employee object.
    typeUserReference:
string      type: object
         descriptiontitle: 'The end date on which the role becomes inactive (exclusive). Format: YYYY-MM-DD (according to RFC3339).'UserReference
      properties:
        userMasterIdentifier:
          formattype: datestring
          description: |
    example: '2024-08-31'       The primary identifier for a User.
required:            For Students the -ECK organisationiD is used.
            -For organisationRolesEmployees this value is empty. There is no primary identifier for Employees.
   - beginDate       required: (either userMasterIdentifier or userIds is required)
  - sourceId     userIds:
   - organisationRoles      #type: Thisarray
UserReference might not be necessary for the Employees API. References aredescription: made|
based on the sourceId of the Employee object.     UserReference:A secondary identifier for a User. This type:value objectis used whenever the primary identifier is title:not UserReferenceavailable.
      properties:      For Employees this userMasterIdentifier:value is mandatory.
        type: string   (either userMasterIdentifier or userIds is required)
  description: |       items:
     The primary identifier for a User.  type: object
         For Students the ECKproperties:
iD is used.            userId:
For Employees this value is empty. There is no primary identifier for Employees.     type: string
      (either userMasterIdentifier or userIds is required)   userIdType:
     userIds:           type: arraystring
          description: |     enum:
       A secundary identifier for a User. This value is used whenever the- primaryNEPPI identifier# isnlPersonProfileId not– available.value can be used for students and employees
     For Employees this value is mandatory.        - BPI # Basispoort ID (either– userMasterIdentifiervalue orcan userIdsbe isused required)for students and employees
       items:           - eduID type:# objecteduID identifier – value can be used for students and employees
  properties:               userId: - NEPRI # nlPersonRealId – value can be used for students only
    type: string             - ASI userIdType:# Las-key – value can be used for students only
       type: string          - eckId # ECK iD – value enum:can be used for employees only, eckId is userIdType for userMasterIdentifier for students
      - NEPPI # nlPersonProfileId – value canrequired:
be used for students and employees         - userId
        - BPI # Basispoort ID – value- canuserIdType
be used for students and employees required:
        - userIds
    
  - eduID #SchoolReference:
eduID identifier – value can be usedtype: forobject
students and employees    title: SchoolReference
      description: 'A reference to a School organisation.'
- NEPRI # nlPersonRealId – value canproperties:
be used for students only    organisationMasterIdentifier:
          type: string
  - ASI # Las-key – value can be useddescription: for|
students only           The primary identifier for a School. For Schools -the eckId`OnderwijsaanbiederId` #is ECKused.
iD – value can be used for employees only, eckId is userIdType for(either userMasterIdentifierorganisationMasterIdentifier foror studentsorganisationIds is required)
          requiredexample: '104A158' # De Mariënborn
        organisationIds:
 - userId        type: array
     - userIdType    description: |
    SchoolReference:       type: objectA secondary identifier for the School. This title:value SchoolReferenceis used whenever the primary identifier is description: 'A reference to a School organisation.'not available.
         properties:   (either organisationMasterIdentifier or organisationIds is required)
organisationMasterIdentifier:          items:
type: string           descriptiontype: |object
            Theproperties:
 primary identifier for a School. For Schools the `OnderwijsaanbiederId` is used.   organisationId:
         (either organisationMasterIdentifier or organisationIds is required)  type: string
       example: '104A158' # De Mariënborn   organisationIdType:
     organisationIds:           type: arraystring
          description: |     enum:
       A secundary identifier for the School. This value is used whenever the- primaryOIE_CODE identifier# is not availableOnderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
          (either organisationMasterIdentifier or organisationIds is required)   - BP_ID # Basispoort gegenereerde identifier voor de items:school.
            type: object     - DD_ID # Door de Centrale Registratie van properties:Edu-iX gegenereerde DigiDeliveryId van de school.
         organisationId:         - AS_ID # Door het Leerlingadministratiesysteem gegenereerde identifier type:van stringde school.
             organisationIdTyperequired:
              - organisationId
type: string             - organisationIdType

 enum:   StatusResponse:
      title: StatusResponse
      type: -object
OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool) description: 'Functional status code and status message.'
      properties:
     - VE_CODE # Vestigingserkenningcode e.g. 09QQ00 (Marienbornschool)status:
          type: integer
         - BP_ID # Basispoort gegenereerde identifier voor de school.description: 'See functional status codes within the Documentation.'
        statusMessage:
         - DD_ID # Door de Centrale Registratie van Edu-iX gegenereerde DigiDeliveryId van de school.
      type: string
          description: 'See functional status messages within the Documentation.'
      required:
    - AS_ID # Door het- Leerlingadministratiesysteemstatus
gegenereerde identifier van
de school. securitySchemes:
    OAuth2:
      requiredtype: oauth2
      flows:
      - organisationId clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
    - organisationIdType     refreshUrl: StatusResponse:https://api.example.com/oauth2/token
      title: StatusResponse   scopes:
   type:  object       descriptioneduv.employee.basic: 'Functionala scope statusthat codegives andaccess statusto message.'employee identifiers and name.'
   properties:         statuseduv.employee.communication: 'a scope that gives access to employee communication  attributes.'
type: integer           descriptioneduv.employee.roles: 'See functional status codes within the Documentationa scope that gives access to employee organisation roles attributes.'
        statusMessage    
paths:
  
  /employees:
    typepost:
    string  summary: Search Employee
      descriptionx-tags:
  'See  functional status messages within the- Documentation.'Employee
      requiredtags:
        - Administratiesysteem onderwijsmedewerker
status      securitySchemesoperationId: search-employee
    OAuth2:
      type: oauth2  description: 'Request an Employee object for a specified Employee at a School.'
      flowsrequestBody:
        clientCredentialscontent:
          tokenUrlapplication/json: https://api.example.com/oauth2/token
            refreshUrlschema: https://api.example.com/oauth2/token
              scopestype: object
           employee.basic   properties:
'a scope that gives access to employee identifers and name.'        school:
    employee.communication: 'a scope that gives access to employee communication attributes.'     $ref: '#/components/schemas/SchoolReference'
      employee.roles: 'a scope that gives access to employee organisation roles attributes.'employee:
             paths:     $ref: '#/components/employees/:schemas/UserReference'
      parameters:       - schemarequired:
            type: string   - school
    name: sourceId         in: query - employee
      requiredresponses:
true         description'200':
'Reference to the sourceId of the Employee object.'   description: OK
  - schema:       content:
   type: string         nameapplication/json:
orgMasterId         in: query    schema:
    required: false         description: | type: array
        The organisationMasterIdentifier of the school.    items:
      This parameter is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`) is available.$ref: '#/components/schemas/Employee'
        - schema'400':
          typedescription: stringBad Request
       name: orgId     content:
   in: query         requiredapplication/json:
false         description: |     schema:
     The organisationIdentifier (secundary identifier) of the school.       $ref: '#/components/schemas/StatusResponse'
   This parameter is used in combination'401':
with the orgIdType when the organisationMasterIdentifier is not available.  description: Unauthorized
   - schema:      content:
    type: string       application/json:
   example: DD_ID           enumschema:
            - OIE_CODE   $ref: '#/components/schemas/StatusResponse'
        - VE_CODE'403':
          description: Forbidden
 - BP_ID        content:
    - DD_ID        application/json:
    - AS_ID         nameschema:
orgIdType         in: query      $ref: '#/components/schemas/StatusResponse'
 required: false      '404':
  description:   |     description: Not Found
   The  type of the organisationIdentifier.  content:
        This parameter is used inapplication/json:
combination with the orgId when the organisationMasterIdentifier is not available.     getschema:
       summary: 'Get Employee'       x-tags:$ref: '#/components/schemas/StatusResponse'
      security:
 - Employee      - tagsOAuth2:
        - Administratiesysteem onderwijsmedewerker  - eduv.employee.basic
   operationId: get-employee       description: |- eduv.employee.communication
       Request an Employee object based on its sourceId.- eduv.employee.roles

  /employees/{sourceId}:
    Theparameters:
Source Identifier is the GUID System ID for an object. This is the GUID that Consumers will refer to when making API calls.
    - schema:
          type: string
        name: sourceId
    The sourcedId of an objectin: ispath
considered an addressable property of an entity and asrequired: suchtrue
will not be treated as Personally Identifiable Information (PII).
      responses:
 description: 'Reference to the sourceId of the Employee object.'
      - '200'schema:
          descriptiontype: OKstring
        name: orgMasterId
content:        in: query
   application/json:     required: false
        schemadescription: |
          The organisationMasterIdentifier of the  $ref: '#/components/schemas/Employee'school.
          This parameter is '400':used when the primary identifier for a school (being the `OnderwijsaanbiederId`) description:is Badavailable.
Request      - schema:
   content:       type: string
    application/json:     name: orgId
        schemain: query
        required: false
     $ref: '#/components/schemas/StatusResponse'   description: |
    '401':      The organisationIdentifier (secondary identifier) of description:the Unauthorizedschool.
          content:This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is application/json:
not available.
      - schema:
     schema:     type: string
          $refexample: '#/components/schemas/StatusResponse'DD_ID
        '403':  enum:
        description: Forbidden   - OIE_CODE
      content:      - BP_ID
     application/json:       - DD_ID
      schema:      - AS_ID
         $refname: '#/components/schemas/StatusResponse'orgIdType
        '404'in: query
         descriptionrequired: Notfalse
Found        description: |
 content:         The type of  application/json:the organisationIdentifier.
          This parameter is used schema:in combination with the orgId when the organisationMasterIdentifier is not available.
      $refget:
'#/components/schemas/StatusResponse'       securitysummary: 'Get Employee'
      x- OAuth2tags:
        - Employee
  -  employee.basic  tags:
 /employees/school/:     parameters:  - Administratiesysteem onderwijsmedewerker
  - schema:   operationId: get-employee
      typedescription: string|
        name:Request orgMasterIdan Employee object based on its sourceId.
  in: query     The Source Identifier is required:the falseGUID System ID for an object. This is the description:GUID |that Consumers will refer to when making API calls.
  The organisationMasterIdentifier of the school.  The sourcedId of an object is considered an addressable Thisproperty parameterof isan usedentity whenand theas primairysuch identifierwill fornot abe schooltreated (beingas thePersonally `OnderwijsaanbiederId`)Identifiable isInformation available(PII).
      - schemaresponses:
        '200':
 type: string         namedescription: orgIdOK
        in: query content:
       required: false    application/json:
    description: |         schema:
 The organisationIdentifier (secundary identifier) of the school.         $ref:  This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.'#/components/schemas/Employee'
        '400':
          description: -Bad schema:Request
          typecontent:
 string           exampleapplication/json:
DD_ID           enum:   schema:
         - OIE_CODE      $ref: '#/components/schemas/StatusResponse'
     - VE_CODE  '401':
          - BP_IDdescription: Unauthorized
          content:
 - DD_ID          application/json:
  - AS_ID         name: orgIdType schema:
       in: query         required$ref: false'#/components/schemas/StatusResponse'
        description'403':
  |        description: Forbidden
 The type of the organisationIdentifier.     content:
     This parameter is used in combination with theapplication/json:
orgId when the organisationMasterIdentifier is not available.       - schema:
          type: integer      $ref: '#/components/schemas/StatusResponse'
        name'404':
start         in description: queryNot Found
       description: 'Start point forcontent:
pagination of results, defaults to 0,'       application/json:
 examples:           default:  schema:
          value: 0     $ref: '#/components/schemas/StatusResponse'
      summarysecurity:
The start point for pagination
      - schemaOAuth2:
          type: integer - eduv.employee.basic
        maximum: 100   - eduv.employee.communication
    name: limit       - eduv.employee.roles
in: query 
  /employees/school:
    descriptionparameters:
'Limit of number of results returned by- page,schema:
defaults to 20 with max 100.'     type: string
  examples:           defaultname: orgMasterId
           valuein: 20query
        required: false
  summary: The default value if none isdescription: provided|
          max:The organisationMasterIdentifier of the school.
        value: 100 This parameter is used when the primary identifier for a school (being summary:the The`OnderwijsaanbiederId`) largestis recommendedavailable.
page size
      - schema:
          type: string
          formatname: date-timeorgId
        in: query
        namerequired: sincefalse
        requireddescription: |
false         description: 'RequestThe allorganisationIdentifier objects(secondary modifiedidentifier) afterof the specified timestampschool.
Format: Conform openapi in ZULU time as specified in RFC 3339,This section 5.6'
        example: "2017-07-21T17:32:28Z"
    get:parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      -   summaryschema:
Get Employees for School       x-tagstype: string
       - Employee  example: DD_ID
   tags:       enum:
  - Administratiesysteem onderwijsmedewerker       operationId: get-employees-for-school
 OIE_CODE
     description: 'Request all Employee objects including basic information (identifiers and names) for a specified school.'- BP_ID
            responses:- DD_ID
       '200':     - AS_ID
    description: OK   name: orgIdType
        contentin: query
        required: false
 application/json:       description: |
      schema:    The type of the organisationIdentifier.
        type: array This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
 items:     - schema:
          type: string
$ref: '#/components/schemas/Employee'         '400'format: date-time
        in: description:query
Bad Request       name: since
  content:      required: false
     application/json:   description: 'Request all objects modified after the specified timestamp. Format: Conform openapi schema:in ZULU time as specified in RFC 3339, section 5.6'
       $ref: '#/components/schemas/StatusResponse'
  example: "2017-07-21T17:32:28Z"
    get:
      '401'summary: Get Employees for School
      description: Unauthorizedx-tags:
        - Employee
      contenttags:
        - Administratiesysteem onderwijsmedewerker
 application/json:     operationId: get-employees-for-school
      description: 'Request all Employee schema:objects including basic information (identifiers and names) for a specified school.'
      $refresponses:
'#/components/schemas/StatusResponse'         '403200':
          description: ForbiddenOK
          content:
            application/json:
              schema:
                $reftype: '#/components/schemas/StatusResponse' array
         '404       items:
                  $ref: '#/components/schemas/Employee'
        '400':
          description: NotBad FoundRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:  '401':
      - OAuth2:   description: Unauthorized
        - employee.basic

  /employees/communication/ content:
    parameters:       - schemaapplication/json:
          type:  string  schema:
      name: sourceId         in$ref: query'#/components/schemas/StatusResponse'
        required'403':
true          description: 'ReferenceForbidden
to the sourceId of the Employee object.'    content:
  - schema:         application/json:
 type: string         name: orgMasterId  schema:
      in: query         required$ref: false'#/components/schemas/StatusResponse'
        description'404':
|          description: Not Found
The organisationMasterIdentifier of the school.      content:
    This parameter is used when the primairy identifier forapplication/json:
a school (being the `OnderwijsaanbiederId`) is available.       - schema:
          type: string     $ref: '#/components/schemas/StatusResponse'
  name: orgId   security:
     in: query  - OAuth2:
     required: false      - eduv.employee.basic
 description: |           The organisationIdentifier (secundary identifier) of the school.- eduv.employee.communication
          This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          example: DD_ID
          enum:
            - OIE_CODE
            - VE_CODE
            - BP_ID
            - DD_ID
            - AS_ID
        name: orgIdType
        in: query
        required: false
        description: |
          The type of the organisationIdentifier.
          This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
    get:
      summary: 'Get Employee Communication'
      x-tags:
        - EmployeeCommunication
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employee-communication
      description: |
        Request the communication 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/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/communication/school/:
    parameters:
      - schema:
          type: string
        name: orgMasterId
        in: query
        required: false
        description: |
          The organisationMasterIdentifier of the school.
          This parameter is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
          type: string
        name: orgId
        in: query
        required: false
        description: |
          The organisationIdentifier (secundary identifier) of the school.
          This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          example: DD_ID
          enum:
            - OIE_CODE
            - VE_CODE
            - BP_ID
            - DD_ID
            - AS_ID
        name: orgIdType
        in: query
        required: false
        description: |
          The type of the organisationIdentifier.
          This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
      - 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"
    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: sourceId
        in: query
        required: true
        description: 'Reference to the sourceId of the Employee object.'
      - schema:
          type: string
        name: orgMasterId
        in: query
        required: false
        description: |
          The organisationMasterIdentifier of the school.
          This parameter is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
          type: string
        name: orgId
        in: query
        required: false
        description: |
          The organisationIdentifier (secundary identifier) of the school.
          This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          example: DD_ID
          enum:
            - OIE_CODE
            - VE_CODE
            - BP_ID
            - DD_ID
            - AS_ID
        name: orgIdType
        in: query
        required: false
        description: |
          The type of the organisationIdentifier.
          This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
    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: orgMasterId
        in: query
        required: false
        description: |
          The organisationMasterIdentifier of the school.
          This parameter is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
          type: string
        name: orgId
        in: query
        required: false
        description: |
          The organisationIdentifier (secundary identifier) of the school.
          This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          example: DD_ID
          enum:
            - OIE_CODE
            - VE_CODE
            - BP_ID
            - DD_ID
            - AS_ID
        name: orgIdType
        in: query
        required: false
        description: |
          The type of the organisationIdentifier.
          This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
      - 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"
    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

...

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.

...

- eduv.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: 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 14

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

Technisch: API specificatie

Release notes

Release notes

Page Comparison

Versions Compared

Old Version 14

New Version Current

Key

Anchor

employee

employee

Object: Employee (Onderwijsmedewerker)

Anchoremployee-communicationemployee-communication

Attributen : EmployeeCommunication

Anchoremployee-rolesemployee-roles

Attributen: EmployeeRoles

Anchororganisation-rolesorganisation-rolesObject:

OrganisationRoles

Technisch: API specificatie

Release notes

Release notes

Anchor
employee-communication
employee-communication

Anchor
employee-roles
employee-roles

Anchor
organisation-roles
organisation-roles
Object: