Usage API

Titel	Usage API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 0.9.1
Versie	schemaVersion: 0.9.1
Datum	27 September 2024
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Geen openstaande acties

De Usage API wordt gebruikt om informatie over leermiddelactivatie en leermiddelgebruik te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdiensten Aanspraken en leermiddelactivatie en Leermiddelactivatie en leermiddelgebruik met de Licentieregistratie als Verzender of Bron.

Het in gebruik nemen van een leermiddel heeft als gevolg dat dit leermiddel niet meer geannuleerd kan worden door een Aanspraakmanager. Om deze reden wordt de leermiddelactivatie vanuit de licentieregistratie naar de Aanspraakmanager toegestuurd middels een melding.

In aanvulling hierop kunnen leermiddelen verworven worden met een businessmodel waarbij gegevens over leermiddelgebruik noodzakelijk zijn voor het proces van betalen. Een voorbeeld is een abonnement op basis van maandelijks actieve gebruikers. De Licentieregistratie deelt hiervoor leermiddelengebruik met de Bestelomgeving leermiddelen. De Bestelomgeving leermiddelen kan deze gegevens opvragen bij de Licentieregistratie.

In het Leermiddelendashboard kunnen de leermiddelactivatie en leermiddelgebruik benut worden om onderwijsmedewerkers een totaaloverzicht te geven over het gebruik van verworven leermiddelen aangeschaft via meerdere Bestelomgevingen leermiddelen. Het Leermiddelendashboard kan deze informatie opvragen bij de Licentieregistratie.

De technische specificatie bestaat uit:

1 Samenvatting
2 Bericht: InitialActivation (Leermiddelactivatie)
3 Object: EntitlementUsage
- 3.1 Object: Usage
4 Object: DeliveryOrderUsage
5 Event mediator: Licentieregistratie
6 Event processor: Aanspraakmanager
7 Status- en foutcodes
8 Technisch: API specificatie
9 Release notes

Samenvatting

Gegevensdienst	Leermiddelactivatie Leermiddelgebruik
Scopes	eduv.usage.seller (voor Bestelomgeving leermiddelen) eduv.usage.entitlor (voor Aanspraakmanager) eduv.usage.dashboard (voor Leermiddelendashboard)
Berichten	InitialActivation
Objecten	EntitlementUsage DeliveryOrderUsage
Verzender/Bron	Licentieregistratie
Ontvanger	Voor gegevensdienst Leermiddelactivatie Aanspraakmanager
Afnemer	Voor gegevensdienst Leermiddelgebruik: Bestelomgeving leermiddelen Leermiddelendashboard
Endpoints	Licentieregistratie GET Get Usage by Entitlement GET Get Usage by DeliveryOrder GET Get Usage for School POST Get Usage for User at School GET Get Usage by Contract Aanspraakmanager PUT Accept InitialActivation from Licentieregistratie

Bericht: InitialActivation (Leermiddelactivatie)

Het bericht InitialActivation wordt door de Licentieregistratie naar de Aanspraakmanager gestuurd bij in gebruik name van een leermiddel. Dit bericht is een bevestiging vanuit de Licentieregistratie aan de Aanspraakmanager dat een aanspraak in gebruik is genomen en een licentie is aangemaakt.

