Page Comparison

Titel

Employees API

Status

colour	Purple
title	In ontwikkeling

Status

title	BEsluitvorming

Status

title	in beheer

Versie

Documentatie: 0.0.34

schemaVersion: 0.0.34

Datum

18 19 April 2024

Auteurs

Architectenraad Edu-V

Acties

Review en doorontwikkeling op basis van input LAS leveranciers

...

Het object Student beschrijft de identifiers en de namen van de onderwijsdeelnemer. 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 berichten. Er is nog geen primaire identifier voor onderwijsmedewerkers. Enkel secundaire identifiers worden gehanteerd. In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.
userIds	array	userId	Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.	[{userId: ‘pietjepukkelen@petteflatcollege', userIdType: 'nlEduPersonRealId’}] Zie referentie naar eindgebruiker	V*	Zodra een secundaire identifier voor een uitzonderingssituatie gehanteerd wordt dan wordt naast het Id ook het Type gespecificeerd. Zie de pagina Identiteiten voor de toegestane secundaire identifiers.
givenName	string	string	De voornaam van de onderwijsmedewerker		V
familyName	string	string	De achternaam van de onderwijsmedewerker		V
familyNamePrefix	string	string	Het tussenvoegsel uit de achternaam van de onderwijsmedewerker		O
sourceId	string	string	Een unieke identifier die gegenereerd is door het Administratiesysteem onderwijsmedewerker en binnen dit systeem uniek is.		V	De sourceId wordt gebruikt om informatie over dit object op te vragen in de koppelvlakspecificatie. Deze identifier is betekenisloos en daarmee geen persoonsgegeven.
status	string	ENUM	De status van dit object.	active tobedeleted	V	De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.
dateCreated	string	datetime	Datum 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

sourceId

string

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-mailadres van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder

employee@school.nl

V

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

Anchor
organisation-roles
organisation-roles
Object: organisationRoles

...

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.0.34'
  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 secundary 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.0.34
          
    Employee:
      title: Employee
      description: 'The Employee object with its identifiers and name information.'
      type: object
      x-tags:
        - Employee
      properties:
        userMasterIdentifier:
          type: string
          description: |
            The primary identifier for the Employee.
            For Employees this value is empty. There is no primary identifier for Employees.
        userIds:
          type: array
          description: |
            A secundary identifier for a User. This value is used whenever the primary identifier is not available.
            For Employees this value is mandatory.
            (either userMasterIdentifier or userIds is required)
          items:
            type: object
            properties:
              userId:
                type: string
              userIdType:
                type: string
                enum:
                  - NEPPI # nlPersonProfileId – value can be used for students and employees
                  - BPI # Basispoort ID – value can be used for students and employees
                  - eduID # eduID identifier – value can be used for students and employees
                  - eckId # ECK iD – value can be used for employees only, eckId is userIdType for userMasterIdentifier for students
            required:
              - userId
              - userIdType
        givenName:
          type: string
        familyName:
          type: string
        familyNamePrefix:
          type: string
        sourcedIdemail:
          type: string
          format: uuid
 description: 'E-mail address hosted by school (e.g. L123456@school.nl).'
        descriptionphone:
  |        type: string
   The Source Identifier of the object. This isdescription: a'Phone GUIDnumber Systemas IDprovided forby anthe objectschool.'
        mobile:
    This is the GUID that Consumers willtype: referstring
to when making API calls, or when needing to identify an object.
      description: 'Mobile phone number as provided by the school.'
     It is RECOMMENDED thatorganisationRoles:
