Usage API

Titel	Usage API
Status	DRAFT WERKGROEP KLANKBORDgroep ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT
Stadium	POC PILOT BEHEER
Versie	0.0.4
Datum	12 Juli 2023
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Toevoegen van bericht dat verstuurd kan worden bij het verlopen van een abonnement dat periodiek wordt verlengd (status expired).

De Usage API wordt gebruikt om informatie over in gebruik name en gebruiksgegevens uit te wisselen tussen de Leermiddelenaanbieder, Leermiddelenshop, Leerportaalaanbieder en de Dashboardaanbieder. Deze informatie is noodzakelijk voor een gesloten geldgoederenstroom. Nadat een Leermiddel in gebruik is genomen door een (eerste) Onderwijsdeelnemer (of -medewerker) dan is de bestelling niet meer te annuleren.

In aanvulling hierop kunnen Leermiddelen verworven worden met een businessmodel waarbij daadwerkelijke gebruiksgegevens noodzakelijk zijn voor het proces van betalen. Een voorbeeld is een abonnement op basis van maandelijks actieve gebruikers. De Leermiddelenaanbieder deelt hiervoor gebruiksgegevens met de Leermiddelenshop.

In de component Overkoepelend dashboard gebruik van de Dasbhoardaanbieder kunnen de in gebruik name gegevens en de gebruiksgegevens benut worden om Onderwijsmedewerkers een totaaloverzicht te geven over het gebruik van verworven leermiddelen aangeschaft via meerdere Leermiddelenshops.

De technische specificatie bestaat uit:

1 Samenvatting
2 Berichtdefinitie: InitialActivation (in gebruik name)
3 Berichtdefinitie: Usage
4 Event mediator: Leermiddelenaanbieder (Licentiekantoor)
5 Event processor: Leermiddelenshop (Faciliteit voor leveren (of arrangeren) van digitale leermiddelen)
6 Event processor: Leerportaalaanbieder (Mijn leermiddelen)
7 Status- en foutcodes
8 Technisch: API specificatie
9 Release notes

Samenvatting

Scopes	la.usage.activation ls.usage.usage
Berichten	InitialActivation Usage
Producer	Leermiddelenaanbieder – Licentiekantoor
Consumer	Leermiddelenshop – Faciliteit voor leveren (of arrangeren) van digitale leermiddelen Leerportaalaanbieder – Mijn leermiddelen Dashboardaanbieder – Overkoepelend dashboard gebruik
Endpoints	Leermiddelenaanbieder GET Get usage by Entitlement POST Get Usage by Individual Leermiddelenshop PUT Initial Activation of Product BUITEN SCOPE POC PUT Usage on Product Leerportaalaanbieder PUT Initial Activation of Product Dashboardaanbieder PUT Initial Activation of Product BUITEN SCOPE POC PUT Usage on Product

Berichtdefinitie: InitialActivation (in gebruik name)

Het bericht InitialActivation wordt door de Leermiddelenaanbieder naar de Leermiddelenshop en de Leerportaalaanbieder en optioneel de Dashboardaanbieder gestuurd bij in gebruik name van een Leermiddel. Dit bericht is een bevestiging vanuit de Leermiddelenaanbieder aan de Leermiddelenshop dat een aanspraak in gebruik is genomen en een licentie is aangemaakt.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlementId	string	uuid	Unieke identifier voor de entitlement waar de in gebruik name betrekking op heeft.		V	In gebruik name wordt gekoppeld aan exact 1 entitlement
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
productId	string	string	Identifier van het Leermiddel dat door de onderwijsdeelnemer of de onderwijsmedewerker in gebruik is genomen.	871792713 0834	O*	Waarde is verplicht zodra de Entitlement een aanspraak op een Product betreft met meerdere digitale producten, bijvoorbeeld een combiproduct of een set van digitale leermiddelen.
schoolId	string	string	Referentie naar de identifier van de onderwijsorganisatie die de Entitlement verworven heeft	-	O*	Waarde is verplicht indien de Besteller van de entitlement een Onderwijsorganisatie is. In het primair onderwijs wordt het BasispoortId gehanteerd. In het voortgezet onderwijs en middelbaar beroepsonderwijs wordt het digiDeliveryId (case sensitive) gehanteerd.
eckId	string	ECK iD	Het ECK iD van de onderwijsdeelnemer of de onderwijsmedewerker	-	V*	eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	Zie object userId in SIS API	O*	Verplicht zodra eckId onbekend is.
activationCode	string	string	Activatiecode die is gehanteerd bij de in gebruik name	XXXXXX	O*	Verplicht zodra leermiddel in gebruik is genomen met een activatiecode
usageDate	string	datum	Datum van in gebruik name van het product	2022-09-12	V	Waarde is verplicht
usageType	string	ENUM	Type gebruiksgegeven	initial-activation	V	In het geval van een in gebruik name is de waarde InitialActivation
expirationDate	string	Date	Datum dat de licentie op het Leermiddel verloopt voor deze onderwijsdeelnemer of onderwijsmedewerker	2023-07-31	V	Waarde is verplicht om in te vullen bij InitialActivation event Indien in de Entitlement de waarde minExpirationDate is gevuld dan is de waarde in dit veld gelijk aan of verder in de toekomst. Waarde mag niet gewijzigd worden

