Entitlement API

Titel

Entitlement API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.0.9

schemaVersion: 0.0.6

Datum

24 April 2024

Auteur

Werkgroep Verwerven en in gebruik nemen

Acties

  • Geen openstaande acties

De Entitlement API wordt gebruikt om informatie over aanspraken te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Aanspraken en leermiddelactivatie met de Aanspraakmanager als Verzender.

Aanspraken vervullen een cruciale rol in de gesloten-geld-goederenstroom. Hierdoor is het cruciaal dat het verzenden, ontvangen en verwerken van de gegevens te traceren is. Daarnaast kent het opvolgen van een aanspraak door de Licentieregistratie en het Leermiddelenportaal een kritieke volgorde. Om deze reden wordt in de Entitlement API gebruik gemaakt van het transactiepatroon georkestreerde uitwisseling.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst

Aanspraken en leermiddelactivatie

Scopes

  • entitlement.seller (voor Bestelomgeving leermiddelen)

  • entitlement.licensor (voor Licentieregistratie)

  • entitlement.portal (voor Leermiddelenportaal)

  • entitlement.dashboard (voor Leermiddelendashboard)

Berichten

Bevestigings-berichten

Objecten

Verzender en bron

  • Aanspraakmanager

Ontvanger

  • Licentieregistratie

  • Leermiddelenportaal

Afnemer

  • Leermiddelendashboard

  • Leermiddelenportaal

  • Bestelomgeving leermiddelen

Endpoints

Aanspraakmanager

  • GET Entitlement by ID

  • GET All Entitlements by School ID

  • POST GET ALL Entitlement by User ID (eckId en userId worden via request body verstuurd)

  • PUT Confirm Entitlement

  • PUT Confirm ChangeLicenseStatus

Licentieregistratie

  • PUT Accept Entitlement

  • PUT Accept ChangeLicenseStatus request

Leermiddelenportaal

  • PUT Accept Entitlement

  • PUT Accept ChangeLicenseStatus request

Leermiddelendashboard

  • PUT Accept Entitlement

  • PUT Accept ChangeLicenseStatus request

Bericht: EntitlementRequest (Aanspraak)

Het EntitlementRequest bericht bevat de specificatie van de aanspraak op een leermiddel. In het bericht is een unieke referentie opgenomen om de traceerbaarheid van verzonden en ontvangen berichten bij te kunnen houden. Indien een ontvanger een bericht ontvangt met eenzelfde entitlementReferenceId is het niet de bedoeling om het Bericht opnieuw te verwerken. Het verzoek is om het bevestigingsbericht opnieuw toe te sturen.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

entitlement
ReferenceId

string

uuid

Referentienummer voor het versturen van de aanspraak.

eacb81ef-c9d5-4bd8-a624-4088bee04b73

V

Dit nummer wordt gebruikt door de event mediator om een logboek bij te houden van verzonden en ontvangen meldingen en terugmeldingen met betrekking tot een unieke entitlementId.

entitlement

object

entitlement

De specificatie van de aanspraak

Zie object Entitlement

V

 

Object: Entitlement

Het object Entitlement beschrijft de aanspraak zoals deze is aangemaakt op basis van de leverspecificatie uit een leveringsorder die door de Aanspraakmanager door een Bestelomgeving leermiddelen is ontvangen.

Iedere aanspraak heeft een status conform de levenscyclus van een Aanspraak. De waarden uit een aanspraak mogen niet gewijzigd worden (ook niet voor foutcorrecties). Indien de aanspraak niet correct is dan wordt deze geannuleerd en wordt er een nieuwe aanspraak gestuurd.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

entitlementId

string

uuid

Unieke identifier voor deze aanspraak

24e39454-5360-4ba4-819f-03e59b8dd679

V

Waarde mag niet gewijzigd worden

deliveryOrderId

string

uuid

Unieke identifier voor de leveringsorder waartoe de entitlement behoort.

24e39454-5360-4ba4-819f-03e59b8dd679

