Results API

Titel

Results API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.0.9

schemaVersion: 0.0.5

Datum

23 Mei 2024

Auteur

Werkgroep Toetsen en examineren

Acties

  • Review door werkgroep Toetsen en Examineren

De Results API wordt gebruikt om leerresultaten te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Leerresultaten met het Digitaal toetssysteem als Verzender.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst

  • Leerresultaten

Scopes

  • result

Entiteiten

Verzender

  • Digitaal toetssysteem

Ontvanger

  • Administratiesysteem leerresultaten

Endpoints

Administratiesysteem leerresultaten

POST /results

Operatie met endpoint POST /results in het koppelvak van Administratiesysteem leerresultaten wordt door het Digitaal toetssysteeem aangeroepen:

Operatie en endpoint

POST /results

Operatie en endpoint

POST /results

OperatieID

postResults

Samenvatting

Het verzoek om bij ontvangende systeem de toetsscores & -resultaten te verwerken voor een individuele student of groep van studenten.

Beschrijving

Lijst van score & resultaat items per student, met voor ieder lijst item het verzoek nieuwe deelnemers scores/resultaten te creëren of bestaande deelnemers scores/resultaten te wijzigen. Het bericht is ingericht op groepsgewijze aanlevering of aanlevering van individuele student. Bij de lijst is algemene informatie gevoegd zoals toets/examen, afnamemoment en opmerkingen.

Tags

Administratiesysteem leerresultaten

Parameters bij request

-

Object in request body

Object AssessmentScoresAndResults, met onderliggende objecten StudentScoresAndResults, Assessment en ScoreScale.

Antwoorden (statuscodes)

202 (Accepted): “Het verzoek is geaccepteerd voor verwerking, maar de verwerking heeft nog niet plaatsgevonden; in feite zou de verwerkingen nog niet gestart kunnen zijn. De verwerking zal later wel of niet plaatsvinden, waarbij het verzoek bij de verwerking eventueel zou kunnen worden afgewezen.“

Antwoorden (foutcodes)

400 (Bad request)

401 (Unauthorized)

403 (Forbidden)

Object AssessmentScoresAndResults

Het gegevensobject AssessmentScoresAndResults (Toetsscores en -resultaten) inclusief onderliggende objecten StudentScoresAndResults (Deelnemerscores en -resultaten) met bijbehorende gegevensgroepen omvat de gegevens over de scores en resultaten door individuele onderwijsdeelnemers behaald bij een bepaalde toetsafname, en wordt in onderstaande figuur weergegeven.

 

afbeelding-20240523-150949.png
Figuur: AssessmentScoresAndResults gegevensobject

 

In bovenstaand figuur wordt het gegevensobject AssessmentScoresAndResults weergegeven. Dit object heeft stereotype <Entiteittype> om aan te geven dat dit een entiteit is. Dit object omvat de gegevenselementen id t/m toolName zoals in het blok getoond met cardinaliteit over verplichting en hoeveel keren dit element mag voorkomen. Bij ontbrekende cardinaliteit is dit exact 1 (verplicht 1 keer).
Deze elementen zijn attributen of gegevensgroepen. Een attribuut is een gegevensveld met een waarde, ieder attribuut heeft een datatype. Wanneer dit datatype een lijst van waarden (enumeratie) is dan wordt deze enumeratie (stereotype <Enumeratie>) getoond. De relatie tussen een object en betreffende enumeratie is schematisch gerepresenteerd door een pijl van object naar enumeratie.
Bijvoorbeeld attribuut id is een gegevensveld van type Characterstring en attribuut status is gegevensveld van type enumeratie StatusType_enum (en in het figuur is dan ook een pijl getekend naar deze enumeratie).
Een gegevensgroep is een element met deelelementen gedefinieerd door een object. Ieder object is van type groep (stereotype <Groep>) of entiteit stereotype <Entiteittype> wanneer dit object een entiteit is. De relatie tussen een object en betreffende gegevensgroep is schematisch gerepresenteerd door een pijl van object naar deelobject.
Bijvoorbeeld het element assessment is een gegevensgroep van type Assessment (en in het figuur is dan ook een pijl getekend naar het object Assessment).