In dit bericht wordt optioneel een nieuwe expirationDate toegevoegd indien deze afhankelijk is van het moment van in gebruik nemen van het leermiddel. Dit is bijvoorbeeld van toepassing zodra een licentie een looptijd heeft van 1 jaar na in gebruik name. De looptijd is hierdoor voor ieder van de eindgebruikers anders.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlementId	string	uuid	Unieke identifier voor de entitlement		V	In gebruik name wordt gekoppeld aan exact 1 entitlement
productId	string	string	Identifier van het leermiddel	871792713 0834	V
entitlementType	string	ENUM	Het type aanspraak beschrijft op welke wijze een individu een aanspraak kan activeren. Dit kan met behulp van een ID of een activatiecode en al dan niet vanuit een onderwijsorganisatie.	Zie entitlementType in de Entitlement API	V
school	object	referentie school	Referentie naar de identifier van de onderwijsorganisatie die het leermiddel verworven heeft	Zie referentie naar school	O*	Indien de aanspraak behoort tot een leveringsorder van een school dan is deze waarde gevuld.
user	object	referentie eindgebruiker	Referentie naar de eindgebruiker die het leermiddel in gebruik heeft genomen.	Zie referentie eindgebruiker	V	de primaire identifier, of indien deze niet aanwezig is, een secundaire identifier, van de eindgebruiker die het product in gebruik heeft genomen.
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 aanspraak een minExpirationDate waarde gevuld was, dan is de waarde in dit veld gelijk aan of verder in de toekomst.

Object: EntitlementUsage

Het object EntitlementUsage bevat gebruiksgegevens met betrekking tot de aanspraak. Dit object wordt niet via berichten verstuurd naar de aanspraakmanager en is op te vragen via de GET endpoints van de Licentieregistratie.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
entitlementId	string	uuid	Unieke identifier voor de entitlement		V	In gebruik name wordt gekoppeld aan exact 1 entitlement
productId	string	string	Identifier van het leermiddel	871792713 0834	V
entitlementType	string	ENUM	Het type aanspraak beschrijft op welke wijze een individu een aanspraak kan activeren. Dit kan met behulp van een ID of een activatiecode en al dan niet vanuit een onderwijsorganisatie.	Zie entitlementType in de Entitlement API	V
entitlementStatus	string	ENUM	De status waarin de aanspraak zich bevindt.	entitled licensed expired cancelled blocked	V	Status conform de levenscyclus van de Aanspraak.
school	object	referentie school	Referentie naar de identifier van de onderwijsorganisatie die het leermiddel verworven heeft	Zie referentie naar school	O*	Indien de aanspraak behoort tot een leveringsorder van een school dan is deze waarde gevuld.
user	object	referentie eindgebruiker	Referentie naar de eindgebruiker die het activatie- en gebruiksrecht heeft op het leermiddel	Zie referentie eindgebruiker	V	de primaire identifier, of indien deze niet aanwezig is, een secundaire identifier, van de eindgebruiker die het product in gebruik heeft genomen.
activationCode	string	string	Activatiecode die is gehanteerd bij de in gebruik name	XXXXXX	O*	Verplicht zodra leermiddel in gebruik is genomen met een activatiecode
expirationDate	string	Date	Datum dat de licentie op het leermiddel verloopt voor de eindgebruiker	2023-07-31	O	Waard is verplicht zodra de status licensed is.
usage	object	usage	De leermiddelactivatie en het leermiddelgebruik dat is geregistreerd op deze aanspraak	Zie object Usage	V	Waarde is verplicht om in te vullen

Object: Usage

Het object Usage beschrijft het moment van de leermiddelactivatie en het leermiddelgebruik van een product door een eindgebruiker.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
firstUsed	string	datum	Datum van in gebruik name van het product	2022-09-12	V
lastUsed	string	datum	Datum van laatste gebruik	2022-09-12	O
frequencyOfUsage	integer	integer	Indicator voor hoe frequent het leermiddel door de eindgebruiker is gebruikt	90	O

Object: DeliveryOrderUsage

Het object DeliveryOrderUsage aggregeert alle gebruiksgegevens van aanspraken voor een leveringsorder. Dit object wordt niet via berichten verstuurd naar de aanspraakmanager en is op te vragen via de GET endpoints van de Licentieregistratie.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
deliveryOrderId	string	uuid	Unieke identifier voor de leveringsorder		V	In gebruik name wordt gekoppeld aan exact 1 entitlement
totalEntitled	integer	integer	Het aantal aanspraken met de status entitled	10	O	Optionele veld gebaseerd op statusinformatie uit de EntitlementUsage
totalLicensed	integer	integer	Het aantal aanspraken met de status licensed	40	O	Idem
totalCancelled	integer	integer	Het aantal aanspraken met de status cancelled	3	O	Idem
totalBlocked	integer	integer	Het aantal aanspraken met de status blocked	0	O	Idem
totalExpired	integer	integer	Het aantal aanspraken met de status expireer	0	O	Idem
entitlements	array	EntitlementUsage	Een array met de objecten EntitlementUsage die onder de leveringsorder vallen	Zie EntitlementUsage	V	Waarde is verplicht om in te vullen