V

Waarde mag niet gewijzigd worden

contractId

string

string

Optionele unieke identifier van een contract tussen de leverancier van het leermiddel en de leverancier die de verwerving verzorgt.

2022-12-v1

O

Waarde mag niet gewijzigd worden.

productId

string

string

Referentie naar de Productbeschrijving in de Catalogue API van het leermiddel.

871792713
0834

V

Een aanspraak verwijst naar exact 1 Product-Beschrijving

Waarde mag niet gewijzigd worden

startDate

string

date

Datum vanaf wanneer het product in gebruik genomen kan worden. Dit is de start van de activatieperiode

2022-08-01

V

Waarde mag niet gewijzigd worden

activationUntilDate

string

date

Datum tot wanneer het product in gebruik genomen kan worden. Hierna is de activatieperiode verlopen

2023-07-31

V

Waarde mag niet gewijzigd worden

expirationDate

string

date

De expirationDate die door de het Leermiddelenportaal gehanteerd kan worden bij het beheren van toegangslinks.

In het eerste bericht wordt dit veld gebruikt met een minExpirationDate die door de Aanspraakmanager wordt bepaald.

2023-07-31

O

Deze waarde wordt berekend op basis van de informatie over het Product uit de catalogus. Voor een jaarlicentie is dit bijvoorbeeld 1 jaar na de startDate.

Dit veld is optioneel. Indien het veld leeg is, is er geen einddatum voor het tonen van de toegangslink.

De Aanspraakmanager kan via een InitialActivation bericht een nieuwe expirationDate doorkrijgen uit de Licentieregistratie.

In dat geval wordt het plaatsen van de toegangslink door het Leermiddelenportaal opnieuw geïnitieerd door de Aanspraakmanager.

Deze nieuwe expirationDate is gelijk aan of ligt verder in de toekomst en overschrijft voor de betreffende gebruiker de eerder berekende minExpiration
Date.

endDate

string

date

Datum dat de aanspraak geannuleerd of geblokkeerd is.

2022-09-28

O

De endDate wordt gevuld zodra de status wijzigt naar Cancelled of Blocked

Waarde mag niet gewijzigd worden

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 en entitlementSpecification

V

Waarde mag niet gewijzigd worden

entitlementSpecification

object

Entitlement
Specification

Specificatie van de waarden behorende bij het type aanspraak.

Zie entitlementType en entitlementSpecification

V

Waarde mag niet gewijzigd worden

entitlementStatus

string

ENUM

De status waarin de aanspraak zich bevindt.

created
entitled
licensed
cancelled
blocked

V

Status wordt toegekend conform de levenscyclus van de Aanspraak.

urlStatuses

array

UrlStatus

De status waarin de plaatsing van de toegangslink bij een Leermiddelenportaa applicatiel zich bevindt.

Zie object UrlStatus

V

De toegangslink kan bij meerdere portalen geplaatst zijn of worden.

dateCreated

string

datetime

Datum en tijdstip waarop de entiteit is aangemaakt

2017-07-21T17:32:28Z

V

 

dateLastModified

string

datetime

Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd

2022-08-11T15:31:12Z

V

 

objecten: EntitlementType en EntitlementSpecification

Een aanspraak betreft het recht om een digitaal leermiddel als individu in gebruik te nemen en te gaan gebruiken. Het type aanspraak specificeert op welke wijze een individu een leermiddel kan gaan activeren. We hanteren de volgende varianten.

Type aanspraak

Besteller

Licentieregistratie staat activering toe zodra:

school-student

Onderwijsorganisatie

De gespecificeerde onderwijsdeelnemer vanuit de gespecificeerde onderwijsorganisatie het leermiddel in gebruik gaat nemen.

school-employee

Onderwijsorganisatie

De gespecificeerde onderwijsmedewerker vanuit de gespecificeerde onderwijsorganisatie het leermiddel in gebruik gaat nemen.

school-activationcode

Onderwijsorganisatie

