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 |
|
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 |
|
Berichten |
|
Producer |
|
Consumer |
|
Endpoints | Leermiddelenaanbieder
Leermiddelenshop
Leerportaalaanbieder
Dashboardaanbieder
|
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 | 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 | 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.