In het gegevensobject AssessmentScoresAndResults bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

In het gegevensobject AssessmentScoresAndResults bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor dit object .

ad80f160- cd06-48dd-af15-84263e173082

V

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

additionalInfo

string

string

Additionele informatie of opmerking over de afname

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 de afname is afgebroken. Bijvoorbeeld internet viel uit.

assessment-
DateTime

string

datetime

Tijdstempel van moment waarop de toetsafname gestart of afgesloten is.

2017-07-21T17:32:28Z

V

 

assessment-Definition

object

Assessment

Definitie van toets en toetsonderdelen bestaande uit identifier en naam van toets en toetsonderdelen.

Zie Object Assessment

V

Vanuit individuele score of resultaat kan worden verwezen naar een toets/toetsonderdeel. De toetsdefinitie hoeft niet bekend te zijn bij de ontvanger.

employees

array

[userMasterIdentifier, userIds]

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

-

V

Minimaal 1 Onderwijsmedewerker is toegevoegd.

Onderwijsmedewerker is gespecificeerd met een userMasterIdentifier of een alternatieve identiteit in attribuut 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.

reviewUrl

string

url

Een URL naar de details over alle scores en resultaten van dit bericht 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 resultaten.

school

object

[organisation-MasterIdentifier, organisationIds]

De onderwijsorganisatie waar de onderwijsdeelnemers de opleiding volgen waarvoor ze deelnemen aan de toetsafname.

-

V

School is verplicht.

School als organisatie is gespecificeerd met een organisationMaster-Identifier of een alternatieve identiteit in attribuut organisationIds.

Het organisationIds is wederom een array van het organisationId en het organisationIdType.

organisationIdType is conform de secundaire identifiers voor een Onderwijsorganisatie.

Zie pagina identiteiten.

schoolPeriod

string

string

De schoolperiode waarop de scores en resultaten betrekking hebben.

Schooljaar 2024-2025

V

 

scoreScale-Definitions

array

ScoreScale

Definitie van de scoreschalen die van toepassing zijn op de scores en resultaten.

Zie Object ScoreScale

O

Vanuit individuele score of resultaat kan worden verwezen naar een scoreschaal.

studentScores-AndResults

array

StudentScoresAndResults

De scores en resultaten van een individuele student (onderwijsdeelnemer)

Zie Object StudentScoresAndResults

O

Kan leeg zijn als alle scores en resultaten van alle studenten ontbreken, bijvoorbeeld door calamiteit.

timestamp

string

datetime

Tijdstempel waarop het bericht is samengesteld.

2017-07-21T17:32:28Z

V

 

toolName

string

string

De naam van het systeem (de tool) waaruit de scores en resultaten zijn verzonden.

Toetssysteem A

O

 

Object StudentScoresAndResults

Het gegevensobject StudentScoresAndResults bestaat uit een gegevensblok met de scores en resultaten van een individuele student (onderwijsdeelnemer), en wordt in onderstaand figuur weergegeven.

afbeelding-20240523-151233.png
Figuur: StudentScoresAndResults gegevensobject

 

In het object StudentScoresAndResults bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor dit item met individuele scores en resultaten

14d807e9-8684-4a84-bc08-d48cd20eb733

V

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

additionalInfo

string

string

Additionele informatie of opmerking over deze scores en resultaten van deze deelnemer

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.

missing

boolean

{True,False}

Geeft aan of scores en resultaten ontbreken

True, False

O

Verplicht als scores en results leeg zijn

results

array

[resultValue, resultType, assessmentId]

Een of meerdere result-items die zijn behaald door een individuele deelnemer bij deze afname.

[{ O, OVG },{ 5.1, 0.0-10.0, part3 }]

