Results API

Titel

Results API

Status

DRAFT WERKGROEP KLANKBORDgroep ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT

Stadium

POC PILOT BEHEER

Versie

0.0.5

Datum

19 Juli 2023

Auteur

Uitwisselen summatieve toetsresultaten

Acties

• Geen activiteiten

Scopes

• la.result

Entiteiten

• Result

• Score

Producer

• Leermiddelenaanbieder – Digitaal toetssysteem

Consumer

• Administratiesysteemaanbieder – Cijferadministratie

Endpoints

Cijferadministratie

• PUT Accept result message from Leermiddelenaanbieder

• POST Accept result-bundle message from Leermiddelenaanbieder

• PUT Accept score message from Leermiddelenaanbieder

• POST Accept score-bundle message from Leermiddelenaanbieder

Digitaal toetssysteem

• GET result by resultId

• GET score by scoreId

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor dit toetsresultaat

 result123abc

V

Indien de status of het result wijzigt wordt hetzelfde id gehanteerd.

schemaVersion

string

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

1.3.0

V

Conform Semantic Versioning 2.0.0

eckId

string

ECK iD

Het ECK iD van de onderwijsdeelnemer

-

V*

eckId is verplicht. Indien onbekend dan kan userIds gehanteerd worden

userId

array

[userId, userIdType]

Alternatief userId indien eckId onbekend is

[12345, nlPersonProfileId]

O*

Verplicht zodra eckId onbekend is.

userIdType is conform de secundaire identifiers voor een Onderwijsdeelnemer.

Zie pagina identiteiten.

assessmentId

string

uuid

Unieke identifier voor de Toets

 toets123abc

V

De assessmentId hoeft niet bekend te zijn bij de Cijferadministratie

assessment-Name

string

string

Naam van de Toets die wordt getoond in de Administratie om de Toetsresultaten aan een cijferkolom toe te wijzen

Schoolexamen
Kijk- en Luistertoetsen HAVO5

V

De naam van de Toets is herkenbaar voor de medewerkers

status

string

ENUM

De status van het Toetsresultaat

in progress
final
canceled

V

Dit veld is additioneel toegevoegd en kan gebruikt worden om toetsresultaten in verschillende stadia door te sturen.

Defaultwaarde is final

assessment-
DateTime

string

datetime

Tijdstempel waarop de toetsafname gepland was

2017-07-21T17:32:28Z

V

resultValue

string

string

Het resultaat (resultaatwaarde) van de deelnemer (leerling of student) aan de Toets.

0.0…10.0
G, V, O
L1F, 1F,…,4S
A1…C2

V

Zie resultType

resultType

string

ENUM

Het resultaattype dat van toepassing is op deze Toets

0.0-10.0
OVG
RnTR
RnERK

V

1.0-10.0 voor cijfers met één decimaal.

OVG voor Onvoldoende, Voldoende of Goed

missing

boolean

{True,False}

Geeft aan of het toetsresultaat ontbreekt

True, False

O

Verplicht als resultValue leeg is

additionalInfo

string

string

Additionele informatie over dit toetsresultaat

HAVO-normering
Betrapt op spieken

O

Dit veld kan bijvoorbeeld gebruikt worden om onderscheid te maken in toetsresultaten van dezelfde onderwijsdeelnemer met een normering op HAVO en VWO niveau.

Ook kan het veld gebruikt worden om een reden op te geven waarom er een resultaat ontbreekt. Bijvoorbeeld fraude of niet aanwezig.

reviewUrl

string

url

Een URL naar de details over het toetsresultaat van deze deelnemer in het Digitaal toetssysteem

-

O

In andere (internationale) standaarden wordt dit veld ook wel deeplink of submission review url genoemd.

Een onderwijsmedewerker kan door het klikken op deze reviewUrl bij aanvullende informatie komen over het toetsresultaat.

employees

array

[eckId, [userId, userIdType]]

Array van Onderwijsmedewerkers die het Toetsresultaat van de Leerling mogen administreren in de Cijferadministratie.

-

V

Minimaal 1 Onderwijsmedewerker is toegevoegd.

De Onderwijsmedewerker is gespecificeerd met een eckId of een alternatief userId.

Het userId is wederom een array van het userId en het userIdType.