Een eindgebruiker vanuit de gespecificeerde onderwijsorganisatie het leermiddel in gebruik gaat nemen en hierbij de gespecificeerd en niet gebruikte activatiecode gebruikt.

customer-student

Particulier

De gespecificeerde onderwijsdeelnemer het leermiddel in gebruik gaat nemen.

customer-activationcode

Particulier

Een eindgebruiker die de gespecificeerde en niet gebruikte activatiecode gebruikt.

Voor ieder van de type aanspraken (entitlementType) geldt een eigen verplichte specificatie (entitlementSpecification) die opgenomen dient te worden in de aanspraak. De velden worden weergegeven in onderstaande tabel.

entitlementType

entitlementSpecification

school-student

school: referentie naar een onderwijsorganisatie

student: referentie naar een eindgebruiker

school-employee

school: referentie naar een onderwijsorganisatie

employee: referentie naar een eindgebruiker

school-activationcode

school: referentie naar een onderwijsorganisatie

activationCode: een activatiecode

customer-student

student: een referentie naar een eindgebruiker

customer-activationcode

activationCode: een activatiecode

object: UrlStatus

Het object UrlStatus geeft de status weer van de url zoals deze is verwerkt door een Leermiddelenportaal.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

portal

string

string

De identifier van de Leermiddelenportaal applicatie waar de toegangslink geplaatst is of dient te worden.

 

V

 

urlStatus

string

ENUM

De status waarin de plaatsing van de toegangslink bij het Leermiddelenportaal zich bevindt.

uninitialized
initialized
processed
cancelled
blocked

V

Status wordt toegekend conform de stap waarin het proces van plaatsen van toegangslinks zich bevindt.

Bevestigingsbericht: EntitlementConfirmation

De Licentieregistratie en het Leermiddelenportaal antwoorden op Entitlement berichten.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

entitlement
ReferenceId

string

uuid

De referentie van de Aanspraakmanager waarop dit bevestigingsbericht een antwoord is.

eacb81ef-c9d5-4bd8-a624-4088bee04b73

V

 

entitlement
ReceiveId

string

uuid

De referentie van de Licentieregistratie of het Leermiddelenportaal voor dit bevestigingsbericht

3437e98f-855d-4f29-9092-7ba311228920

V

 

entitlementId

string

uuid

Verwijzing naar de unieke identifier voor de aanspraak

24e39454-5360-4ba4-819f-03e59b8dd679

V

 

productId

string

string

Verwijzing naar de unieke identifier voor het product

871792713
0834

V

 

processed
Timestamp

string

datetime

Tijdstip waarop het aanspraak verzoek is verwerkt door de Licentieregistratie of het Leermiddelenportaal

2017-07-21T17:32:28Z

V

 

newEntitlement
Status

string

ENUM

De nieuwe status van de aanspraak

created
entitled
licensed
cancelled
blocked

V

De Licentieregistratie antwoordt via dit veld naar de Aanspraakmanager met een nieuwe status indien de verwerking succesvol was.

newUrlStatus

object

UrlStatus

De nieuwe status in het proces van plaatsen van toegangslinks door het Leermiddelenportaal

Zie object UrlStatus

V

Het Leermiddelenportaal antwoordt via dit veld naar de Aanspraakmanger met een nieuwe status indien de verwerking succesvol was.

success

boolean

boolean

Indicatie of de Aanspraakmanager het (wijzigings)bericht heeft kunnen verwerken

True
False

V

False indien de Ontvanger niet akkoord is of er een fout is opgetreden.

status

integer

ENUM

Status

0 (=OK)

V

Zie status en foutcodes

statusMessage

string

string

Toelichting op status

-

O

Zie status en foutcodes

Object: EntitlementProduct

Een Leermiddelenportaal kan bij een Aanspraakmanager de producten opvragen waar een Eindgebruik een aanspraak op heeft. Dit object bevat enkel informatie over het product, de status van de aanspraak en de datumvelden die van toepassing zijn op de activatie- en gebruiksperiode.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