O

Een resultaat-item bestaat uit de drie attributen resultValue, resultType en AssessmentId. Alleen resultValue en resultType zijn verplicht,

Het resultValue bevat de waarde van het resultaat en deze waarde moet voldoen aan typering in resultType . De waarde van resultType komt uit waardelijst.

Het assessmentId verwijst naar betreffende toets of toetsonderdeel in Toetsdefinitie (assessment).

reviewUrl

string

url

Een URL naar de details over deze scores en resultaten 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.

scores

array

[scoreValue, scoreType, scoreMaximum, assessmentId, scoreScaleId]

Een of meerdere score-items die zijn behaald door een individuele deelnemer bij deze afname.

[{ 64, 0-100},{ 6, 0-10 }]

O

Een score-item bestaat uit de vijf attributen scoreValue, scoreType, scoreMaximum, assessmentId en scoreScaleId. Alleen scoreValue en ScoreType zijn verplicht,

Het scoreValue bevat de waarde van het scoregetal en deze waarde moet voldoen aan typering in scoreType. Het scoretype (in scoreType) komt uit waardelijst. scoreMaximum is de maximum te behalen score en moet daarmee voldoen aan scoreType; en scoreValue moet kleiner of gelijk aan dit maximum zijn.

Het assessmentId verwijst naar betreffende toets of toetsonderdeel in Toetsdefinitie (assessment).

Het scoreScaleId verwijst naar betreffende scoreschaal in Scoreschaaldefinities (scoreScales).

status

string

ENUM

De status van dit deelnemer scores/resultaten item

in progress
final
canceled

O

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

Defaultwaarde is final

student

object

[userMasterIdentifier, userIds]

De Onderwijsdeelnemer die de scores en resultaten heeft behaald bij de betreffende toetsafname.

-

V

De Onderwijsdeelnemer is verplicht.

Onderwijsdeelnemer is gespecificeerd met een userMasterIdentifier of een alternatieve identiteit in attribuut userIds.

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

userIdType is conform de secundaire identifiers voor een Onderwijsdeelnemer .

Zie pagina identiteiten.

dateCreated

string

datetime

Datum waarop de entiteit is aangemaakt

2024-07-21T17:32:28Z

V

 

dateLastModified

string

datetime

Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd

2024-08-11T15:31:12Z

V

 

 

 

Object Assessment

Het gegevensobject Assessment (Toetsdefinitie) omvat de definitiegegevens van een toets eventueel met toetsonderdelen, en wordt in onderstaand figuur weergegeven.

In het gegevensobject Assessment bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor de Toets

6c92d082- 0d03-4194-b352-988b2e6f9ae6

V

Dit id hoeft niet bekend te zijn bij de ontvanger.

name

string

string

Naam van de Toets die wordt getoond in de Administratie om de toetsresultaten aan een resultaatkolom toe te wijzen

Schoolexamen
Kijk- en Luistertoetsen HAVO5

V

De naam van de Toets is herkenbaar voor de medewerkers.

parts

object

[ id, name, index ]

De onderdelen van de toets voor de toetsresultaten

[{ part1, Module 1},{ part2, Module 2 }]

O

Een toets hoeft geen onderdelen te hebben.

Een onderdeel-item bestaat uit de attributen id, name en index. Allen zijn verplicht,

 

Object ScoreScale

Het gegevensobject ScoreScale (Scoreschaal) omvat de definitiegegevens van een scoreschaal, en wordt in onderstaand figuur weergegeven.

In het gegevensobject ScoreScale bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor de Scoreschaal.

6c92d082- 0d03-4194-b352-988b2e6f9ae7

V

Deze identifier hoeft niet bekend te zijn bij de ontvanger.

name

string

string

Naam van de Scoreschaal die wordt/is gebruikt om scores in resultaten om te zetten.

 

O

De naam van de Scoreschaal is herkenbaar voor de medewerkers.

scoreScaleEntries

array