systems are able to map whichever local ids (e.g. database key fields), userMasterIdentifier or userIds they use to SourceId.
            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).
            
            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).
        status:
          description: |
            The status field gives an indication to Consumers about the status of an object.
            Consumers can delete objects that are flagged `tobedeleted`  as such if they wish.

            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).
          type: string
          enum:
            - active
            - tobedeleted
        dateCreated:
          type: string
          description: 'Indicates the date and time the object was first created. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
          format: date-time
          example: "2017-07-21T17:32:28Z"
        dateLastModified:
          type: string
          description: 'Indicates the date and time the object was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
          format: date-time
          example: "2022-08-11T15:31:12Z"
      required:
        - userIds
        - givenName
        - familyName
        - status
        - sourceId
        - dateCreated
        - dateLastModified
    
    EmployeeCommunication:
      title: EmployeeCommunication
      description: 'Communication data of the Employee. For Employees this is the e-mail address, phone number or mobile phone number as provided by the School.'
      type: object
      x-tags:
        - EmployeeCommunication
      properties:
        sourceId:
          type: string
          format: uuid
          description: 'The Source Identifier of the Employee.'
        email:
          type: string
          description: 'E-mail address hosted by school (e.g. L123456@school.nl).'
        phone:
          type: string
          description: 'Phone number as provided by the school.'
        mobile:
          type: string
          description: 'Mobile phone number as provided by the school.'
      required:
        - sourceId
        - email

    EmployeeRoles:
      title: EmployeeRoles
      description: 'Roles of the Employee within the school.'
      type: object
      x-tags:
        - EmployeeRoles
      properties:
        sourceId:
          type: string
          format: uuid
          description: 'The Source Identifier of the Employee.'
        organisationRoles:
          type: array
          description: 'The organisation roles the Employee has within the organisation.'
          items:
            type: object
            properties:
              organisation:
                $ref: '#/components/schemas/SchoolReference'
              organisationRole:
                type: string
                description: 'The organisation role the Employee has within the organisation.'
                enum:
                  - administratief-medewerker
                  - applicatiebeheerder
                  - begeleider
                  - invalkracht
                  - ibp-er
                  - leermiddelencoordinator
                  - leraar
                  - mentor
                  - onderwijsbestuurder
                  - onderwijsdirecteur
                  - stagiair
              beginDate:
                type: string
                description: 'The start date on which the role becomes active (inclusive). Format: YYYY-MM-DD (according to RFC3339).'
                format: date
                example: '2022-07-31'
              endDate:
                type: string
                description: 'The end date on which the role becomes inactive (exclusive). Format: YYYY-MM-DD (according to RFC3339).'
                format: date
                example: '2024-08-31'
            required:
              - organisation
              - organisationRoles
              - beginDate
      required:
        - sourceId
        - organisationRoles

    # This UserReference might not be necessary for the Employees API. References are made based on the sourceId of the Employee object.
    UserReference:
      type: object
      title: UserReference
      properties:
        userMasterIdentifier:
          type: string
          description: |
            The primary identifier for a User.
            For Students the ECK iD is used.
            For Employees this value is empty. There is no primary identifier for Employees.
            (either userMasterIdentifier or userIds is required)
        userIds:
          type: array
          description: |
            A secundary identifier for a User. This value is used whenever the primary identifier is not available.
            For Employees this value is mandatory.
            (either userMasterIdentifier or userIds is required)
          items:
            type: object
            properties:
              userId:
                type: string
              userIdType:
                type: string
                enum:
                  - NEPPI # nlPersonProfileId – value can be used for students and employees
                  - BPI # Basispoort ID – value can be used for students and employees
                  - eduID # eduID identifier – value can be used for students and employees
                  - NEPRI # nlPersonRealId – value can be used for students only
                  - ASI # Las-key – value can be used for students only
                  - eckId # ECK iD – value can be used for employees only, eckId is userIdType for userMasterIdentifier for students
            required:
              - userId
              - userIdType
    
    SchoolReference:
      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 `OnderwijsaanbiederId` is used.
            (either organisationMasterIdentifier or organisationIds is required)
          example: '104A158' # De Mariënborn
        organisationIds:
          type: array
          description: |
            A secundary 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:
                  - OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - VE_CODE # Vestigingserkenningcode e.g. 09QQ00 (Marienbornschool)
                  - BP_ID # Basispoort gegenereerde identifier voor de school.
                  - DD_ID # Door de Centrale Registratie van Edu-iX gegenereerde DigiDeliveryId van de school.
                  - AS_ID # 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:
            employee.basic: 'a scope that gives access to employee identifers and name.'
            employee.communication: 'a scope that gives access to employee communication attributes.'
            employee.roles: 'a scope that gives access to employee organisation roles attributes.'
            
paths:
  
  /employees/:
    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'
      x-tags:
        - Employee
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employee
      description: |
        Request an 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/Employee'
        '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.basic

  /employees/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  type: array
          enumdescription: 'The organisation roles the Employee has within the organisation.'
   - OIE_CODE      items:
      - VE_CODE     type: object
      - BP_ID     properties:
       - DD_ID      organisation:
      - AS_ID         name$ref: orgIdType'#/components/schemas/SchoolReference'
        in: query         required: false
    organisationRole:
   description: |           The type of the organisationIdentifier.
          This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.: string
               - schemadescription: 'The organisation role the Employee has within the organisation.'
    type: integer         name: start enum:
       in: query         description: 'Start point for pagination of results, defaults to 0,'- administratief-medewerker
               examples:   - applicatiebeheerder
      default:            - value:begeleider