entitlementId

string

uuid

Verwijzing naar de unieke identifier voor de aanspraak

24e39454-5360-4ba4-819f-03e59b8dd679

V

 

productId

string

string

Verwijzing naar de unieke identifier voor het product

871792713
0834

V

 

entitlementStatus

string

ENUM

De status waarin de aanspraak zich bevindt.

created
entitled
licensed
cancelled
blocked

V

Status wordt toegekend conform de levenscyclus van de Aanspraak.

startDate

string

date

Datum vanaf wanneer het product in gebruik genomen kan worden. Dit is de start van de activatieperiode

2022-08-01

V

Waarde mag niet gewijzigd worden

activationUntilDate

string

date

Datum tot wanneer het product in gebruik genomen kan worden. Hierna is de activatieperiode verlopen

2023-07-31

V

Waarde mag niet gewijzigd worden

expirationDate

string

date

De expirationDate die door de het Leermiddelenportaal gehanteerd kan worden bij het beheren van toegangslinks.

In het eerste bericht wordt dit veld gebruikt met een minExpirationDate die door de Aanspraakmanager wordt bepaald.

2023-07-31

O

Deze waarde wordt berekend op basis van de informatie over het Product uit de catalogus. Voor een jaarlicentie is dit bijvoorbeeld 1 jaar na de startDate.

Dit veld is optioneel. Indien het veld leeg is, is er geen einddatum voor het tonen van de toegangslink.

De Aanspraakmanager kan via een InitialActivation bericht een nieuwe expirationDate doorkrijgen uit de Licentieregistratie.

In dat geval wordt het plaatsen van de toegangslink door het Leermiddelenportaal opnieuw geïnitieerd door de Aanspraakmanager.

Deze nieuwe expirationDate is gelijk aan of ligt verder in de toekomst en overschrijft voor de betreffende gebruiker de eerder berekende minExpiration
Date.

Event mediator: Aanspraakmanager

De Event mediator van de Entitlement API van de Aanspraakmanager orkestreert aan de hand van het verzenden van Entitlement berichten en het ontvangen en verwerken van EntitlementConfirmation berichten het toekennen van aanspraken aan eindgebruikers en het plaatsen van toegangslinks in het Leermiddelenportaal.

Proces

Trigger

Actie

Output

Registratie

Leveren digitaal leermiddel

 

 

 

Een nieuwe DeliveryOrder die verwerkt dient te worden

Een nieuwe van een onderwijsdeelnemer op een opleidingsjaar of op een vak

Genereren Entitlement met entitlementStatus created

Versturen Entitlement in EntitlementRequest bericht naar Licentieregistratie

EntitlementRequest bericht

entitlementReferenceId
voor entitlementStatus created

EntitlementConfirmation
bevestigingsbericht van Licentieregistratie met newEntitlementStatus entitled

Wijzigen entitlementStatus van een Entitlement naar
entitled

 

entitlementReceiveId van Licentieregistratie

EntitlementConfirmation bevestigingsbericht van Licentieregistratie

Leermiddelenportaal laat plaatsing verzorgen door Aanspraakmanager.

Een Entitlement is gewijzigd van status naar entitled.

Wijzigen urlStatus van een Entitlement naar initialized

Versturen Entitlement in EntitlementRequest bericht naar Leermiddelenportaal

EntitlementRequest bericht

entitlementReferenceId
voor urlStatus initialized

EntitlementConfirmation
bevestigingsbericht van Licentieregistratie met newUrlStatus processed

Wijzigen urlStatus Entitlement naar
processed

 

entitlementReceiveId van Leermiddelenportaal

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal met foutcode

Notificeren support van Aanspraakmanager

Versturen Supportbericht inclusief foutcode

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal

entitlementReceiveId van Licentieregistratie of Leermiddelenportaal

Annuleren levering van digitaal leermiddel

 

 

 

Een DeliveryOrder wordt geannuleerd.