Event mediator: Licentieregistratie

Het InitialActivation bericht wordt direct nadat een leermiddel in gebruik is genomen verstuurd naar de Aanspraakmanager.

Event processor: Aanspraakmanager

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

De status van de aanspraak wordt gewijzigd naar licensed en indien de expirationDate is aangepast door de Licentieregistratie dan wordt het plaatsen van de toegangslink in het Leermiddelenportaal opnieuw geïnitieerd. Ook verstuurd de Aanspraakmanger bij de eerste leermiddelactivatie van een aanspraak in een leveringsorder een bevestigingsbericht naar de Bestelomgeving leermiddelen.

Deze stappen zijn toegelicht als onderdeel van de Event Mediator van de Aanspraakmanager in de Entitlement API.

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.

Technisch: API specificatie

Release notes

0.0.1: Eerste draft van de API.
0.0.2: Objecten 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 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.
0.0.5: Objecten geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader.
0.0.6: De objecten en koppelvlakspecificatie inclusief de YAML zijn aangepast naar het nieuwe conceptueel model. Dit heeft geleid tot de volgende wijzigingen:
- Aanspraken zijn van toepassing voor een enkele eindgebruiker. De voorheen open aanspraakvarianten zijn verplaatst naar de leveringsorders in de Delivery API
- Aanspraken zijn er nog steeds in typen. De typen variëren vanuit de beoogde gebruiker: onderwijsdeelnemer, onderwijsmedewerker en een eindgebruiker met een activatiecode. Daarnaast zijn er aanspraken die toebehoren aan een onderwijsorganisatie.
- De statusinformatie van aanspraken is gewijzigd en de statusinformatie van licenties is verwijderd. Een aanspraak is voor een enkele eindgebruiker en heeft nu een status van entitled, licensed en expired.
- Het transactiepatroon voor het Leermiddelendashboard en de Bestelomgeving leermiddelen is gewijzigd naar een Bevraging. Het Leermiddelendashboard ontvang geen meldingen meer vanuit de Licentieregistratie.
- Er zijn GET endpoints toegevoegd voor het Leermiddelendashboard
- Er zijn GET endpoints toegevoegd voor de Bestelomgeving leermiddelen en de Aanspraakmanager om usage informatie op basis van een leveringsorderId en contractId op te vragen.
- De scopes zijn aangepast met een specifieke scope voor de gegevensafnemende referentiecomponenten: Bestelomgeving leermiddelen, Aanspraakmanager en Leermiddelendashboard.
0.0.7: Er zijn wijzigingen verwerkt:
- Wijzigen in de architectuur:
  - Attribuut schemaVersion is verwijderd uit de objecten.
  - Query parameter schemaVersion is verwijderd uit de koppelvlakken.
  - Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
  - Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
  - Primaire en secundaire identifiers voor onderwijsaanbieders en eindgebruikers bijgewerkt.
  - / achter endpoints verwijderd.
0.9.0: Het Bestuurlijk Overleg heeft tijdens de bijeenkomst van 27 juni 2024 het Afsprakenstelsel Edu-V als versie 0.9.0 goedgekeurd voor implementatie.
0.9.1: Wijzigingen naar aanleiding van RFC’s:
- Op basis van RFC002 is de scope aangepast met een prefix eduv.. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.
- De parameters voor paginering zijn uit de koppelvlakspecificatie verwijderd. Binnen het afsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.
- De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.