userIdType is conform de secundaire identifiers voor een Onderwijsmedewerker.

Zie pagina identiteiten.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor deze toetsscore

 score123abc

V

Indien de status of de score wijzigt wordt hetzelfde id gehanteerd.

schemaVersion

string

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

1.3.0

V

Conform Semantic Versioning 2.0.0

eckId

string

ECK iD

Het ECK iD van de onderwijsdeelnemer

-

V*

eckId is verplicht. Indien onbekend dan kan userIds gehanteerd worden

userId

array

[userId, userIdType]

Alternatief userId indien eckId onbekend is

[12345, nlPersonProfileId]

O*

Verplicht zodra eckId onbekend is.

userIdType is conform de secundaire identifiers voor een Onderwijsdeelnemer.

Zie pagina identiteiten.

assessmentId

string

uuid

Unieke identifier voor de Toets

 toets123abc

V

De assessmentId hoeft niet bekend te zijn bij de Cijferadministratie

assessment-Name

string

string

Naam van de Toets die wordt getoond in de Administratie om de scores aan een cijferkolom toe te kunnen wijzen

Schoolexamen
Kijk- en Luistertoetsen HAVO5

V

De naam van de Toets is herkenbaar voor de medewerkers

status

string

ENUM

De status van de toetsscore

in progress
final
canceled

V

Dit veld is additioneel toegevoegd en kan gebruikt worden om toetsscores in verschillende stadia door te sturen.

Defaultwaarde is final

assessment-
DateTime

string

datetime

Tijdstempel waarop de toetsafname gepland was

2017-07-21T17:32:28Z

V

scoreValue

string

string

De score (scorewaarde) van de deelnemer (leerling of student) aan de Toets.

7.6

V

De waarde van de score moet voldoen aan de omzetting in scoreschaal.

scoreScale

array

[LHS, RHS]

De scoreschaal die van toepassing is op de score voor deze Toets

[{ 0.0-5.4, Onvoldoende},{5.5-10.0, Voldoende}]

V

Geeft voor een interval aan waarden (LHS) aan welke resultaatwaarde (RHS) daarvoor geldt.

missing

boolean

{True,False}

Geeft aan of de toetsscore ontbreekt

True, False

O

Verplicht als scoreValue leeg is

additionalInfo

string

string

Additionele informatie over deze toetsscore

Betrapt op spieken of Niet aanwezig

O

Dit veld kan bijvoorbeeld gebruikt worden om een reden op te geven waarom er de score ontbreekt.

reviewUrl

string

url

Een URL naar de details over de toetsscore van deze deelnemer in het Digitaal toetssysteem

-

O

In andere (internationale) standaarden wordt dit veld ook wel deeplink of submission review url genoemd.

Een onderwijsmedewerker kan door het klikken op deze reviewUrl bij aanvullende informatie komen over de score.

employees

array

[eckId, [userId, userIdType]]

Array van Onderwijsmedewerkers die de score van de toetsdeelnemer mogen administreren in de Cijferadministratie.

-

V

Minimaal 1 Onderwijsmedewerker is toegevoegd.

De Onderwijsmedewerker is gespecificeerd met een eckId of een alternatief userId in userIds.

Het userIds is wederom een array van het userId en het userIdType.

userIdType is conform de secundaire identifiers voor een Onderwijsmedewerker.

Zie pagina identiteiten.

Status code

Status

statusMessage

Toelichting

200

0

OK

Verzoek succesvol verwerkt

400

1

schema validation unsuccessful

Schemavalidatie niet succesvol

400

2

schemaVersion not supported

De ontvanger kan de gevraagde SchemaVersion niet aanbieden.

401

3

scope required

Client is niet geautoriseerd voor scope.

403

4

consent required

De gegevenssoort is van classificatie II of IV. Dit vereist een activering van de gegevensuitwisseling. Dit is in dit foutscenario niet het geval.

403

5

edu_org_id unknown

De Verzender communiceert in de context van een Onderwijsorganisatie die niet bekend is bij Ontvanger.

404

6

Result unknown

De identifier van het resultaat is onbekend.

404

7

Score unknown

De identifier van het resultaat is onbekend.

400

99

Vullingsregel: in statusMessage een beschrijving van de reden opnemen

Overige reden