Usage API
Titel | Usage API |
Status | In ontwikkeling ROSA-Architectuurscan BEsluitvorming in beheer |
Versie | Documentatie: 0.0.7 |
schemaVersion: 0.0.6 | |
Datum | 24 April 2024 |
Auteur | Werkgroep Verwerven en in gebruik nemen |
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 |
|
Scopes |
|
Berichten | |
Objecten | |
Verzender/Bron |
|
Ontvanger | Voor gegevensdienst Leermiddelactivatie
|
Afnemer | Voor gegevensdienst Leermiddelgebruik:
|
Endpoints | Licentieregistratie
Aanspraakmanager
|
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 | 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 | 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. | 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 | 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 | V | Status conform de levenscyclus van de Aanspraak. |
school | object | referentie school | Referentie naar de identifier van de onderwijsorganisatie die het leermiddel verworven heeft | 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 | 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.