Pagina-navigatiestructuur
Spring naar het einde van metadata
Ga nar het begin van metadata

Inleiding



Schoolstructuur 

Het hoogste niveau is het project (schoolInSchoolYear). Dit is een combinatie tussen een school en een schooljaar. Een project kan vervolgens weer onderverdeeld zijn in verschillende vestigingen (branchesOfSchools).

Iedere vestiging bevat één of meerdere afdelingen (departmentOfBranch). Een afdeling bevat een leerlaag (1-6) en één of meerdere opleidingsniveaus (havo/vwo/..). Daarnaast kunnen leerlingen (students) geplaatst worden in een afdeling via een afdelingsdeelname (studentsInDepartments).

Op een afdeling worden meerdere keuzevakken (choosableInDepartments) aangeboden worden. Een keuzevak bevat een naam (netl/dutl/fatl/...), een type (profiel/opleiding/pakketvak) en eventueel een lessentabel (aantal uur per tijdvak dat deze les gegeven moet worden). Een afdelingsdeelname van een leerling kan verbonden zijn aan meerdere keuzevakken (ofwel zijn vakkenpakket).

Ieder keuzevak kan een aantal geplande groepen (plannedGroups) bevatten, ofwel het aantal geplande groepen per vak. Een geplande groep bevat, naast het keuzevak, ook een volgnummer (bijvoorbeeld AK.grp1 en AK.grp2).

Een afdeling kan meerdere roostergroepen (groupInDepartments) bevatten. Een leerling kan via zijn afdelingsdeelname deelnemen aan meerdere roostergroepen. Een roostergroep bevat tevens de eigenschap of het een stamklas of mentorgroep betreft.

Een roostergroep wordt gekoppeld aan één of meerdere geplande groepen. In de meeste gevallen is er per geplande groep ook één roostergroep aanwezig. Uitzonderingen zijn bijvoorbeeld stamklassen. Een stamklas (h4a) kan meerdere geplande groepen gekoppeld worden (entl.grp1, netl.grp1, lo.grp1, enz. )

Een afspraak (appointment) kan voorzien worden van een roostergroep.


Scholen en Vestigingen

Scholen en vestigingen zijn oorspronkelijk bedoeld om de vergelijkbare scholen en vestigingen van DUO te modelleren (hoofd-BRIN en vestiging-BRIN). Het staat een klant echter vrij dit in te delen. Het kan dus zijn dat een klant besluit zijn vestigingen in het portal te beschouwen als scholen.

Op dit moment kan in het portal een school voorzien zijn van een vier cijferig BRIN (Beheer > Portal-inrichting > Scholen). Een vestiging heeft een unieke code die door de klant vrij te bepalen is (Beheer > Portal-inrichting > Vestigingscode)

Geplande groepen vs Roostergroepen

Een geplande groep bevat géén leerlingen. Een geplande groep wordt door de formatiebeheerder gebruikt om per keuzevak aan te geven hoeveel groepen hij uiteindelijk verwacht. Hierdoor kan de formatiebeheerder zijn volledige formatie taakbeleid voltooien, zonder dat er door de roostermaker daadwerkelijke groepen zijn aangemaakt.

API requests

Roostergroepen

De roostergroepen kun in de portal interface vinden bij Onderwijs > Schoolstructuur > Roostergroepen


Je kunt alle roostergroepen van een project in één keer opvragen via: 

Request groupindepartments
$ curl https://schoolnaam.zportal.nl/api/v3/groupindepartments?schoolInSchoolYear=51&access_token=...

Dit is dan de response:

Response
{
"response": { 
	"status":200,
	"message":"",
	"details":"",
	"eventId":0,
	"startRow":0,
	"endRow":16,
	"totalRows":16,
	"data":[
		{
		"id":27,
		"departmentOfBranch":104,
		"name":"r3a",
		"isMainGroup":true,
		"isMentorGroup":false,
		"extendedName":"r3.r3a"
		},
		{
		"id":28,
		"departmentOfBranch":104,
		"name":"r3b",
		"isMainGroup":true,
		"isMentorGroup":false,
		"extendedName":"r3.r3b"
		},	
...]}}

Aanvullende info:

  1. Naam (name): de naam van de groep
  2. Onder welke afdeling valt deze groep (departmentOfBranch ID)
  3. Is de betreffende groep een stamklas (isMainGroup). Een leerling mag maximaal in één stamklas zitten
  4. Is de betreffende roostergroep een mentorgroep (isMentorGroup). Een leerling mag maximaal in één mentorgroep zitten
  5. Volledige naam, inclusief afdeling (extendedName)

Je kunt ook van slechts één afdeling de lesgroepen opvragen, door het fields parameter aan te passen.

Voor uitgebreide info, zie swagger: https://schoolnaam.zportal.nl/static/swagger/#!/groupindepartments/get


Roostergroepindelingen

Een overzicht van de roostergroepsindeling kun je in de portalinterface vinden bij Leerlingen > Roostergroepindelingen > Alle groepen

Je kunt van de gehele school in een keer alle leerlingen opvragen, door deze aan te vullen met een aantal verplichte fields parameters (id, student, departmentOfBranch):

