Usage API

Titel

Usage API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.9.1

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:

Samenvatting

Gegevensdienst

  • Leermiddelactivatie

  • Leermiddelgebruik

Scopes

  • eduv.usage.seller (voor Bestelomgeving leermiddelen)

  • eduv.usage.entitlor (voor Aanspraakmanager)

  • eduv.usage.dashboard (voor Leermiddelendashboard)

Berichten

Objecten

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.