0             summary: The start point for pagination- invalkracht
     - schema:           type: integer- ibp-er
         maximum: 100        - name:leermiddelencoordinator
limit         in: query        - description:leraar
'Limit of number of results returned by page, defaults to 20 with max 100.'     - mentor
  examples:           default:     - onderwijsbestuurder
      value: 20           - onderwijsdirecteur
summary: The default value if none is provided           max:- stagiair
           value: 100  beginDate:
          summary: The largest recommended page size type: string
    - schema:           typedescription: string'The start date on which the role becomes active   format(inclusive). Format: dateYYYY-MM-timeDD (according to RFC3339).'
     in:  query         nameformat: since
 date
      required: false         descriptionexample: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'2022-07-31'
              endDate:
          example: "2017-07-21T17:32:28Z"     gettype: string
     summary: Get Employees for School       x-tags:
        - Employeedescription: 'The end date on which the role becomes inactive (exclusive). Format: YYYY-MM-DD (according to RFC3339).'
        tags:        format: -date
Administratiesysteem onderwijsmedewerker       operationId: get-employees-for-school       descriptionexample: 'Request all Employee objects including basic information (identifiers and names) for a specified school.'2024-08-31'
            required:
       responses:       - organisation
'200':           description: OK  - organisationRoles
       content:       - beginDate
    application/json:    sourceId:
          schematype: string
          format: uuid
    type: array     description: |
          items:  The Source Identifier of the object. This is a GUID System ID for an object.
  $ref: '#/components/schemas/Employee'         '400':This is the GUID that Consumers will refer to when making description:API Badcalls, Requestor when needing to identify an object.
    content:        It is RECOMMENDED that systems application/json:are able to map whichever local ids (e.g. database key fields), userMasterIdentifier or userIds they schema:use to SourceId.
            The sourcedId $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorizedof an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
          content:  
          application/json:  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).
  schema:      status:
          $refdescription: '#/components/schemas/StatusResponse'