Berichtdefinitie: Usage

Zodra een Leermiddel in gebruik is genomen door een onderwijsdeelnemer of -medewerker, dan heeft de Leermiddelenaanbieder de mogelijkheid om vervolggebruik te delen met de Leermiddelenshop en de Dasbhoardaanbieder. De Leermiddelenshop kan deze informatie bijvoorbeeld gebruiken voor het maandelijks factureren op basis van actieve gebruikers. De Dasbhoardaanbieder kan in een overkoepelend dashboard gebruik aan Onderwijsmedewerkers, veelal in de functie van leermiddelencoördinator of inkoper, de frequentie van gebruik van leermiddelen door onderwijsdeelnemers en -medewerkers tonen.

De opbouw van het Usage bericht is gelijk aan het InitialActivation bericht, het verschil zit in de waarde voor het veld usageType.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlementId	string	uuid	Unieke identifier voor de entitlement waar de in gebruik name betrekking op heeft.		V	In gebruik name wordt gekoppeld aan exact 1 entitlement
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
productId	string	string	Identifier van het Leermiddel dat door de onderwijsdeelnemer of de onderwijsmedewerker in is gebruikt.	871792713 0834	O*	Waarde is verplicht zodra de Entitlement een aanspraak op een Product betreft met meerdere digitale producten, bijvoorbeeld een combiproduct of een set van digitale leermiddelen.
schoolId	string	string	Referentie naar de identifier van de onderwijsorganisatie die de Entitlement verworven heeft	-	O*	Waarde is verplicht indien de Besteller van de entitlement een onderwijsorganisatie is. In het primair onderwijs wordt het BasispoortId gehanteerd. In het voortgezet onderwijs en middelbaar beroepsonderwijs wordt het digiDeliveryId (case sensitive) gehanteerd.
eckId	string	ECK iD	Het ECK iD van de onderwijsdeelnemer of de onderwijsmedewerker	-	V*	eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	Zie object userId in SIS API	O*	Verplicht zodra eckId onbekend is.
usageDate	string	datum	Datum van (laatste) gebruik van product	2022-09-15	V	Waarde is verplicht
usageType	string	ENUM	Type gebruiksgegeven	unique-usage weekly-usage monthly-usage	V	In het geval van een gebruiksgegeven wordt één van de typen genoemd.
expirationDate	string	Date	Datum dat de licentie op het Leermiddel verloopt voor deze onderwijsdeelnemer of onderwijsmedewerker	2023-07-31	V	Waarde is conform de waarde uit het InitialActivation event. Waarde mag niet gewijzigd worden

Event mediator: Leermiddelenaanbieder (Licentiekantoor)

Het InitialActivation bericht wordt direct nadat een nieuwe Licentie is aangemaakt in het Licentiekantoor verstuurd naar de componenten:

Faciliteit voor leveren (of arrangeren) van digitale leermiddelen van de Leermiddelenshop
Mijn leermiddelen van de Leerportaalaanbieder

Event processor: Leermiddelenshop (Faciliteit voor leveren (of arrangeren) van digitale leermiddelen)

Na ontvangen van een InitialActivation bericht wordt de in gebruik name geregistreerd bij de Aanspraak. Vanaf de eerste in gebruik name is de Entitlement niet meer te annuleren door de Leermiddelenshop.

Event processor: Leerportaalaanbieder (Mijn leermiddelen)

Na ontvangen van een InitialActivationbericht wordt in het beheer van Toegangslinks de expirationDate gehanteerd als einddatum tot wanneer een Toegangslink actief is voor een Onderwijsdeelnemer (of -medewerker).

Status- en foutcodes

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	School unknown	De identifier van de onderwijsorganisatie is onbekend.
404	7	User unknown	De identifier van de onderwijsdeelnemer of onderwijsmederker is onbekend.
404	8	Entitlement unknown	De identifier van de Aanspraak is onbekend.
400	99	Vullingsregel: in statusMessage een beschrijving van de reden opnemen	Overige reden

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 het activeren en deactiveren van gegevensuitwisselingen en de M2M identificatie en authenticatie.
- Het transactiepatroon melding bevestiging is toegepast voor het uitwisselen van de IntialActivation en Usage berichten. Dit heeft geresulteerd in PUT endpoints voor de meldingen voor de relevante referentiecomponenten.
- BasispoortIDs zijn toegevoegd als opties voor Onderwijsdeelnemer, Onderwijsmedewerker en School.
- 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: De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.