Request studentsindepartments
$ curl https://schoolnaam.zportal.nl/api/v3/studentsindepartments?schoolInSchoolYear=51&fields=id%2Cstudent%2CdepartmentOfBranch%2CgroupInDepartments&access_token=...


Dit is dan de response: 

Response studentsindepartments
{
"response": {
	"status":200,
	"message":"",
	"details":"",
	"eventId":0,
	"startRow":0,
	"endRow":357,
	"totalRows":357,
	"data":[
		{
		"id":704,
		"student":"775021",
		"departmentOfBranch":105,
		"groupInDepartments":[59,48,60,46,61,44,50]
		},
		{
		"id":746,
		"student":"779801",
		"departmentOfBranch":105,
		"groupInDepartments":[47,46,52,62,43,50]
		},
...]}}

Aanvullende info:

  1. Afdelingsdeelname (id)
  2. Het betreffende leerlingnummer (student)
  3. In welke afdeling zit deze leerling (departmentOfBranch ID)
  4. In welke roostergroepen zit deze leerling (groupInDepartments)


Let op! Een leerling kan in een schooljaar in meerdere afdelingen zitten. Dat kan bijvoorbeeld zijn, omdat nog in de prognose fase nog niet duidelijk naar welke afdeling deze leerling volgend jaar gaat (prognoses).
In de (nabije) toekomst is het goed mogelijk dat een leerling bewust in twee afdelingen wordt geplaatst. Bijvoorbeeld wanneer een leerling uit de afdeling H4 (Havo 4) een aantal lessen gaat volgen op afdeling H5 (Havo 5).

Voor uitgebreide info, zie swagger: https://schoolnaam.zportal.nl/static/swagger/#!/studentsindepartments/get

Geplande groepen (plannedGroups)

Een overzicht van de Geplande Groepen per afdeling kun je in de portalinterface vinden bij Leerlingen > Geplande groepen > Geplande groepen (details)

Het is mogelijk van een project in één keer alle geplande groepen op te vragen, met 

Request studentsindepartments
$ curl https://schoolnaam.zportal.nl/api/v3/plannedgroups?schoolInSchoolYear=401&fields=id%2CchoosableInDepartment%2CgroupInDepartmentName%2CsubjectCode%2CgroupInDepartment%2CgroupInDepartmentIsMainGroup%2CgroupInDepartmentIsMentorGroup&access_token=...

Dit is dan de response: 

Response plannedgroups
{
"response": {
	"status":200,
	"message":"",
	"details":"",
	"eventId":0,
	"startRow":0,
	"endRow":357,
	"totalRows":357,
	"data":[
		{
		"id":1151,
		"choosableInDepartment":1697,
		"groupInDepartment":3951,
		"groupInDepartmentName":"ak1",
		"groupInDepartmentIsMainGroup":false,
		"groupInDepartmentIsMentorGroup":false,
		"subjectCode":"aard"
		},
		{
		"id":1152,
		"choosableInDepartment":1697,
		"groupInDepartment":null,
		"groupInDepartmentName":null,
		"groupInDepartmentIsMainGroup":null,
		"groupInDepartmentIsMentorGroup":null,
		"subjectCode":"aard"
		},
		{
		"id":3101,
		"choosableInDepartment":3195,
		"groupInDepartment":3954,
		"groupInDepartmentName":"h4a",
		"groupInDepartmentIsMainGroup":true,
		"groupInDepartmentIsMentorGroup":true,
		"subjectCode":"netl"
		},
		{"id":3102,
		"choosableInDepartment":3195,
		"groupInDepartment":3955,
		"groupInDepartmentName":"h4b",
		"groupInDepartmentIsMainGroup":true,
		"groupInDepartmentIsMentorGroup":true,
		"subjectCode":"netl"
		},
...]}}

Van een geplande groep krijg je de volgende informatie mee:

  1. Bij welk keuzevak hoort deze groep (choosableInDepartment
  2. Bij welke roostergroep hoort deze geplande groep (groupInDepartment

Het is mogelijk dat een geplande groep nog niet voorzien is van een roostergroep. In dat geval staat in de response "groupInDepartment": null.

Hiermee wordt aangegeven dat een groep voorlopig is gepland (door bijvoorbeeld de formatiebeheerder), maar nog niet daadwerkelijk is gerealiseerd. Zolang er nog geen roostergroep gekoppeld is, kun je deze geplande groep het beste negeren.


Er worden ook nog een aantal service velden meegestuurd (van de entiteiten choosableInDepartment en groupInDepartment):

  1. Naam van de roostergroep (groupInDepartmentName
  2. Is de roostergroep ook een stamklas (groupInDepartmentIsMainGroup) ?
  3. Is de roostergroep ook een mentorgroep (groupInDepartmentIsMentorGroup) ?
  4. De afkorting van het keuzevak (subjectCode)

Let op! Voor een correcte koppeling is het aan te raden informatie over de roostergroep en keuzevak daadwerkelijk op te vragen bij de betreffende entiteiten (groupInDepartment en choosableInDepartment). Gebruik hiervoor niet de servicevelden. Zo staat in dit geval in het serviceveld de naam van de roostergroep altijd zónder toevoeging van de afdeling. Je zult dus niet "h4.ak2" en "h5.bi2" zien staan, maar "ak2" en "bi2".

  • Geen labels