[ LHS , RHS ]

De items van scoreschaal in combi LHS en RHS die de scoreschaal definiëren.

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

V

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

Het formaat van LHS is een enkele getalswaarde ('x') of een bereik van twee getallen ('x-y'). In het eerste geval is de waarde de ondergrens van het interval. Bij het bereik zijn de getallen de onder- respectievelijk bovengrens van het interval. Intervallen zijn inclusief de grenswaarden.

RHS is een tekstuele waarde.

 

Status- en foutcodes

Voor alle APIs uit het Afsprakenstelsel Edu-V zijn de status- en foutcodes beschreven op de pagina Status- en foutcodes. Hierbij is onderscheid gemaakt in algemene en voor de API specifieke status- en foutcodes.

Mogelijke foutsituaties zijn:

  • De identifier van de onderwijsdeelnemer is onbekend.

  • De identifier van de onderwijsmedewerker is onbekend.

  • Een in het bericht opgenomen score is ongeldig gegeven de bijbehorende typering

  • Een in het bericht opgenomen resultaat is ongeldig gegeven de bijbehorende typering

Technisch: API specificatie


Release notes

  • 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:

    • Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van regie op gegevens en de M2M identificatie en authenticatie.

    • Het transactiepatroon melding bevestiging is toegepast voor het uitwisselen van het Result berichten. Dit heeft geresulteerd in PUT endpoint voor de meldingen voor de relevante referentiecomponent Cijferadministratie.

    • BasispoortIDs zijn toegevoegd als opties voor Onderwijsdeelnemer, Onderwijsmedewerker en School.

    • De status- en foutcodes zijn toegevoegd aan de documentatie en aan 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: Het bericht Score is toegevoegd. Tevens zijn er een bundel van toetsresultaten en een bundel van toetsscores toegevoegd. In de YAML zijn deze berichten geïmplementeerd in PUT (enkele score/resultaat) en POST (meerdere scores/resultaten) endpoints.

  • 0.0.5: GET endpoints om een resultaat of een score op basis van id op te vragen bij het Digitaal toetssysteem zijn aan de YAML toegevoegd. Dit stelt een cijferadministratie in staat om bij onduidelijkheid over de status van een resultaat of een score de laatste gegevens op te vragen.

  • 0.0.6: De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.

  • 0.0.7: De berichtdefinities zijn gewijzigd: de vier berichten score en resultaat (individueel en gebundeld) zijn gecombineerd tot 1 bericht met scores en resultaten van een toetsdeelnemer zoals door de werkgroep gewenst. Verwijzing naar cijferadministratie is weggepoetst.

  • 0.0.8: Correcties en verduidelijkingen aangebracht n.a.v. reviewcommentaren van de werkgroep. Naar aanleiding van bespreking zijn de volgende wijzigingen aangebracht:

    • Het object AssessmentScoresAndResults is uitgebreid met schoolPeriod, assessmentSystem en school,

    • Het object Assessment (Toetsdefinitie) is uitgebreid met toetsonderdelen in parts

    • Het object ScoreScale (Scoreschaal) is vervangen door definitie van meerdere scoreschalen in attribuut scoreScales binnen AssessmentScoresAndResults .

    • Het object StudenttScoresAndResults is uitgebreid met attributen dateCreated en dateLastModified,

    • Individuele score (in object Score) is uitgebreid met attribuut scoreMaximum en verwijzing naar betreffende toetsonderdeel (assessmentId) en scoreschaal (scoreScaleId).

    • Individueel resultaat (in object Result) is uitgebreid met verwijzing naar betreffende toetsonderdeel (assessmentId).

    • Resultaattypen uitgebreid met DLE.

    • Attribuut index (volgnummer) toegevoegd aan object AssessmentPart.

  • 0.0.9: Wijzigen in de architectuur zijn verwerkt:

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

    • Primaire en secundaire identifiers voor onderwijsaanbieders en eindgebruikers bijgewerkt.