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:

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.