|
       '403':     The status field gives an indication description:to ForbiddenConsumers about the status of an object.
    content:        Consumers can delete objects that application/json:are flagged `tobedeleted`  as such if they wish.

     schema:       The status attribute is based on the [Base Class from $ref: '#/components/schemas/StatusResponse'OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
          '404'type: string
          descriptionenum:
  Not Found         - active
content:            - application/json:tobedeleted
        dateCreated:
     schema:     type: string
          $refdescription: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
Indicates the date and time the object was first created. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
          format: date-time
  employee.basic    /employees/communication/:     parameters:example: "2017-07-21T17:32:28Z"
      -  schemadateLastModified:
          type: string
        name: sourceId
        in: query
        required: true  description: 'Indicates the date and time the object was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
          descriptionformat: 'Referencedate-time
to the sourceId of the Employee object.'       - schema:example: "2022-08-11T15:31:12Z"
      required:
    type: string   - userIds
    name: orgMasterId   - givenName
    in: query   - familyName
    required: false   - status
    description: |   - sourceId
      The organisationMasterIdentifier of- thedateCreated
school.        - dateLastModified

This parameter is used when# theThis primairyUserReference identifiermight fornot abe schoolnecessary (beingfor the `OnderwijsaanbiederId`) is availableEmployees API. References      - schema:
          type: string
 are made based on the sourceId of the Employee object.
    UserReference:
      nametype: orgIdobject
        intitle: queryUserReference
        requiredproperties:
false         descriptionuserMasterIdentifier:
|          type: Thestring
organisationIdentifier (secundary identifier) of the school.     description: |
    This parameter is used in combination with the orgIdTypeThe whenprimary theidentifier organisationMasterIdentifierfor isa notUser.
available.       - schema:    For Students the ECK iD is used.
type: string           example: DD_ID
          enum:For Employees this value is empty. There is no primary identifier for Employees.
            - OIE_CODE
   (either userMasterIdentifier or userIds is required)
        -userIds:
VE_CODE          type: array
 - BP_ID        description: |
   - DD_ID        A secundary identifier for a - AS_ID
        name: orgIdTypeUser. This value is used whenever the primary identifier is not available.
        in: query   For Employees this value is mandatory.
required: false         description: |  (either userMasterIdentifier or userIds is required)
   The type of the organisationIdentifier.   items:
       This parameter is used in combinationtype: withobject
the orgId when the organisationMasterIdentifier is not available.     getproperties:

     summary: 'Get Employee Communication'       x-tagsuserId:
        - EmployeeCommunication       tagstype: string
       -  Administratiesysteem onderwijsmedewerker    userIdType:
  operationId: get-employee-communication       description: |     type: string
  Request the communication attributes of Employee object based on its sourceId.    enum:
    The Source Identifier is the GUID System ID for an object. This is the GUID- thatNEPPI Consumers# willnlPersonProfileId refer– tovalue whencan makingbe APIused calls.for students and employees
     The sourcedId of an object is considered an addressable property of an entity and- asBPI such# willBasispoort notID be– treatedvalue ascan Personallybe Identifiableused Information (PII).
 for students and employees
    responses:         '200':     - eduID # eduID identifier – description:value OKcan be used for students and employees
    content:             application/json: - NEPRI # nlPersonRealId – value can be used for students only
  schema:                - $ref:ASI '#/components/schemas/EmployeeCommunication'
        '400': Las-key – value can be used for students only
          description: Bad Request      - eckId # ECK iD content:– value can be used for employees only, eckId is userIdType for userMasterIdentifier application/json:for students
             schemarequired:
              - userId
$ref: '#/components/schemas/StatusResponse'           '401':   - userIdType
      descriptionrequired: Unauthorized
        - userIds
content:    
    SchoolReference:
   application/json:   type: object
      title: SchoolReference
  schema:    description: 'A reference to a School organisation.'
      $refproperties:
'#/components/schemas/StatusResponse'         '403'organisationMasterIdentifier:
          descriptiontype: Forbiddenstring
          contentdescription: |
           application/json: The primary identifier for a School. For Schools the `OnderwijsaanbiederId` is used.
  schema:          (either organisationMasterIdentifier or organisationIds is required)
 $ref: '#/components/schemas/StatusResponse'        example: '404104A158': # De Mariënborn
        descriptionorganisationIds:
Not Found           contenttype: array
           application/jsondescription: |
            A schema:
secundary identifier for the School. This value is used whenever the primary identifier is not available.
$ref: '#/components/schemas/StatusResponse'       security:    (either organisationMasterIdentifier or organisationIds is -required)
OAuth2:          items:
  - employee.communication    /employees/communication/school/:     parameterstype: object
     - schema:      properties:
    type: string         nameorganisationId:
orgMasterId         in: query         requiredtype: falsestring
        description: |     organisationIdType:
     The organisationMasterIdentifier of the school.        type: string
 This parameter is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`) is available.enum:
      - schema:           type: string
    - OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
   name: orgId         in: query    - VE_CODE # Vestigingserkenningcode  required: falsee.g. 09QQ00 (Marienbornschool)
        description: |         - BP_ID The# organisationIdentifierBasispoort (secundarygegenereerde identifier) ofvoor thede school.
          This  parameter is used in combination with the- orgIdTypeDD_ID when# theDoor organisationMasterIdentifierde isCentrale notRegistratie available.van Edu-iX gegenereerde DigiDeliveryId van de school.
- schema:           type: string     - AS_ID # Door het Leerlingadministratiesysteem example: DD_ID
  gegenereerde identifier van de school.
       enum:     required:
       - OIE_CODE      - organisationId
     - VE_CODE        - organisationIdType

  - BP_ID StatusResponse:
      title: StatusResponse
   - DD_ID  type: object
      description: 'Functional status -code AS_IDand status message.'
      nameproperties:
orgIdType        status:
in: query         requiredtype: integer
false          description: 'See |functional status codes within the Documentation.'
     The type of thestatusMessage:
organisationIdentifier.          type: Thisstring
parameter is used in combination with the orgId when the organisationMasterIdentifierdescription: is'See notfunctional available.status messages within the Documentation.'
  - schema:   required:
       type: integer- status
  
  securitySchemes:
 name: start  OAuth2:
      intype: queryoauth2
      flows:
 description:  'Start point for pagination of results,clientCredentials:
defaults to 0,'        tokenUrl: examples:https://api.example.com/oauth2/token
          defaultrefreshUrl: https://api.example.com/oauth2/token
           valuescopes:
0             summaryemployee.basic: The'a startscope pointthat forgives paginationaccess to employee identifers and name.'
 - schema:           typeemployee.communication: integer'a scope that gives access to employee communication  attributes.'
 maximum: 100         name: limit    employee.roles: 'a scope that gives in:access queryto employee organisation roles attributes.'
    description: 'Limit of number of results returned by page,
defaultspaths:
to 20 with
max 100.'
 /employees/:
    post:
  examples:    summary: Search Employee
    default:  x-tags:
        - Enrollment
value: 20     tags:
       summary: The- defaultAdministratiesysteem valueonderwijsmedewerker
if none is provided   operationId: search-employee
      maxdescription: 'Request an Employee object for a specified Employee at a School.'
 value: 100    requestBody:
        summarycontent:
The largest recommended page size       - schema:application/json:
            typeschema:
string           format: date-time  type: object
     in: query         nameproperties:
since         required: false       school:
 description: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'$ref: '#/components/schemas/SchoolReference'
          example: "2017-07-21T17:32:28Z"     getemployee:
      summary: Get Employees Communication for School       x-tags$ref: '#/components/schemas/UserReference'
       - EmployeeCommunication       tagsrequired:
  
     - Administratiesysteem onderwijsmedewerker       operationId: get-employees-communication-for-  - school
      description: 'Request communication attributes for all Employee objects for a specified- school.'employee
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $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:
            - employee.basic
            - employee.communication
            - employee.roles

  /employees/roles/{sourceId}:
    parameters:
      - schema:
          type: string
        name: sourceId
        in: querypath
        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:
        - EmployeeRolesEmployee
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employee-roles
      description: |
        Request the organiation roles attributes of an 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/EmployeeRolesEmployee'
        '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.basic
   security:         - OAuth2:employee.communication
            - 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:
        - EmployeeRolesEmployee
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employees-roles-for-school
      description: 'Request all organisationEmployee objects rolesincluding attributesbasic forinformation all(identifiers Employeeand objectsnames) for a specified school.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeRolesEmployee'
        '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.basic
            - employee.communication
            - employee.roles

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

...

0.0.1: De Rostering API was voorheen een onderdeel van de SIS API. Hierin waren de volgende wijzingen gedaan:
- 0.0.1: Eerste draft van de API.
- 0.0.2: Berichtdefinities en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.
- 0.0.3: De technische specificatie is verder uitgewerkt. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:
  - GET all endpoints zijn toegevoegd voor alle objecten.
  - Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van regie op gegevens en de M2M identificatie en authenticatie.
  - Bericht Teacher is hernoemd naar Employee inclusief het attribuut role. In dezelfde lijn is ook teacherReference hernoemd naar employeeReference
  - De waardelijst studyYear is verduidelijkt.
  - Het attribuut class van de Student is een separaat bericht geworden inclusief employees.
  - De status- en foutcodes zijn toegevoegd aan de documentatie en de YAML.
  - In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
  - De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.
- 0.0.4: Berichtdefinities geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader.
- 0.0.5: Terminologie in YAML bijgewerkt.
- 0.0.6: Gegevensdiensten van SIS API opgesplitst in:
  - Onderwijsorganisatie
  - Adresgegevens fijndistributie
  - Onderwijsaanbod
0.0.2: De Employees API is opgesteld op basis van een herziening van de SIS API. In deze herziening is aansluiting gezocht bij de best practices uit bestaande standaarden en een uiteenzetting van ontwerpeisen vanuit de flexibilisering van het onderwijs.
0.0.3: De volgende wijzigingen zijn gedaan:
- Wijzigingen in de architectuur:
  - Attribuut schemaVersion is verwijderd uit de berichtspecificaties.
  - Query parameter schemaVersion is verwijderd uit de koppelvlakken.
  - Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
  - Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
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.

Versions Compared

Old Version 16

New Version 17

Key

Anchor
employee-communication
employee-communication

Attributen : EmployeeCommunication

Anchor
employee-roles
employee-roles

Attributen: EmployeeRoles

Anchor
organisation-roles
organisation-roles
Object: organisationRoles

Technisch: API specificatie

Page Comparison

Versions Compared

Old Version 16

New Version 17

Key

Anchoremployee-communicationemployee-communication

Attributen : EmployeeCommunication

Anchoremployee-rolesemployee-roles

Attributen: EmployeeRoles

Anchororganisation-rolesorganisation-rolesObject: organisationRoles

Technisch: API specificatie

Anchor
employee-communication
employee-communication

Anchor
employee-roles
employee-roles

Anchor
organisation-roles
organisation-roles
Object: organisationRoles