Een Onderwijsdeelnemer is niet meer ingeschreven op een opleidingsjaar of vak.

De aanspraak is gecontroleerd en heeft niet de status licensed

Wijzigen entitlementStatus Entitlement naar cancelled voor te versturen bericht naar Licentieregistratie

Wijzigen urlStatus Entitlement naar cancelled voor te versturen bericht naar Leermiddelenportaal

Versturen Entitlement in EntitlementRequest berichten naar Licentieregistratie en Leermiddelenportaal

Entitlement bericht

entitlementReferenceId
voor entitlementStatus en urlStatus cancelled

EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newEntitlementStatus cancelled

Wijzigen entitlementStatus van een Entitlement naar
cancelled

de endDate wordt toegevoegd aan de entitlement

-

EntitlementConfirmation bevestigingsbericht van Licentieregistratie

entitlementReceiveId van Licentieregistratie

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met newUrlStatus cancelled

Wijzigen urlStatus van een Entitlement naar cancelled

-

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal

entitlementReceiveId van Leermiddelenportaal

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal met foutcode

Notificeren support van Aanspraakmanager

Versturen Supportbericht inclusief foutcode

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal

entitlementReceiveId van Licentieregistratie of Leermiddelenportaal

Blokkeren aanspraak

 

 

 

Verzoek tot blokkeren van Entitlement

Wijzigen entitlementStatus Entitlement naar blocked voor te versturen bericht naar Licentieregistratie

Wijzigen urlStatus Entitlement naar blocked voor te versturen bericht naar Leermiddelenportaal

Versturen Entitlement in EntitlementRequest berichten naar Licentieregistratie en Leermiddelenportaal

Entitlement bericht

entitlementReferenceId
voor entitlementStatus en urlStatus blocked

EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newEntitlementStatus blocked

Wijzigen entitlementStatus van een Entitlement naar
blocked

de endDate wordt toegevoegd aan de entitlement

-

EntitlementConfirmation bevestigingsbericht van Licentieregistratie

entitlementReceiveId van Licentieregistratie

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met newUrlStatus blocked

Wijzigen urlStatus van een Entitlement naar blocked

-

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal

entitlementReceiveId van Leermiddelenportaal

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal met foutcode

Notificeren support van Aanspraakmanager

Versturen Supportbericht inclusief foutcode

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal

entitlementReceiveId van Licentieregistratie of Leermiddelenportaal

Deblokkeren aanspraak

Verzoek tot deblokkeren van Entitlement

Wijzigen entitlementStatus Entitlement naar vorige status entitled / licensed voor te versturen bericht naar Licentieregistratie

Wijzigen urlStatus Entitlement naar initialized voor te versturen bericht naar Leermiddelenportaal

Versturen Entitlement in EntitlementRequest berichten naar Licentieregistratie en Leermiddelenportaal

Entitlement bericht

entitlementReferenceId
voor entitlementStatus entitled / licensed en urlStatus initialized

EntitlementConfirmation bevestigingsbericht van Licentieregistratie met newEntitlementStatus entitled/ licensed

Wijzigen entitlementStatus van een Entitlement naar vorige status
entitled / licensed

de endDate wordt verwijderd uit de entitlement

-

EntitlementConfirmation bevestigingsbericht van Licentieregistratie

entitlementReceiveId van Licentieregistratie

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met newUrlStatus initialized

Wijzigen urlStatus van een Entitlement naar processed

-

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal

entitlementReceiveId van Leermiddelenportaal

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal met foutcode

Notificeren support van Aanspraakmanager

Versturen Supportbericht inclusief foutcode

EntitlementConfirmation bevestigingsbericht van Licentieregistratie of Leermiddelenportaal

entitlementReceiveId van Licentieregistratie of Leermiddelenportaal

In gebruik nemen digitaal leermiddel

InitialActivation bericht via de Usage API vanuit de Licentieregistratie

Optioneel is de expirationDate bijgewerkt voor de betreffende aanspraak.

Wijzigen entitlementStatus van Entitlement naar licensed

Indien het de eerste leermiddelactivatie binnen de DeliveryOrder betreft:

Wijzigen status van DeliveryOrder naar licensed en opstellen van DeliveryOrderConfirmation met newStatus licensed

Indien expirationDate is gewijzigd:

Bijwerken van de expirationDate op de Entitlement.

Wijzigen van urlStatus van Entitlement naar initialized

Versturen DeliveryOrderConfirmation naar Bestelomgeving leermiddelen

Versturen Entitlement in EntitlementRequest bericht naar Leermiddelenportaal

DeliveryOrderConfirmation bevestigingsbericht

deliveryOrderReceiveId voor newStatus licensed

Entitlement bericht

entitlementReferenceId
urlStatus initialized

EntitlementConfirmation
bevestigingsbericht van Leermiddelenportaal met newUrlStatus processed

Wijzigen urlStatus Entitlement naar
processed

 

entitlementReceiveId van Leermiddelenportaal

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal met foutcode

Notificeren support van Aanspraakmanager

Versturen Supportbericht inclusief foutcode

EntitlementConfirmation bevestigingsbericht van Leermiddelenportaal

entitlementReceiveId van Leermiddelenportaal

Event processor: Licentieregistratie

Bij het verwerken van Entitlement wordt gewerkt met terugmeldingen. Op deze manier zijn de activiteiten van de drie rollen die betrokken zijn in dit proces altijd te traceren. In onderstaande tabel is het gedrag van de Event processor van het Licentiekantoor beschreven.

Proces

Trigger

Actie

Output

Registratie

Leveren digitaal leermiddel

 

 

Entitlement in EntitlementRequest bericht met entitlementStatus
created

Verwerken van Entitlement conform entitlementType en entitlementSpecification

Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus
entitled

Versturen EntitlementConfirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus
processed of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status ordered

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newStatus processed | foutcode

Annuleren levering van digitaal leermiddel

Entitlement in EntitlementRequest bericht met entitlementStatus cancelled

Verwerken van annulering van Entitlement en het wijzigen van de entitlementStatus naar cancelled

Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus
cancelled

Versturen Entitlement
Confirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus
cancelled of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status cancelled

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newEntitlementStatus cancelled | foutcode

Blokkeren aanspraak

Entitlement in EntitlementRequest bericht met entitlementStatus
blocked

Verwerken van blokkering van Entitlement en het wijzigen van de entitlementSatus naar blocked

Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus
blocked

Versturen Entitlement
Confirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus
blocked of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status blocked

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newEntitlementStatus blocked | foutcode

Deblokkeren aanspraak

Entitlement in EntitlementRequest bericht met voorde blokkade van toepassing zijnde entitlementStatus
entitled / licensed

Verwerken van deblokkering van Entitlement en het wijzigen van de entitlementSatus naar entitled / licensed

Genereren EntitlementConfirmation bevestigingsbericht met newEntitlementStatus
entitled / licensed

Versturen Entitlement
Confirmation bevestigingsbericht naar Aanspraakmanager met newEntitlementStatus
entitled / licensed of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status entitled / licensed EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newEntitlementStatus entitled / licensed | foutcode

Event processor: Leermiddelenportaal

Bij het verwerken van Entitlement wordt gewerkt met bevestigingsberichten. Op deze manier zijn de activiteiten van de componenten die betrokken zijn in dit proces altijd te traceren. In onderstaande tabel is het gedrag van de Event processor van het Leermiddelenportaal toegelicht.

Proces

Trigger

Actie

Output

Registratie

Leveren digitaal leermiddel

 

 

Entitlement in EntitlementRequest bericht met urlStatus
initialized

Toegangslink naar product plaatsen voor eindgebruiker binnen aangegeven datumvelden.

Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus
processed

Versturen EntitlementConfirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus
processed of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status initialized

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newUrlStatus processed | foutcode

Annuleren levering van digitaal leermiddel

Entitlement in EntitlementRequest bericht met urlStatus cancelled

Toegangslink van product verwijderen voor eindgebruiker.

Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus
cancelled

Versturen Entitlement
Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus
cancelled of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status cancelled

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newUrlStatus cancelled | foutcode

Blokkeren aanspraak

Entitlement in EntitlementRequest bericht met urlStatus
blocked

Toegangslink van product verwijderen voor eindgebruiker.

Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus
blocked

Versturen Entitlement
Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus
blocked of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status blocked

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newUrlStatus blocked | foutcode

Deblokkeren aanspraak

Entitlement in EntitlementRequest bericht met urlStatus
initialized

Toegangslink naar product plaatsen voor eindgebruiker binnen aangegeven datumvelden.

Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus
processed

Versturen Entitlement
Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus
processed of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status initialized

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newUrlStatus processed | foutcode

In gebruik nemen digitaal leermiddel

Entitlement in EntitlementRequest bericht met urlStatus
initialized

Het veld van de expirationDate is gewijzigd.

De aanspraakmanager heeft dit veld gewijzigd op basis van een ontvangen InitialActivation bericht van de Licentieregistratie.

Toegangslink naar product plaatsen voor eindgebruiker binnen aangegeven datumvelden. De link blijft actief tot en met de nieuwe waarde in de expirationDate.

Genereren EntitlementConfirmation bevestigingsbericht met newUrlStatus
processed`

Versturen Entitlement
Confirmation bevestigingsbericht naar Aanspraakmanager met newUrlStatus
processed of indien verwerking niet succesvol met foutcode

EntitlementRequest bericht van Aanspraakmanager

entitlementReferenceId
voor status initialized

EntitlementConfirmation bevestigingsbericht

entitlementReceiveId voor newUrlStatus processed | foutcode

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:

    • Endpoint toegevoegd waarin entitlements voor een onderwijsdeelnemer of onderwijsmedewerker opgevraagd kunnen worden.

    • Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van het regie op gegevens en de M2M identificatie en authenticatie.

    • Het transactiepatroon georkestreerde uitwisseling met een opeenvolging van asynchrone uitwisselingen is toegepast op de Entitlement API. Dit heeft geresulteerd in PUT endpoints voor de meldingen en de terugmeldingen (confirmations) 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. Objecten ChangeLicenseStatus en ChangeLicenseStatusConfirmation toegevoegd.

  • 0.0.6: YAML file aangepast. Endpoints voor activatiecode verwijderd en verplaatst naar de ActivationCode API.

  • 0.0.7: Typo’s verwijderd uit de YAML file.

  • 0.0.8: 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. Dit heeft geleid tot de status van een aanspraak en de status van de plaatsing van de links in het leermiddelenportaal.

    • Er zijn GET endpoints toegevoegd voor het Leermiddelendashboard

    • Er zijn GET endpoints toegevoegd voor het Leermiddelenportaal om aanspraken en producten uit aanspraken op te vragen voor een specifieke eindgebruiker.

    • Er zijn GET endpoints toegevoegd voor de Bestelomgeving leermiddelen en de Licentieregistratie om aanspraken op basis van een leveringsorderId en contractId op te vragen.

    • Het transactiepatroon voor het Leermiddelendashboard is gewijzigd naar een Bevraging. Het Leermiddelendashboard ontvang geen meldingen meer vanuit de Aanspraakmanager en speelt geen rol meer in de georkestreerde uitwisseling.

    • De scopes zijn aangepast met een specifieke scope voor de gegevensafnemende referentiecomponenten: Bestelomgeving leermiddelen, Licentieregistratie, Leermiddelendashboard en Leermiddelenportaal.

  • 0.0.9: 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.

    • Feedback vanuit de werkgroep Verwerven en in gebruik nemen:

      • Attribuut urlStatus is vervangen door urlStatusses met een verwijzing naar de urlStatus per Portaal.

      • Endpoint entitlementproducts/school/user is hernoemd naar entitlements/school/user/products

  • 0.0.10: / achter endpoints verwijderd.