DISTRIBUTIE EN TOEGANG VAN DIGITALE LEERMIDDELEN Deel II: Functioneel en Technisch model

DISTRIBUTIE EN TOEGANG VAN DIGITALE LEERMIDDELEN Deel II: Functioneel en Technisch model Distributie van en toegang tot digitale leermiddelen in de educatieve contentketen

Auteur(s)

:

Wijnand Derks Erwin Reinhoud

Versienummer

:

Totstandkoming :

Zie documentgeschiedenis Dit document is tot stand gekomen in samenwerking met vertegenwoordigers van aanbieders en afnemers van digitale leermiddelen

© 2012 Kennisnet, SLO, GEU

2 / 68

Deel II: Functioneel en Technisch model december 2012

Documentgeschiedenis Versie

Datum

Omschrijving

0.9

25 november 2011

Eerste versie van de referentiearchitectuur.

0.91

13 december 2011

Verdere inpassing in ECK-sjabloon.

0.92

Inhoudelijke aanpassingen.

0.93

19 januari 2012

Aanpassingen Deel II en figuur 3.1

0.94

20 januari 2012

Invoegen Deel I v0.93 (versie GEU) en diversen.

0.95

31 januari 2012

Diverse wijzigingen, met name rond Identiteitsverstrekker en ProfileService.

0.96/7

10 februari 2012

Aanpassingen obv korte consultatieronde.

0.98

13 april 2012

Aanpassingen nav afspraken LiMBO-programma

1.0

-

Deze versie is niet verschenen, omdat er geen afgestemde tussenversie is gecreëerd.

1.1

2 mei 2012

Eerste volledige versie (met de technische specificaties in bijlagen)

1.11

4 mei 2012

Introductie van de concepten Eenheid en Contract nav gesprek met ThiemeMeulenhoff

1.2

18 mei 2012

Vertaling van ICT-gerelateerde onderdelen in Functioneel en Technisch model naar het Engels.

1.21

22 mei 2012

Wijzigingen in vertalingen naar Engels verwerkt.

1.3

24 mei 2012

Aanpassingen o.b.v. input GEU (w/o Catalogusservice) Eerste volledige concept voor ketenbrede consultatie d.d. 5 juni 2012

1.4

22 juni 2012

Aanpassingen o.b.v. feedback ketenbrede consultatie d.d. 5 juni 2012 en afstemming met GEU, Van Dijk Educatie, Kennisnetfederatie.

1.41

29 juni 2012

Document gesplitst in twee delen, t.w.: •

Definities en Procesmodel (toelichting bij basisafspraak)

• 1.5

20 december 2012

Functioneel en Technisch model (basisafspraak)

Aanvullingen van Malmberg, m.n. t.b.v. autorisaties (via ProfileService) en Service-resolutie. Tevens ketenbreed unieke identifiers (UserId, UnitId e.d.) expliciet opgebouwd uit lokale identifier en identifier van de Administratie. Profielgegevens uitgebreid met initialen en fysieke adresgegevens. Identificatie van Tegoeden eenduidig gemaakt. CouponCode toegevoegd aan OrderService. AccountService: AuthenticateUser verwijderd omdat het een interne functie betreft. RequestAuthentication vernoemd naar de SAML-naam AuthnRequest.

3 / 68


Inhoudsopgave Documentgeschiedenis

2

Inhoudsopgave

3

1.

5

1.1

Inleiding Aanleiding

1.2

Waarom een referentiearchitectuur?

1.3

Voordelen van een brede afspraak over distributie en toegang

1.4

De afspraak

1.5

Doelstelling

1.6

Afbakening

1.7

Toepasselijkheid

1.8

Opbouw

1.9 2.

Leeswijzer Functioneel model (I)

2.1

AccountService

2.2

ProfileService

2.3

ProductListService

2.4

EducationalContentListService

2.5

OrderService

2.6

PaymentService

2.7

DistributionService

2.8 2.9

LicenseService

2.10 3.

3.1 3.2 3.3 3.4 3.5 3.6 3.7

EntryLocationService EducationalContentService

Technisch model (T) Identificatie Gebruikers identificeren, authenticeren en ophalen van profielinformatie Authenticatie van Ketenpartners Beveiliging web service koppelvlakken Web service standaarden Diakrieten, de tekenset en encoding Foutafhandeling

5 5 5 5 5 5 6 6 6

7 9

12 18 23 28 33 35 40 42 47 48 48 49 51 51 52 53 54

4.

Vrijwaring gebruik afspraak

55

5.

Bronnen

56

Bijlage: Deelnemers aan het standaardisatieproces

57

Bijlage: Algemene web service specificaties

59

Bijlage: ProfileService web service specificatie

60

Bijlage: AccountService web service specificatie

61

Bijlage: ProductListService web service specificatie

62

4 / 68


Bijlage: EducationalContentListService web service specificatie

63

Bijlage: OrderService web service specificatie

64

Bijlage: PaymentService web service specificatie

65

Bijlage: DistributionService web service specificatie

66

Bijlage: LicenseService web service specificatie

67

Bijlage: EntryLocationServicehuis web service specificatie

68


1. Inleiding 1.1

Aanleiding

Digitale leermiddelen nemen ieder jaar een belangrijkere plaats in op de leermiddelenlijst van onderwijsinstellingen. Nu scholen steeds meer vertrouwen op digitale leermiddelen voor hun primaire onderwijsproces, wordt het steeds belangrijker dat deze leermiddelen ook tijdig beschikbaar zijn in de klas. 1.2

Waarom een referentiearchitectuur?

Voor een foutloze distributie en toegang zijn de LAS- en ELO-leveranciers, distributeurs en uitgeverijen onderling afhankelijk van elkaar. Hiermee ontstaat de noodzaak om afspraken te maken over de samenwerking. 1.3

Voordelen van een brede afspraak over distributie en toegang

Een ketenbrede afspraak heeft als voordeel dat partijen eenvoudiger met elkaar kunnen samenwerken. Hierdoor wordt het voor ketenpartijen makkelijker om hun toegevoegde waarde binnen de keten te realiseren. Dit levert betere kwaliteit en lagere kosten voor iedereen, en in het bijzonder de scholen. 1.4

De afspraak

De afspraak omvat een referentiearchitectuur met daarin een lijst van begrippen, een procesmodel, functioneel model en technisch model. Ieder model kent een aantal principes die richtinggevend zijn voor marktoplossingen. De referentiearchitectuur vormt een basis voor dienstverlening door marktpartijen. 1.5

Doelstelling

De afspraak dient ervoor om de gewenste vormen van dienstverlening mogelijk te maken. Voor de gewenste vormen van dienstverlening verwijzen we naar de ECK-DTDL-wensenlijst [1] en het pakket van eisen van het LiMBO-programma [2]. 1.6

Afbakening

De referentiearchitectuur bestrijkt het volgende domein binnen de educatieve contentketen: •

•

•

1

De referentiearchitectuur beschouwt web-gebaseerd digitale leermiddelen die onder licentie wordt uitgegeven, al dan niet tegen vergoeding. De referentiearchitectuur beoogd wel compatibel te zijn met de werkwijzen rondom fysieke leermiddelen. De referentiearchitectuur beoogt wel compatibel te zijn met de werkwijzen rondom fysieke leermiddelen. De distributie en toegang van digitale leermiddelen omvat de processen en systemen van het bepalen van de leermiddelenlijst tot en met het moment van toegang van de gebruiker tot het digitaal leermateriaal. De referentiearchitectuur is van toepassing op digitale leermiddelen voor het primair onderwijs1 (PO), voortgezet onderwijs (VO) en middelbaar beroepsonderwijs (MBO).

Het primair onderwijs is beperkt betrokken geweest bij de totstandkoming van deze versie van de

referentiearchitectuur. Dientengevolge kan voor deze sector de referentiearchitectuur vooralsnog niet als richtinggevend worden beschouwd.

5 / 68


1.7

Toepasselijkheid

De referentiearchitectuur is als volgt van toepassing: •

•

•

1.8

De referentiearchitectuur is van toepassing op alle organisaties die betrokken zijn bij distributie en toegang van digitaal leermateriaal in de educatieve contentketen, waaronder scholen en instellingen, leveranciers van voorzieningen, distributeurs en overige handelspartijen en uitgeverijen. De referentiearchitectuur is van toepassing op de samenwerking tussen deze organisaties. De referentiearchitectuur is niet van toepassing op inrichting en/of werkwijzen binnen organisaties. Organisaties zijn niet verplicht alle functionaliteit van de referentiearchitectuur aan te bieden of te gebruiken. Opbouw

De referentiearchitectuur omvat de volgende onderdelen: Deel I: Definities en Procesmodel • •

Definities: omvat de begrippen die in deze afspraak worden gebruikt, Procesmodel: omvat de processtappen en werkingsprincipes binnen de distributie en toegangsketen.

Deel II: Functioneel en technisch model (dit document) • •

1.9

Functioneel model: omvat de functionele bouwblokken en hun koppelvlakken binnen de distributie en toegangsketen, Technisch model: omvat de technische beschrijvingen van de koppelvlakken van de functionele bouwblokken. Leeswijzer

In ieder hoofdstuk zijn zogenaamde ‘Best practices’ benoemd. Een Best practice dient te worden gelezen als een advies voor het gebruik van een bepaald onderdeel van de referentiearchitectuur.

6 / 68

7 / 68


2. Functioneel model (I) In dit hoofdstuk worden de functionele bouwblokken beschreven die de processtappen ondersteunen. De functionele bouwblokken noemen we Services.2 Ketenpartners zijn vrij in hun keuze welke Service zij aanbieden. Indien een Service wordt aangeboden, dan dienen ook alle bijbehorende functies te worden aangeboden, behalve de optionele functies (Optional). De manier waarop Services gevonden kunnen worden door ketenpartners is beschreven in het Technisch Model. In figuur 1 wordt de relatie tussen de processtappen en Services weergegeven in termen van gegevensstromen.

Payment-‐ Service

Betalen Order-‐ Service

Bestellen

Educational ContentList Service

Distribueren

Bepalen ProductList Service

Configureren

Distribution Service

Profileren Entry-‐ Location-‐ Service

Identificeren Profile-‐ Service

Authenticeren

Account-‐ Service

Vermenigvuldigen

Koppelen

License-‐ Service

Toegang

Educational Content Service

Activeren

Figuur 1 Overzicht van processtappen en Services

Principes

Principe

Het Functioneel model is service georiënteerd opgezet.

(1) Uitleg

Conform breed toegepaste referentiearchitecturen, dienen services servicegeoriënteerd opgezet te worden (http://nl.wikipedia.org/wiki/Service-oriëntatie)

Rationale

Services moeten service georiënteerd opgezet zijn. Deze opzet voorziet in modulariteit waardoor herbruikbaarheid en vervangbaarheid worden verhoogd.

2

We kiezen niet voor de term ‘dienst’ om verwarring met (zakelijke) dienstverlening door ketenpartners te

vermijden.


Principe

Het Functioneel model omvat de noodzakelijke koppelvlakken om de

(2)

gewenste vormen van dienstverlening te faciliteren.

Uitleg

Het Functioneel model biedt de minimale functionaliteit om de gewenste dienstverlening in de keten te faciliteren.

Rationale

Dit principe dient als leidraad voor de afbakening van het functioneel model: er volgt uit welke informatie op welke wijze tussen services en applicaties uitgewisseld kan en moet worden.

Principe

De services dragen de verantwoordelijk voor de zakelijke

(3)

consistentieregels.

Uitleg

Eventuele applicaties bovenop de services leveren aanvullende dienstverlening, maar de verantwoordelijkheid voor de correctheid van de werkwijze is belegd bij de services.

Rationale

Dit principe dient als leidraad voor de afbakening van het functioneel model: er volgt uit welke informatie op welke wijze tussen services en applicaties uitgewisseld kan en moet worden.

Principe

De volgende services worden onderkend:

(4)

• • • • • • • • • •

AccountService ProfileService ProductListService EducationalContentListService OrderService PaymentService LicenseService DistributionService EntryLocationService EducationalContentService

Uitleg

Binnen de keten worden de betreffende services en functies onderkend

Rationale

De services vormen eenheden die door ketenpartners als aparte dienst in de keten (zouden kunnen) worden aangeboden.

Principe

De identifiers die zijn benoemd in de invoeren uitvoerparameters van

(5)

service-functies zijn ketenbreed uniek.

Uitleg

Een identifier die voorkomt als invoer- of uitvoerparameter heeft een dusdanige vorm dat deze herleid kan worden tot een unieke identiteit binnen de keten.

Rationale

Op deze manier wordt niet voorgeschreven hoe een ketenbreed unieke identifier wordt bepaald.

Principe

De identifier van een Rechtspersoon is geen onderdeel van Functioneel

(6)

Model.

Uitleg

De PartyId wordt slechts binnen het Technisch model gebruikt. De combinatie van AdministratieId en lokale identifier is voldoende voor ketenbrede identificatie van Deelnemers en Eenheden.

Rationale

Indien de Rechtspersoon verandert, hoeven de gekoppelde licenties niet per definitie te worden verhuisd.

8 / 68


2.1

AccountService

De AccountService beheert accounts en biedt authenticatiefuncties voor identiteiten van natuurlijke personen. Authenticatie van voorzieningen verloopt via certificaten. Voor details verwijzen we naar het Technisch model. Authenticatie vindt plaats op basis van gebruikersnaam en wachtwoord. Nadat een natuurlijk persoon zich heeft geauthenticeerd voor een bepaalde identiteit, verstrekt de AccountService de ketenbreed unieke identifier van de gebruiker. Op basis van deze identifier kunnen in een ProfileService kenmerken van de betreffende identiteit worden gelezen.

Figuur 2 Overzicht van AccountServicefuncties

Principes Principe

De AccountService authenticeert identiteiten van natuurlijke personen.

(1) Uitleg

Een AccountService beheert accounts van identiteiten van natuurlijke personen. Naast de authenticatiefunctie worden er functies voor het creëren en activeren van een account ondersteund. Er zijn ook beheerfuncties voorzien.

Rationale

De AccountService is met name bedoeld voor het kunnen authenticeren van identiteiten van natuurlijke personen. Natuurlijke personen maken veelal gebruik van Portalen via web browsers. Via deze browsers moet de achterliggende identiteit van de gebruiker kunnen worden bepaald. Voor authenticatie van Rechtspersonen worden andere authenticatievoorzieningen gebruikt. Dit wordt in het technisch model toegelicht.

9 / 68


Principe

De AccountService beheert alleen accountgegevens van een gebruiker.

(2) Uitleg

De AccountService beheert geen nadere gegevens dan de identifier (UserId en UserAdministrationId) van een gebruiker. Aanvullende gegevens over gebruikers worden in een ProfileService geregistreerd.

Rationale

Hierdoor wordt het mogelijk om authenticatiediensten en het beheren van (aanvullende) persoonsgegevens van elkaar te scheiden en door verschillende aanbieders te laten uitvoeren. Bijvoorbeeld kan de AccountService centraal worden aangeboden, en de ProfileServices door individuele ketenpartners.

Principe

De authenticatiefunctie van de AccountService ondersteunt

(3)

zekerheidsniveau Basis.

Uitleg

Indien voor een functie authenticatie vereist is, geldt dat de mate van zekerheid die gewenst is over de identiteit van een gebruiker van zekerheidsniveau Basis is. Voor de indeling van zekerheidsniveaus bij het authenticeren van gebruikers wordt aangesloten op de betreffende definities van DigiD3 hiervoor. Binnen de keten worden authenticatiemiddelen toegepast die onder zekerheidsniveau Basis vallen. Dit zijn bijvoorbeeld de UserName en Password combinatie. Er zijn andere zekerheidsniveaus als Midden en Hoog waarbij respectievelijk authenticatie plaats vindt op basis van SMS en een persoonsgebonden elektronische identiteitskaart. Deze vormen zijn niet noodzakelijk. De zekerheid op niveau basis wordt momenteel als voldoende geacht.

Rationale

Het streven is om zoveel mogelijk binnen de keten te standaardiseren. Zekerheidsniveau Basis is voldoende om alle functies binnen de keten te kunnen uitvoeren

Principe

De UserName moet uniek zijn binnen het domein van de AccountService

(4) Uitleg

De geregistreerde accounts in een AccountService worden uniek onderkend op basis van de UserName.

Rationale

De UserName moet uniek zijn om de gebruiker en bijbehorende account ook uniek te kunnen identificeren.

Principe

Federatieve authenticatie wordt ondersteund

(5) Uitleg

Een AccountService kan een ander AccountService vragen om authenticatie van een gebruiker.

Rationale

Federatieve authenticatie kan gewenst zijn om het onderhoud van AccountServices te minimaliseren.

2.1.1

NewAccount (Optional) Bij het creëren van een nieuw account wordt een authenticatiemiddel aan een UserId gekoppeld. Het hier beschreven authenticatiemiddel is een UserName en een Password-combinatie. Er bestaat de keuze dat er direct door de gebruiker een account wordt aangemaakt en een Password ingegeven wordt, of dat door een beheerder bij een Instelling het account wordt 3

http://www.digid.nl/burger/zekerheidsniveaus/

10 / 68


aangemaakt. Als een Instelling nieuwe accounts aanmaakt wordt en een tijdelijk wachtwoord (TempPassword) gegenereerd welk de gebruiker nodig heeft bij het activeren van het account. De invoergegevens voor deze functie zijn: 1

UserName: gebruikersnaam

2

Password (Optional): wachtwoord

3

UserId: identifier van de gebruiker, uniek binnen de betreffende Administratie

4

UserAdministrationId: de Administratie bij de UserId

De uitvoergegevens voor deze functie zijn: 1 2.1.2

TempPassword (Optional): tijdelijk wachtwoord; indien Password niet is ingevoerd

DeleteAccount (Optional) Deze functie verwijdert een bestaand account. Merk op dat als identifier van het account de UserName wordt aangehouden en niet de combinatie UserId met UserAdministrationId. Op deze wijze kunnen meerdere accounts worden ondersteund voor eenzelfde identiteit. De invoergegevens voor deze functie zijn: 1



Confirmation: bevestiging

ActivateAccount (Optional) Indien bij het creëren van een nieuwe account voor later activeren is gekozen kan de account via deze functie geactiveerd te worden. Bij later activeren wordt bij het creëren een tijdelijk Password aangemaakt welke de gebruiker nodig heeft om zijn account te kunnen activeren en moet hierbij een nieuw Password ingeven. De invoergegevens voor deze functie zijn: 1


2

TempPassword: tijdelijk wachtwoord

3

NewPassword: nieuw wachtwoord

De uitvoergegevens voor deze functie zijn: 1

2.1.4


AuthnRequest4 Dit is de vraag zoals deze door de dienstaanbieder aan de AccountService wordt doorgegeven via het door de gebruiker gebruikte platform. Het authenticeren van gebruikers wordt op basis van het SAML 2.0 Web Browser SSO profiel (SP initiated SSO with POST/artifact bindings) geïmplementeerd. Na authenticatie, worden de volgende gegevens teruggegeven: •


•


Zie voor verdere details de bijlage AccountService web service specificatie.

4

Vernoemd naar de betreffende SAML-functie.

11 / 68


2.2

ProfileService

Een ProfileService beheert aanvullende gegevens over identiteiten in profielen. Deze gegevens kunnen vervolgens selectief beschikbaar worden gesteld aan derden. De gegevens omvatten persoonsgegevens, maar ook machtigingen die zijn toegekend aan de betreffende identiteit. Een voorbeeld hiervan is de machtiging aan een leerling om van een bepaald schooltegoed te mogen afboeken. Meerdere ProfileServices kunnen gegevens bewaren over dezelfde identiteiten.

Figuur 3 Overzicht van de functies van de ProfileService

Principes Principe

Een ProfileService is een registratie waarop de Wet Bescherming

(1)

Persoonsgegevens van toepassing is.

Uitleg

Indien een ProfileService persoonsgegevens gaat beheren, moet deze conform de richtlijnen van „Achtergrondstudies en Verkenningen 23‟ worden ontworpen en ontwikkeld. Het AV-23 is beschikbaar gesteld door het College voor Persoonsbescherming (http://www.cbpweb.nl/Pages/av_23_Beveiliging.aspx).

Rationale

Gegevens die herleidbaar zijn naar natuurlijke personen vallen onder de Wet Bescherming Persoonsgegevens.

Principe

Een profiel kan aan de hand van een UserLocalId en UserAdministrationId

(2)

worden gezocht.

Uitleg

Een Profiel is altijd aan één gebruiker gekoppeld.

Rationale

Een Profiel omvat kenmerken van een gebruiker.

12 / 68


Principe

Een gebruiker hoeft geen Profiel te hebben.

(3)

2.2.1

Uitleg

Er hoeft geen Profiel te zijn geregistreerd bij een gebruiker.

Rationale

Een identiteit kan ook zonder profiel bestaan.

NewProfile (Optional) De invoergegevens voor deze functie zijn: 1

UserId: identifier van de gebruiker die uniek is binnen de betreffende Administratie

2



2.2.2


UpdateProfile (Optional) Deze functie schrijft kenmerken van een identiteit in een profiel. De waarden van de invoerparameters vervangen de oude waarden. Een lege invoerparameter resulteert in het wissen van de oude waarde. Een gebruiker kan slechts een enkele rol vervullen. Een gebruiker in verschillende rollen heeft verschillende identiteiten. De velden EducationalCourseId, EducationalSubjectId, EducationalLevelId, EducationalGroupId geven het onderwijskundige domein aan van de gebruiker:

•

Leerling - Indien het een leerling betreft, bepalen deze velden welke leermiddelenlijsten van toepassing zijn op de leerling, en in welke onderwijskundige context hij zijn materialen gebruikt (bijv. t.b.v. docentenoverzichten).

•

Leermiddelenlijstbeheerder - Indien het een leermiddelencoördinator betreft, geven deze velden aan binnen welke context deze leermiddelencoördinator leermiddelenlijsten mag beheren.

•

Docent - Indien het een docent betreft, geven deze velden aan binnen welke context hij de rol van docent vervult.

We merken op dat de velden EducationalCourseId, EducationalSubjectId, EducationalLevelId, EducationalGroupId niet hoeven te voldoen aan vocabulaires, en dat zij dus kunnen verschillen per school. De begunstigde (CreditorId) in het profiel van een gebruiker kunnen door ketenpartners onder andere worden gebruikt voor:

•

Bestellen - de gebruiker mag bestellen volgens de voorwaarden die voor deze begunstigde(n) zijn afgesproken,

•

Distribueren - de gebruiker mag (verzamel-) tegoeden van deze begunstigde(n) verzilveren in een licentie. Dit is met name gebruikelijk in IBF-scenario’s.

13 / 68


De invoergegevens voor deze functie zijn: 1

UserId: identifier van de gebruiker of organisatorische eenheid

2


3

Role (Optional): de rol van de gebruiker

4

0..n:

5

6

1

UnitId: organisatorische eenheid van de gebruiker

2

UnitAdministrationId: de Administratie bij de UnitId

0..n: 1

CreditorId: begunstigde waarvan de gebruiker tegoed mag afboeken

2

CreditorAdministrationId: de Administratie bij de CreditorId

0..n: 1

EducationalCourseId: opleiding bij de gebruiker

2

EducationalCourseAdministrationId: de Administratie bij EducationalCourseId

3

EducationalSubjectId: vak bij de gebruiker

4

EducationalSubjectAdministrationId: de Administratie bij EducationalSubjectId

5

EducationalLevelId: leerniveau/jaargang bij de gebruiker

6

EducationalLevelAdministrationId: de Administratie bij EducationalLevelId

7

EducationalGroupId: onderwijsgerelateerde klas/groep bij de gebruiker

8

EducationalGroupAdministrationId: de Administratie bij EducationalGroupId

7

Initials (Optional): initialen van de gebruiker

8

FirstName (Optional): voornaam van de gebruiker

9

MiddleName (Optional): tussenvoegsel van de gebruiker

10

LastName (Optional): achternaam van de gebruiker

11

BirthDate (Optional): geboortedatum van de gebruiker

12

Street (Optional): straatnaam bij de gebruiker

13

StreetNumber (Optional): huisnummer bij de gebruiker

14

StreetNumberExtra (Optional): huisnummertoevoeging bij de gebruiker

15

PostalCode (Optional): postcode bij de gebruiker

16

City (Optional): woonplaats bij de gebruiker

17

Email (Optional): emailadres voor correspondentie met de gebruiker

18

PhoneNumber (Optional): telefoonnummer van de gebruiker


2.2.3


ReadProfile De profielgegevens kunnen worden uitgelezen worden op basis van een UserId en bijbehorende UserAdministrationId, of op basis van andere profielkenmerken. Bij de invoerparameters geldt indien geen waarde is opgegeven, alle waarden worden aangenomen. Verder worden alleen die gegevens geleverd worden, waarvoor de afnemer is geautoriseerd.

14 / 68



UserId (Optional): identifier van de gebruiker, uniek binnen de betreffende Administratie

2

UserAdministrationId (Optional5): de Administratie bij de UserId

3


4

0..n:

5

6

1

UnitId: organisatorische eenheden van de gebruiker

2

UnitAdministrationId: de Administratie van de UnitId

0..n: 1

CreditorId: begunstigde waarvan de gebruiker tegoed mag afboeken6

2


0..n: 1

EducationalCourseId (Optional): opleiding van de gebruiker

2

EducatialCourseAdministrationId (Optional): de Administratie bij de EducationalCourseId

3

EducationalSubjectId (Optional): vak van de gebruiker

4

EducationalSubjectAdministrationId (Optional): de Administratie bij EducationalSubjectId

5

EducationalLevelId (Optional): leerniveau/jaargang van de gebruiker

6

EducationalLevelAdministrationId (Optional): de Administratie bij EducationalLevelId

7

EducationalGroupId (Optional): onderwijsgerelateerde klas/groep van de gebruiker

8

EducationalGroupAdministrationId (Optional): de Administratie bij EducationalGroupId

7


8


9


10


11


12


13


14


15


16


17


18


5

Verplicht als UserId is ingevuld.

6

Mogelijk beperkt een leverancier de mogelijke CreditorId/CreditorAdministrationId’s om te voorkomen dat

tegoeden willekeurig van derden worden afgeboekt.

15 / 68



0..n: 1


2


3


4

0..n:

5

6

1

UnitId: organisatorische eenheden van de gebruiker

2

UnitAdministrationId: de Administratie bij de UnitId

0..n: 1

CreditorId: begunstigde waarvan de gebruiker tegoed mag afboeken

2


0..n: 1

EducationalCourseId (Optional): opleiding(en) van de gebruiker

2

EducationalCourseAdministrationId (Optional): de Administratie bij de EducationalCourseId

3

EducationalSubjectId (Optional): vak van de gebruiker

4


5

EducationalLevelId (Optional): leerniveau/jaargang van de gebruiker

6


7

EducationalGroupId (Optional): onderwijsgerelateerde klas/groep van de gebruiker

8


7


8


9


10


11


12


13


14


15


16


17


18


16 / 68


2.2.4

DeleteProfile (Optional) De invoergegevens voor deze functie zijn: 1

UserId: identifier van de gebruiker

2




17 / 68


2.3

ProductListService

De ProductListService7 ontsluit het actuele aanbod van Leermiddelen van een Ketenpartner, waaronder distributeurs, boekhandels en uitgevers. De ProductListService dient ter ondersteuning van de processtappen Bepalen en Bestellen. De ProductListService is niet bedoeld voor marketingdoeleinden. De ProductListService beschrijft enkelvoudige en samengestelde leermiddelen. Beide worden geïdentificeerd met een EducationalContentId. We merken op dat de ProductListService leermiddelen kan bevatten, die niet door de aanbieder als product worden verkocht. Zo kan een enkelvoudig leermiddel alleen samengesteld in combinatie met andere leermiddelen als product worden verkocht. Indien het een digitaal leermiddel betreft, kan bij het leermiddel een beperking in periode (LicenseStartDate, LicenseEndDate), in gebruiksduur (LicenseDuration) of aantal maal gebruik (LicenseCount) zijn bepaald. Op dit moment worden digitale leermiddelen als product vaak nog gecombineerd aangeboden met fysieke leermiddelen. De ProductListService ondersteunt daarom samengestelde leermiddelen die bestaan uit fysieke en digitale leermiddelen. De ProductListService kan mogelijk worden gevoed door externe Catalogi.

Figuur 4 Overzicht van ProductListServicefuncties

Principes Principe

De EducationalContentId identificeert een enkelvoudig of samengesteld

(1)

Leermiddel.

Uitleg

Een EducationalContentId is een verwijzing naar een product in de ProductListService. Deze verwijzing kan naar een product verwijzen dat uit meerdere Leermiddelen bestaat.

Rationale

7

De EducationalContentId verwijst naar een product.

Er is bewust gekozen voor de naam ProductListService in plaats van CatalogueService, om verwarring te

voorkomen met een (toekomstige) standaard voor catalogi van uitgevers. De ProductListService heeft alleen toepassing binnen de context van deze afspraak.

18 / 68


Principe

Een EducationalContentId impliceert het type content en de bijbehorende

(2)

licentievorm.

Uitleg

De EducationalContentId identificeert het leermiddel en de licentievorm. De EducationalContentId bepaalt niet per definitie de licentieperiode.

Rationale

De licentievorm wordt door de aanbieder van het leermiddel bepaald en hoeft bij het zoeken en bestellen niet apart gespecificeerd te worden. Een EducationalContentId identificeert eenduidig het product en licentievorm en de gebruiksmogelijkheden die hier aan verbonden zijn. Omdat het een licentie betreft, kan de gebruiksperiode variëren.

Principe

Een aanbieder ontsluit via zijn ProductListService het actuele aanbod van

(3)

leermiddelen.

Uitleg

De ProductListService presenteert de leermiddelen die bij de aanbieder van de ProductListService kunnen worden besteld.

Rationale

Afnemers van de informatie moeten kunnen vertrouwen op de kwaliteit van de gegevens.

Principe

De ProductListService presenteert algemene productinformatie.

(4) Uitleg

De aanbieder van de ProductListService presenteert zijn algemeen geldende contractvoorwaarden voor de leermiddelen, zoals levereenheden, adviesprijzen en beschikbaarheid. Individuele afspraken met afnemers worden niet door de ProductListService verstrekt.

Rationale

Speciale, individuele contractvoorwaarden zijn gebonden aan contractpartijen. Deze zijn bekend bij de OrderService en identiteit-gebonden en passen om dit reden beter bij de OrderService.

Principe

Veranderingen in de kenmerken van een leermiddel verstoren de

(4)

ketenprocessen niet.

Uitleg

Webgebaseerd materiaal kan wijzigen nadat het is besteld. Voorbeelden zijn updates m.b.t. inhoud of prijzen. Wijzigingen mogen niet leiden tot ongewenste effecten, zoals grote afwijkingen van de inhoud, of tussentijdse prijsverhogingen.

Rationale

Ketenpartners moeten er vanuit kunnen gaan dat een leermiddel niet ongewenst ‘tijdens de rit’ verandert. Dit zou immers ertoe kunnen leiden dat een bepaald leermiddel met een bepaald EducationalContentId wordt besteld, en het leermiddel later wijzigt.

2.3.1

ReadProductListEntry Deze functie is bedoeld ter ondersteuning van de processtappen Bepalen en Bestellen. De functie is niet bedoeld om informatie te verstrekken voor marketingdoeleinden. Ter ondersteuning van deze stappen biedt de service niet alleen algemene productinformatie maar ook handelsinformatie. We wijzen erop, dat de functie actuele informatie teruggeeft over producten. De waarden van de uitvoervelden kunnen dus verschillen per aanroep. De invoerparameters bepalen de kenmerken van de leermiddelen die worden gelezen. De uitvoerparameters zijn gemarkeerd met de wenselijkheid waarmee zij gevuld zijn (Nice, Should). Die parameters die niet nader zijn gemarkeerd zijn verplicht gevuld.

19 / 68


Bij digitale leermiddelen worden soms ook aanvullende rechten verkocht. Voorbeelden hiervan zijn beheerrechten, overdrachtsrechten, verlenging van licentieperiode e.d. De standaard gaat er vanuit dat deze aanvullende rechten als aparte producten worden verkocht onder een eigen EducationalContentId.

De invoergegevens voor deze functie zijn:

8

1

EducationalContentId (Optional): uniek nummer van het leermiddel

2

EducationalContentAdministrationId (Optional8): de Administratie bij de EducationalContentId

3

PublisherId (Optional): identificatie van de uitgever als Rechtspersoon

4

PublisherName (Optional): naam van de uitgever als Rechtspersoon

5

Title (Optional): titel van het product

6

Author (Optional): de personen en/of organisatie die hebben gewerkt aan de totstandkoming

7

Description (Optional): Korte (inhoudelijke) beschrijving of samenvatting van het leermiddel.

8

EducationalSubject (Optional): Vak, onderwerp van het leermiddel.

9

Classification (Optional): classificatie van de inhoud van het leermiddel.

10

Medium (Optional): gegevensdrager van het product

11

EducationalContentUsageType (Optional): de indicatie of het materiaal gebruik-, of verbruikmateriaal is

12

LicenseStartDate (Optional): startdatum van de licentie

13

LicenseEndDate (Optional): einddatum van de licentie

14

LicenseDuration (Optional): aantal dagen dat de licentie geldig is vanaf start

15

LicenseCount (Optional): aantal maal dat de licentie mag worden gebruikt

16

IntendedUserRole (Optional): indicatie of het materiaal is bedoeld voor gebruik door leerling of voor docent

17

FirstPublishedDate (Optional): de eerste verschijningsdatum van het leermateriaal op de markt

18

LastRevisionDate (Optional): de laatste herzieningsdatum van het leermateriaal

19

EntryLocation (Optional): referentie (URL) naar plaats van het webgebaseerd leermiddel

20

InformationLocation (Optional): referentie (URL) naar de plaats van nadere productinformatie

21

ThumbnailLocation (Optional): Publieke referentie naar thumbnail van het product

22

Copyright (Optional): Leermiddel is wel/niet belast met auteursrechten

23

CopyrightDescription (Optional): Omschrijving van de auteursrechten die van toepassing zijn

24

0..n: 1

EducationalContentChildId: de leermiddelen waaruit dit product bestaat (in het geval van een gecombineerd product)

2

EducationalContentChildAdministrationId: de Administratie bij de EducationalContentChildId

Verplicht als EducationalContentId is ingevuld.

20 / 68


25

SupplierId (Optional): de Rechtspersoon die het leerobject voor genoemde prijs voor verkoop aanbiedt

26

SupplierName (Optional): de naam van de Rechtspersoon bij de SupplierId

27

SaleUnitSize (Optional): het aantal exemplaren van het (mogelijk samengesteld) product dat als eenheid wordt verkocht.

28

HasCost (Optional): indicator om aan te geven of aan de leermiddelen kosten zijn verbonden

29

Currency (Optional): de valuta van de prijs

30

PriceVATHigh (Optional): de prijs per verkoopeenheid van het product (excl. BTW) in centen waarover hoog BTW-tarief wordt gerekend

31

PriceVATLow (Optional): de prijs per verkoopeenheid van het product (excl. BTW) in centen waarover laag BTW-tarief wordt gerekend

32

AvailabilityStatus (Optional): status leverbaarheid van product

33

AvailabilityDate (Optional): datum vanaf wanneer het product leverbaar is

34

LastModifiedDate (Optional): laatste keer dat de productinformatie is aangepast door de uitgever.

De uitvoergegevens voor deze functie zijn: 0..n:

9

1

EducationalContentId: uniek productnummer van het leermateriaal

2

EducationalContentAdministrationId: de Administratie bij de EducationalContentId

3

PublisherId: identificatie van de uitgever

4

PublisherName: naam van de uitgever

5

Title (Should): titel van het product

6

Author (Should9): de personen en/of organisatie die hebben gewerkt aan de totstandkoming

7

Description (Should): Korte (inhoudelijke) beschrijving of samenvatting van het leermiddel.

8

EducationalSubject (Nice): Vak, onderwerp van het leermiddel.

9

Classification (Should): classificatie van de inhoud van het leermiddel.

10

Medium (Should): gegevensdrager van het product

11

EducationalContentUsageType (Nice): de indicatie of het materiaal gebruik-, of verbruikmateriaal is

12

LicenseStartDate (Should): startdatum van de licentie

13

LicenseEndDate (Should): einddatum van de licentie

14

LicenseDuration (Should): aantal dagen dat de licentie geldig is vanaf start

15

LicenseCount (Should): aantal maal dat het product mag worden gebruikt

16

IntendedUserRole (Should): indicatie of het materiaal is bedoeld voor gebruik door leerling of voor docent

17

FirstPublishedDate (Should): de eerste verschijningsdatum van het leermateriaal op de markt

18

LastRevisionDate (Should): de laatste herzieningsdatum van het leermateriaal

19

EntryLocation (Should): referentie (URL) naar plaats van het webgebaseerd leermiddel

Verplicht volgens NL-LOM.

21 / 68


20

InformationLocation (Should): referentie (URL) naar de plaats van nadere productinformatie

21

ThumbnailLocation (Nice): Publieke referentie naar thumbnail van het product

22

Copyright (Should): Leermiddel is wel/niet belast met auteursrechten

23

CopyrightDescription (Should): Omschrijving van de auteursrechten die van toepassing zijn

24

0..n: 1

EducationalContentChildId: de leermiddelen waaruit dit product bestaat (in het geval van een gecombineerd product)

2

EducationalContentChildAdministrationId: de Administratie bij de EducationalContentChildId

25

SupplierId: de persoon, groep of organisatie die het leerobject voor genoemde prijs voor verkoop aanbiedt

26

SupplierName: de naam bij de SupplierId

27

SaleUnitSize (Should): het aantal exemplaren van het (mogelijk samengesteld) product dat als eenheid wordt verkocht.

28

HasCost (Should): indicator om aan te geven of aan de leermiddelen kosten zijn verbonden

29

Currency (Should): de valuta van de prijs

30

PriceVATHigh (Should): de prijs per verkoopeenheid van het product (excl. BTW) in centen waarover hoog BTW-tarief wordt gerekend

31

PriceVATLow (Should): de prijs per verkoopeenheid van het product (excl. BTW) in centen waarover laag BTW-tarief wordt gerekend

32

AvailabilityStatus (Should): status leverbaarheid van product

33

AvailabilityDate (Should): datum vanaf wanneer het product leverbaar is

34

LastModifiedDate (Nice): laatste keer dat de productinformatie is aangepast door de uitgever.

22 / 68


2.4

EducationalContentListService

Tijdens de processtap Bepalen oriënteert een instelling zich op welke digitale leermiddelen er de komende periode gebruikt gaan worden. Een Leermiddelenbeheerder bij een Instelling zal hier via het Portaal gebruik van maken om de Leermiddelen te selecteren. De gecreëerde Leermiddelenlijst kan bij het bestellen gebruikt worden om de te bestellen leermiddelen te kunnen identificeren.

Figuur 5 Overzicht van EducationalContentListServicefuncties

Principes Er zijn geen principes bepaald.

2.4.1

NewEducationalContentList (Optional) Met deze functie kan er een nieuwe leermiddelenlijst in de EducationalContentListService geregistreerd worden. Leermiddelenlijsten worden opgesteld in de context van administraties en daarbinnen toegeschreven naar organisatorische eenheden (optioneel), opleidingen, vakken en/of groepsindelingen. Leermiddelenlijsten hebben een beperkte geldigheid als basis voor bestellingen: onderliggende contractuele afspraken zijn mogelijk slechts een beperkte tijd geldig. De rechten van een beheerder van een leermiddelenlijst kunnen worden ingeperkt door zijn profiel in de ProfileService. Daar kan zijn profiel aangeven voor welke UnitId, EducationalCourseId, EducationalSubjectId en EducationalLevelId de beheerder leermiddelenlijsten mag opstellen (zie ook ProfileService).

23 / 68


Een besteller krijgt op zijn beurt op basis van de UnitId, EducationalCourseId, EducationalSubjectId en EducationalLevelId in zijn profiel de betreffende leermiddelenlijsten gepresenteerd. Merk op dat voor EducationalCourse, EducationalSubject en EducationalLevel identifiers zijn voorzien en hier geen vocabulaires voor worden gebruikt. Hiermee kunnen onderwijsinstellingen hun eigen onderwijskundige context blijven gebruiken, zonder dat zij in een standaard structuur worden gedwongen. De invoergegevens voor deze functie zijn: 1

AdministratorId10: beheerder van de leermiddelenlijst

2

AdministratorAdministrationId: de Administratie bij de AdministratorId

3

UnitId (Optional): organisatorische eenheid waarvoor de leermiddelenlijst is bestemd

4

UnitAdministrationId (Optional11 ): de Administratie van de UnitId

5

0..n: 1

EducationalCourseId (Optional): opleiding aan welke de leermiddelenlijst ter beschikking wordt gesteld

2

EducationalCourseAdministrationId (Optional12 ): de Administratie bij de EducationalCourseId

3

EducationalSubjectId (Optional): vak aan welke de leermiddelenlijst ter beschikking wordt gesteld

4

EducationalSubjectAdministrationId (Optional13): de Administratie bij EducationalSubjectId

5

EducationalLevelId (Optional): leerjaar aan welke de leermiddelenlijst ter beschikking wordt gesteld

6

EducationalLevelAdministrationId (Optional14 ): de Administratie bij EducationalLevelId

6

StartDate: datum vanaf wanneer de leermiddelenlijst geldig is

7

EndDate: datum vanaf wanneer de leermiddelenlijst niet meer geldig is

De uitvoergegevens voor deze functie zijn:

2.4.2

1

EducationalContentListId: identifier van de leermiddelenlijst

2

EducationalContentListAdministrationId: de Administratie bij de EducationalContentListId

DeleteEducationalContentList (Optional) De invoergegevens voor deze functie zijn: 1


2




10

We beschouwen de opsteller van de leermiddelenlijst ook als de beheerder.

11

Verplicht indien UnitId is ingevuld.

12

Verplicht indien EducationalCourseId is ingevuld.

13

Verplicht indien EducationalSubjectId is ingevuld.

14

Verplicht indien EducationalLevelId is ingevuld.

24 / 68


2.4.3

NewEducationalContentListEntry (Optional) Toevoegen van een leermiddel aan een reeds bestaande leermiddelenlijst. De leermiddelenlijst kan per leermiddel meerdere verkopers (SupplierId) onderkennen, ieder mogelijk met andere bestelaantallen, prijzen en andere karakteristieken. De invoergegevens voor deze functie zijn: 1

EducationalContentListId: de identifier van de leermiddelenlijst

2


3

EducationalContentId: het betreffende leermiddel op de leermiddelenlijst

4


5

SupplierId: verkoper waarbij het leermiddel besteld moet worden15

6

PayerId (Optional16): de betaler van het leermiddel.

7

PayerAdministrationId (Optional17): de Administratie bij de PayerId

8

MinQuantity: minimaal aantal leermiddelen dat moet worden besteld

9

MaxQuantity: maximaal aantal leermiddelen dat mag worden besteld

10

PriceVATLow: deel van de prijs18 van het leermiddel met laag BTW-tarief

11

PriceVATHigh: deel van de prijs19 van het leermiddel met hoog BTW-tarief

12

Discount: het kortingspercentage dat is toegepast op PriceVATLow en PriceVATHigh

13

AdditionalInfo: omschrijving en/of instructie aan de besteller voor dit leermiddel

14

ContractId (Optional): speciale voorwaarden die zijn afgesproken met de verkoper

15

ContractAdministrationId (Optional20): de Administratie bij de ContractId


Confirmation

DeleteEducationalContentListEntry (Optional) Verwijderen van een leermiddel aan een reeds bestaande leermiddelenlijst. De invoergegevens voor deze functie zijn: 1

EducationalContentListId: leermiddelenlijst waarin het leermiddel staat benoemd

2

EducationalContentListAdministrationId: de Administratie van de EducationalContentListId

3

EducationalContentId: het leermiddel dat wordt verwijderd uit de lijst

4

EducationalContentAdministrationId: de Administratie van de EducationalContentId

5

SupplierId: de leveranciers van het leermiddel


Confirmation

15

De combinatie EducationalContentId en SupplierId maakt de regel in de Leermiddelenlijst uniek.

16

Indien de betaler niet is ingevuld, wordt de besteller aangesproken als betaler.

17

Verplicht als PayerId is ingevuld.

18

Mogelijk wijkt deze prijs af van de catalogusprijs.

19

Mogelijk wijkt deze prijs af van de catalogusprijs.

20

Verplicht als ContractId is ingevuld.

25 / 68


2.4.5

ReadEducationalContentList Leermiddelenlijsten kunnen bijvoorbeeld gezocht worden op basis van ondermeer AdministratorId, EducationalCourse, EducationalSubject of EducationalLevel. De invoergegevens voor deze functie zijn: 1

EducationalContentListId (Optional): identifier van de leermiddelenlijst

2

EducationalContentListAdministrationId (Optional): de Administratie bij de EducationalContentListId

3

AdministratorId (Optional): beheerder van de leermiddelenlijst

4

AdministratorAdministrationId (Optional): de Administratie bij de AdministratorId

5


6

UnitAdministrationId (Optional): de Administratie bij de UnitId

7

0..n: 1

EducationalCourseId (Optional): opleiding aan welke de LML ter beschikking wordt gesteld

2


3

EducationalSubjectId (Optional): vak aan welke de LML ter beschikking wordt gesteld

4


5

EducationalLevelId (Optional): leerjaar aan welke de LML ter beschikking wordt gesteld

6


8

StartDate (Optional): datum vanaf wanneer de leermiddelenlijst geldig is

9

EndDate (Optional) datum vanaf wanneer de leermiddelenlijst niet meer geldig is

26 / 68


De uitvoergegevens voor deze functie zijn: 0..n: 1


2


3

AdministratorId: beheerder van de leermiddelenlijst

4

AdministratorAdministrationId: de Administratie bij de AdministratorId

5


6


7

0..n: 1

EducationalCourseId (Optional): opleiding aan welke de LML ter beschikking wordt gesteld

2


3

EducationalSubjectId (Optional): vak aan welke de LML ter beschikking wordt gesteld

4


5

EducationalLevelId (Optional): klas aan welke de LML ter beschikking wordt gesteld

6


8

StartDate (Optional): datum vanaf wanneer de leermiddelenlijst geldig is

9

EndDate (Optional): datum vanaf wanneer de leermiddelenlijst niet meer geldig is

10

0..n: 1

EducationalContentId: het betreffende leermiddel op de leermiddelenlijst

2


3

SupplierId: verkoper waarbij het leermiddel besteld moet worden

4

PayerId (Optional): de betaler van het leermiddel

5

PayerAdministrationId (Optional): de Administratie bij de PayerId

6

MinQuantity: minimaal aantal leermiddelen dat moet worden besteld

7

MaxQuantity: maximaal aantal leermiddelen dat mag worden besteld

8

PriceVATLow: deel van de prijs van het leermiddel met laag BTW-tarief

9

PriceVATHigh: deel van de prijs van het leermiddel met hoog BTW-tarief

10

Discount: het kortingspercentage dat is toegepast op PriceVATLow en PriceVATHigh

11

AdditionalInfo: omschrijving en/of instructie aan de besteller voor dit leermiddel

12

ContractId (Optional): speciale voorwaarden die zijn afgesproken met de verkoper

13

ContractAdministrationId (Optional): de Administratie bij de ContractId

27 / 68


2.5

OrderService

Via de OrderService worden bestellingen geplaatst bij een ketenpartner. Bij een Bestelling kunnen de Besteller, Betaler en Begunstigde apart worden gespecificeerd. Een Bestelling resulteert altijd in een Tegoed bij een DistributionService. Dit Tegoed kan worden omgezet in een Licentie.

Figuur 6 Overzicht van OrderServicefuncties

Principes Er zijn geen principes vastgesteld.

2.5.1

NewOrder Een besteller plaatst een bestelling bij de OrderService. De besteller hoeft zich hierbij niet noodzakelijkerwijs te identificeren of authenticeren. Met de operatie NewOrder kan men alleen enkelvoudige leermiddelen bestellen. Voor samengestelde leermiddelen, dient men de ProductListService te raadplegen om de enkelvoudige leermiddelen te bepalen. De NewOrder kent geen samenstelling van orders in orderregels. Mogelijke relaties tussen verschillende orders dienen dus buiten de OrderService geadministreerd te worden. Bij een Order kan een CouponCode worden meegegeven, waarmee de besteller zich kan beroepen op speciale voorwaarden, zoals kortingen. Daarnaast kunnen bestellingen expliciet in de context van speciale contractvoorwaarden worden geplaatst. Aan deze speciale contractvoorwaarden kan expliciet worden gerefereerd tijdens de bestelling door de ContractId. Eventueel kan de ketenpartner die de bestelling ontvangt in het betreffende ProfileService nadere gegevens opvragen over de besteller en/of betaler om de contractvoorwaarden te verifiëren. Voorbeelden van dergelijke gegevens zijn de rol en organisatorische eenheid (zie ProfileService).

28 / 68


Bij de functie NewOrder kan een DeliveryMethod worden opgegeven die bepaalt hoe de bestelling van de digitale materialen geleverd wordt, te weten:21

•

Direct: de licentierechten worden onmiddellijk gekoppeld aan de CreditorId (zonder tegoed als tussenstap)

• •

Credit: uitlevering als tegoed CodeSend: verzenden van codes (bijv. op papier, of via email); het afleveradres wordt door aanbieder van NewOrder bepaald, bijvoorbeeld door het adres of de email uit het profiel van de Creditor te lezen.

•

CodeRead: uitlezen van codes (via de functie ReadCode van de DistributionService).

Het bestelde product (EducationalContentId) kan een samengesteld product zijn. Een samengesteld product wordt altijd geleverd als enkelvoudige producten. De invoergegevens voor deze functie zijn: 1

BuyerId (Optional22): de besteller

2

BuyerAdministrationId (Optional23 ): de Administratie bij de BuyerId

3

PayerId (Optional24): de betaler

4


5

CreditorId: de begunstigde (gebruiker of organisatorische eenheid) van de bestelling26

6


7

EducationalContentId: het enkelvoudige leermiddel dat wordt besteld

8


9

Quantity: het aantal27 leermiddelen dat wordt besteld

10

DeliveryMethod: levermethode van het leermiddel

11

DeliveryDate (Optional28 ): datum vanaf wanneer de tegoeden/codes worden geleverd

12

CouponCode (Optional): code voor speciale voorwaarden, bijvoorbeeld een korting

13

ContractId (Optional): contractuele context van de bestelling

14

ContractAdministrationId (Optional29): de Administratie bij de ContractId


OrderId: referentie van de geplaatste order.

2

OrderAdministrationId: de Administratie bij de OrderId

Of een PayerId kan worden opgegeven is afhankelijk van de contractuele afspraken zijn gemaakt. Eventueel zijn de mogelijke PayerId’s ingeperkt.

21

Zie Technisch model.

22

Anoniem bestellen is mogelijk.

23

Verplicht als BuyerId is ingevuld.

24

Afhankelijk van de geldende contractvoorwaarden.

25


26

Indien DeliveryMethod=CodeSend, dan wordt het afleveradres mogelijk uit het profiel van de identiteit

gelezen. 27

Indien DeliveryMethod=Direct, geldt dat Quantity=1.

28

Geen waarde betekent ‘onmiddellijk’.

29

Verplicht als ContractId is ingevuld.

29 / 68


2.5.2

ReadOrder Ketenpartners of bestellers hebben middels deze functie inzicht in geplaatste bestellingen. Hierbij zijn verschillende filters mogelijk. De invoergegevens geven hiervan een overzicht. De invoergegevens voor deze functie bij een bestelling zijn: 1

OrderId (Optional): referentie van de order

2

OrderAdministrationId (Optional): de Administratie bij de OrderId

3

BuyerId (Optional): de besteller

4

BuyerAdministrationId (Optional): de Administratie bij de BuyerId

5

PayerId (Optional): de betaler

6


7

CreditorId (Optional): de begunstigde (gebruiker of organisatorische eenheid) van de bestelling

8

CreditorAdministrationId (Optional): de Administratie bij de CreditorId

9

EducationalContentId (Optional): het enkelvoudige leermiddel dat wordt besteld

10

EducationalContentAdministrationId (Optional): de Administratie bij de EducationalContentId

11

Quantity (Optional): het aantal leermiddelen dat wordt besteld

12

DeliveryMethod (Optional): levermethode van het leermiddel

13

DeliveryDate (Optional): datum vanaf wanneer de tegoeden/codes worden geleverd

14


15


16

ContractAdministrationId (Optional): de Administratie bij de ContractIdOrderStatus (Optional)

30 / 68



2.5.3

0..n: 1

OrderId: referentie bij de Order

2


3

BuyerId (Optional): de besteller

4

BuyerAdministrationId (Optional): de Administratie bij de besteller

5

PayerId (Optional): de betaler

6

PayerAdministrationId (Optional): de Administratie bij de betaler

7

CreditorId: de begunstigde (gebruiker of organisatorische eenheid) van de bestelling

8


9

EducationalContentId: het enkelvoudige leermiddel dat wordt besteld

10


11

Quantity: het aantal leermiddelen dat wordt besteld

12

DeliveryMethod: levermethode van het leermiddel

13

DeliveryDate (Optional): datum vanaf wanneer de tegoeden/codes worden geleverd

14


15


16

ContractAdministrationId (Optional): de Administratie bij de ContractId

17

OrderStatus: status van de order

CancelOrder (Optional) Deze functie annuleert een bestelling. De invoergegevens voor deze functie bij een bestelling zijn: 1

OrderId: referentie van de geplaatste order

2




Best practice

Foutgevoeligheid identifiers Het gebruik van een identifier (CreditorId) als begunstigde van een bestelling (zie ook Distribueren) kan in de uitvoeringspraktijk foutgevoelig zijn. Mogelijke fouten zijn: 1

Foutief invoeren van de identifier (‘bloot’ gebruik),

2

Verliezen of vergeten van de identifier.

31 / 68


Hieronder volgen een aantal best practices om de foutgevoeligheid te verminderen. Ad 1: Foutief invoeren van de identifier •

Er worden alleen identifiers uitgegeven volgens een bepaalde systematiek, met intrinsieke redundantie. Nadeel hiervan is dat mogelijk bestaande nummering niet kan worden hergebruikt.

•

Controleren van de ingegeven identifier aan de hand van profielgegevens (via de ProfileService).

•

De gebruiker vragen om in te loggen, waarna de UserId met UserAdministrationId automatisch wordt meegegeven (incl. eventuele aanvullende kenmerken via de ProfileService).

Ad 2: Verliezen of vergeten van de identifier •

De Ketenpartner biedt een zoekfunctie (via ProfileService (geautomatiseerd) of via helpdesk) om de identifier te achterhalen.

•

Nummers gebruiken die gebruikers eenvoudig kunnen onthouden (bijv. leerlingnummer).

32 / 68


2.6

PaymentService

Tijdens de processtap Betalen worden de betalingen voor de betreffende bestellingen verwerkt. De PaymentService voert zelf geen betalingen uit, maar registreert de betalingen die door een financiële dienstverlener zijn uitgevoerd.

Figuur 7 Overzicht van PaymentServicefuncties

Principes Principe

Een PaymentService registreert betalingen, maar voert deze niet uit.

(1) Uitleg

De PaymentService laat de afhandeling van betalingen over aan een financiële dienstverlener.

Rationale

2.6.1

ECK heeft niet de ambitie om betalingswijzen te standaardiseren.

RegisterPayment (Optional) Met deze functie kan de afhandeling van een betaling worden geregistreerd. Deze functie handelt zelf geen betaling af. Een betaling wordt pas geregistreerd, indien deze is afgerond.30 Er bestaat de mogelijkheid om anonieme betalingen te registreren (bijvoorbeeld contant). In dat geval zal de betaler niet gespecificeerd zijn.

Ook is het mogelijk dat iemand anders betaalt, dan is opgegeven bij het plaatsen van de order via NewOrder. Om die reden is de PayerId opgenomen in de parameterlijst.

30

In deze versie van de referentiearchitectuur onderkennen we nog geen betaalstatus.

33 / 68



OrderId: referentie naar de bestelling

2


3

PayerId (Optional31): diegene die heeft betaald

4


5

Amount: het bedrag dat is betaald33


2.6.2

1

PaymentId: referentie van de betaling

2

PaymentAdministrationId: de Administratie bij de PaymentId

ReadPayment Deze functie biedt inzicht in betalingen. Hierbij zijn verschillende filters mogelijk. De invoergegevens geven hiervan een overzicht. De invoergegevens voor deze functie zijn: 1

PaymentId (Optional): referentie van de betaling

2

PaymentAdministrationId (Optional): de Administratie bij de PaymentId

3

OrderId (Optional): referentie naar de bestelling

4

OrderAdministrationId (Optional): de Administratie bij de OrderId

5

PayerId (Optional): diegene die heeft betaald

6

PayerAdministrationId (Optional)

7

Amount (Optional): het bedrag dat is betaald

De uitvoergegevens voor deze functie zijn: 0..n: 1 PaymentId: referentie van de betaling 2

PaymentAdministrationId: de Administratie bij de PaymentId

3

OrderId: referentie naar de bestelling

4


5

PayerId (Optional): diegene die heeft betaald

6


7

Amount: het bedrag dat is betaald

31

In geval van anonieme betaling (bijv. à contant of per iDEAL e.d.).

32


33

Dit hoeft niet noodzakelijkerwijs het exacte bedrag van de Bestelling te omvatten.

34 / 68


2.7

DistributionService

De DistributionService beheert Tegoeden en Codes die gebruikers recht geven op licenties. De DistributionService maakt het mogelijk Tegoeden van een identiteit naar een andere identiteit te distribueren en Tegoeden om te zetten naar Codes. In deze referentiearchitectuur wordt niet voorzien in het overdragen van tegoeden tussen DistributionServices.

Figuur 8 Overzicht van DistributionServicefuncties

Principes Principe

De DistributionService bevat tegoeden en codes die zijn toegekend aan

(1)

identifiers van gebruikers en organisatie-eenheden.

Uitleg

De DistributionService beheert het digitaal handelswaar. Dit handelswaar heeft de vorm van tegoeden en codes en staan op naam van identiteiten.

Rationale

De DistributionService bevat het digitaal handelswaar dat hier eventueel van eigenaar kan wisselen.

35 / 68


Principe

Gebruikers kunnen via een ProfileService worden gemachtigd om Tegoeden

(2)

te consumeren van organisatorische eenheden.

Uitleg

Indien een gebruiker volgens zijn profiel behoort tot een organisatorische eenheid, dan is deze gemachtigd een tegoed op naam van deze organisatorische eenheid te consumeren tot een licentie.

Rationale

Deze werkwijze is een implementatie van een machtigingsconstructie. De school machtigt een leerling feitelijk om een tegoed op naam van de school te verzilveren bij een uitgever ten tijde van eerste toegang. Dit is gangbaar bij zogenaamde interne boekenfondsen.

2.7.1

DistributeCredit Met de functie DistributeCredit kan (een deel van) een tegoed worden overgedragen van een Creditor naar een andere Creditor. De aanroeper moet geautoriseerd zijn om het Credit van CurrentCreditorId over te dragen. De overdracht zelf wordt geïdentificeerd door een DistributionId. Door dit DistributionId kunnen leveringen worden getraceerd. Dit is nuttig voor verantwoording en servicedoeleinden: de aanroeper kan hiervoor met het DistributionId een relatie leggen met een Order. De invoergegevens voor deze functie zijn: 1

CurrentCreditorId: de identiteit die de tegoeden bezit

2

CurrentCreditorAdministrationId: de Administratie bij de CurrentCreditorId

3

NewCreditorId: de identiteit die de tegoeden ontvangt

4

NewCreditorAdministrationId: de Administratie bij de NewCreditorId

5

EducationalContentId: leermiddel waarvan tegoeden worden overgedragen

6


7

Quantity: aantal tegoeden dat wordt overgedragen


2.7.2

1

DistributionId: referentie van de overdracht

2

DistributionAdministrationId: de Administratie bij de DistributionId

CorrectDistributeCredit Deze functie maakt een overdracht van Tegoeden ongedaan. In principe kan een aanroeper met deze functie Tegoeden terughalen, die buiten zijn bereik zijn overgedragen. Of dit daadwerkelijk mogelijk is hangt af van de afspraken die zijn gemaakt rondom eerdere overdracht. De invoergegevens voor deze functie zijn: 1

DistributionId: referentie de te corrigeren overdracht

2



DistributionId: referentie van de corrigerende overdracht

2


36 / 68


2.7.3

ReadDistributeCredit (Optional) Deze functie leest de uitgevoerde overdrachten via de functie DistributeCredit en CorrectDistributeCredit. De invoergegevens voor deze functie zijn: 1

DistributionId (Optional): referentie van de overdracht

2

DistributionAdministrationId (Optional): de Administratie bij de DistributionId

3

CurrentCreditorId (Optional): de identiteit die de tegoeden heeft geleverd

4

CurrentCreditorAdministrationId (Optional): de Administratie bij de CurrentCreditorId

5

NewCreditorId (Optional): de identiteit die de tegoeden heeft ontvangen

6

NewCreditorAdministrationId (Optional): de Administratie bij de NewCreditorId

7

EducationalContentId (Optional): leermiddel waarvan tegoeden zijn overgedragen

8


9

Quantity (Optional): aantal tegoeden dat is overgedragen


2.7.4

1

DistributionId: referentie van de overdracht

2


3

CurrentCreditorId: de identiteit die de tegoeden heeft geleverd

4

CurrentCreditorAdministrationId: de Administratie bij de CurrentCreditorId

5

NewCreditorId: de identiteit die de tegoeden heeft ontvangen

6

NewCreditorAdministrationId: de Administratie bij de NewCreditorId

7

EducationalContentId: leermiddel waarvan tegoeden zijn overgedragen

8


9

Quantity: aantal tegoeden dat is overgedragen

ReadCredit Deze functie leest de Tegoeden die zijn geregistreerd in de DistributionService. De invoerparameters bepalen welke Tegoeden worden opgevraagd. De invoergegevens voor deze functie zijn:34

34

1

CreditorId (Optional): begunstigde van het tegoed

2

CreditorAdministrationId (Optional): de Administratie bij CreditorId

3

EducationalContentId (Optional): betreffende leermiddel bij het tegoed

4


Indien een invoerveld leeg blijft, worden alle waarden aangenomen.

37 / 68


De uitvoergegevens voor deze functie zijn: 0..n:

2.7.5

1

CreditorId: Begunstigde van het tegoed

2


3

EducationalContentId: Betreffende leermiddel bij het tegoed

4


5

AvailableQuantity: Aantal tegoeden beschikbaar

6

UsedQuantity: Aantal tegoeden afgeboekt

CreditToCode Deze functie zet een of meerdere tegoeden om in een code. Het is dus mogelijk om voor meerdere tegoeden een enkele code uit te leveren. De code zal tijdens het Koppelen moeten worden geaccepteerd door de LicenseService. Deze versie van de referentie-architectuur beschrijft nog niet hoe dit wordt geborgd. Een Code kan worden verstuurd of uitleesbaar gemaakt worden in de DistributionService (zie ReadCode):

•

CodeSend: verzenden van een code (bijv. op papier, of via email). De aanbieder van de DistributionService bepaalt hoe de codes vervolgens worden verstuurd. Mogelijk baseert de aanbieder zich op informatie in het profiel van de Creditor.

•

CodeRead: de code is uit te lezen via de functie ReadCode van de DistributionService

Merk op dat codes niet als uitvoerparameter van de functie worden teruggegeven, om de kans op verlies van codes te minimaliseren. De invoergegevens voor deze functie zijn: 1

CreditorId: de identiteit die het tegoed bezit

2


3

EducationalContentId: het leermiddel waarvoor een code moet worden geleverd

4


5

Quantity: het aantal tegoeden dat wordt omgezet in de code

6

DeliveryMethod: levermethode van de code


DistributionId: referentie van de omzetting naar de code

2


38 / 68


2.7.6

ReadCode (Optional) Nadat tegoeden zijn geleverd als code, zijn de codes beschikbaar in de DistributionService. De codes zijn vervolgens terug te lezen via deze operatie. Alleen die codes zijn terug te lezen, waarvoor de aanroeper is geautoriseerd. De invoergegevens voor deze functie zijn: 1

CreditorId (Optional): De identiteit die de code bezit

2


3

EducationalContentId (Optional): Het leermiddel waarvoor de code is bedoeld

4


5

Code (Optional): De code zelf


CreditorId: De identiteit die de code bezit

2


3

EducationalContentId: Het leermiddel waarvoor de code is bedoeld

4


5

Code: de code zelf

39 / 68

40 / 68


2.8

LicenseService

De LicenseService beheert de Licenties bij Leermiddelen. Licenties bestaan uit individuele gebruiks- en beheerrechten. LicenseService S2S Koppelvlak extern gebruik

ReadLicense

Koppelvlak voor intern netwerk (ontsluiting via eigen portaal) Rechtspersoon Rechtspersoon

Licenses

Principes Principe

De Licentie wordt geïdentificeerd door EducationalContentId en UserId.

(1) Uitleg

Een Licentie is een individueel recht op een Leermiddel. De combinatie van identifier van het Leermiddel en de gebruiker bepalen dus de individuele Licentie.

Rationale

2.8.1

Licenties zijn rechten die aan gebruikers worden toegekend.

ReadLicense Deze operatie levert een overzicht van bestaande Licenties. Een Licentie kent een StartDate en ExpirationDate om de rechten eventueel te beperken tot een bepaalde periode. Ook kan het aantal keer dat een recht kan worden uitgeoefend worden beperkt (Count). Indien de betreffende StartDate, ExpirationDate of Count niet is ingevuld, geldt er geen beperking. De operatie geeft terug alleen die Licenties, die de aanroeper mag zien. De invoergegevens voor deze functie zijn: 1

UserId (Optional): de gebruiker van de licentie(s)

2

UserAdministrationId (Optional): de Administratie bij UserId

3

EducationalContentId (Optional): het leermiddel dat is gekoppeld aan de gebruiker

4


5

StartDate (Optional): datum vanaf wanneer de licentie(s) geldig zijn

6

ExpirationDate (Optional): datum tot en met wanneer de licentie(s) geldig zijn

7

Count (Optional): aantal keer dat het recht nog uitgeoefend kan worden



UserId (Optional): de gebruiker van de licentie(s)

2


3

EducationalContentId: het leermiddel dat is gekoppeld aan de gebruiker

4


5

StartDate (Optional): datum vanaf wanneer de licentie geldig is

6

ExpirationDate (Optional): datum tot en met wanneer de licentie geldig is

7

Count (Optional): aantal keer dat het recht nog uitgeoefend kan worden

41 / 68


2.9

EntryLocationService

De functies van de EntryLocationService worden in figuur 9 weergegeven. Het biedt diensten met betrekking tot toegangsadressen welke vaak binnen de instelling aangeroepen zullen worden. Met de toegangsadressen verkrijgen gebruikers toegang tot het materiaal.

Figuur 10 Overzicht van de functies van de EntryLocationService

Principes Principe

Een toegangsadres verwijst naar de locatie waar Licentierechten kunnen worden

(1)

uitgeoefend.

Uitleg

Licentierechten kunnen zowel gebruiksrechten als ook beheerrechten omvatten. In het geval van gebruiksrechten zal het toegangsadres veelal naar een educatieve applicatie verwijzen. In het geval van beheerrechten kan het toegangsadres ook wel naar een beheersite verwijzen.

Rationale

42 / 68


2.9.1

NewEntryLocation Met deze functie kunnen toegangsadressen (EntryLocation) gekoppeld worden aan een gebruiker en/of zijn administratieve, organisatorische en onderwijskundige context. Het toekennen aan contexten is nuttig indien distributie plaatsvindt op basis van verzameltegoeden (ook wel: interne boekenfondsen). Op basis hiervan kan een toegangsportaal de juiste toegangsadressen aan de betreffende gebruikers tonen. De invoergegevens voor deze functie zijn: 1

UserId (Optional): de gebruiker waarbij een toegangsadres wordt geplaatst

2

UserAdministrationId (Optional35 ): de Administratie bij UserId

3

UnitId (Optional): de organisatorische eenheid waarbij het toegangsadres wordt geplaatst.

4

UnitAdministrationId (Optional36 ): de Administratie bij de UnitId

5

EducationalCourseId (Optional): opleiding waarbij het toegangsadres wordt geplaatst

6

EducationalCourseAdministrationId (Optional37): de Administratie bij de EducationalCourseId

7

EducationalSubjectId (Optional): vak waarbij het toegangsadres wordt geplaatst

8

EducationalSubjectAdministrationId (Optional38 ): de Administratie bij EducationalSubjectId

9

EducationalLevelId (Optional): leerniveau/jaargang waarbij het toegangsadres wordt geplaatst

10

EducationalLevelAdministrationId (Optional39): de Administratie bij EducationalLevelId

11

EducationalGroupId (Optional): onderwijsgerelateerde klas/groep waarbij het toegangsadres wordt geplaatst

12

EducationalGroupAdministrationId (Optional40): de Administratie bij EducationalGroupId

13

EntryLocation: het toegangsadres van het enkelvoudige leermiddel



35

Verplicht indien UserId is ingevuld.

36

Verplicht indien UnitId is ingevuld.

37

Verplicht indien EducationalCourseId is ingevuld.

38

Verplicht indien EducationalSubjectId is ingevuld.

39

Verplicht indien EducationalLevelId is ingevuld.

40

Verplicht indien EducationalGroupId is ingevuld.

43 / 68


2.9.2

ReadEntryLocation Deze functie levert een overzicht van de toegangsadressen in de EntryLocationService. Lege parameters impliceren geen beperking. De invoergegevens voor deze functie zijn:41

41

1

UserId (Optional): de gebruiker waarbij de toegangsadressen worden gelezen

2


3

UnitId (Optional): de organisatorische eenheid waarbij de toegangsadressen worden gelezen.

4


5

EducationalCourseId (Optional): opleiding waarbij de toegangsadressen worden gelezen

6


7

EducationalSubjectId (Optional): vak waarbij de toegangsadressen worden gelezen

8


9

EducationalLevelId (Optional): leerniveau/jaargang waarbij de toegangsadressen worden gelezen

10


11

EducationalGroupId (Optional): onderwijsgerelateerde klas/groep waarbij de toegangsadressen worden gelezen

12


13

EntryLocation (Optional): het toegangsadres dat wordt gelezen

UserId is ingevuld dan en slechts dan als de velden Unit*Id en velden Educational*Id leeg zijn.

44 / 68



UserId (Optional): de gebruiker waar het toegangsadres bij hoort

2


3

UnitId (Optional): de organisatorische eenheid waarbij het toegangsadres wordt gelezen.

4


5

EducationalCourseId (Optional): opleiding waarbij het toegangsadres wordt gelezen

6


7

EducationalSubjectId (Optional): vak waarbij het toegangsadres wordt gelezen

8


9

EducationalLevelId (Optional): leerniveau/jaargang waarbij het toegangsadres wordt gelezen

10


11

EducationalGroupId (Optional): onderwijsgerelateerde klas/groep waarbij het toegangsadres wordt gelezen

12


13

EntryLocation: het betreffende toegangsadres

45 / 68


2.9.3

DeleteEntryLocation Met deze functie worden toegangsadressen verwijderd. De invoergegevens voor deze functie zijn:42 1

UserId (Optional): de gebruiker waar het toegangsadres bij hoort

2


3

UnitId (Optional): de organisatorische eenheid waarbij het toegangsadres wordt geplaatst

4


5

EducationalCourseId (Optional): opleiding waarbij het toegangsadres wordt geplaatst

6


7

EducationalSubjectId (Optional): vak waarbij het toegangsadres wordt geplaatst

8


9

EducationalLevelId (Optional): leerniveau/jaargang waarbij het toegangsadres wordt geplaatst

10


11

EducationalGroupId (Optional): onderwijsgerelateerde klas/groep waarbij het toegangsadres wordt geplaatst

12


13

EntryLocation (Optional): het toegangsadres



Best practice

EntryLocation Voor de EntryLocation wordt aanbevolen om de volgende URL te gebruiken: /EAN.

Voorbeeld www.malmberg.nl/2349812 www.thiememeulenhoff.nl/912834

42

Voor de invoerparameters geldt dat zij inperken: een lege parameter impliceert alle waarden.

46 / 68


2.10

EducationalContentService

Deze service representeert de locatie waar de leermiddelen staan en de toegangsadressen naar verwijzen. Toegang tot de leermiddelen vereist authenticatie en autorisatie van de gebruiker. Indien beide succesvol verlopen, verkrijgt de gebruiker toegang tot het materiaal. We merken op dat het feitelijk gebruik van het leermiddel buiten deze standaard valt. 2.10.1

(Access) Deze functie representeert de feitelijke toegang tot het leermiddel. Het is geen feitelijke webservice, maar representeert de toegangsadres voor de EducationalContentId. De functie is dan ook niet opgenomen in het Technisch model. De toegang verloopt als volgt: 1.

De gebruiker vraagt toegang tot het leermiddel bij de betreffende EntryLocation. Hij geeft hierbij mogelijk het endpoint van de AccountService mee, via welke de gebruiker zich wenst te identificeren en authenticeren.

2.

De betreffende AccountService wordt aangeroepen voor authenticatie van de gebruiker (AuthenticateUser) en de UserId met UserAdministrationId wordt geretourneerd.

3.

Via de LicenseService worden de aan de UserId met UserAdministrationId gekoppelde licentierechten vastgesteld.

4.

Indien de gebruiker niet de benodigde licentierechten bezit, wordt eerst een eventueel Tegoed op naam van de UserId afgeboekt. Indien er geen Tegoed bestaat op naam van de UserId, dan worden de CreditorId’s van de gebruiker uit zijn profiel gelezen via de ProfileService. Indien hier een Tegoed bestaat, dan wordt hier van afgeboekt. Lukt dat niet, of kan het Profiel niet worden gelezen, dan wordt de gebruiker om een code gevraagd. Op basis van het Tegoed of de Code wordt alsnog de licentie gekoppeld.

5.

De gebruiker wordt op basis van UserId met UserAdministrationId toegang verleend.


EntryLocation: toegangsadres van het enkelvoudige leermiddel

2

AccountServiceEndpoint (Optional): de URL van de AccountService via welke de gebruiker zich wenst te identificeren en authenticeren



47 / 68


3. Technisch model (T) De functies van de services worden middels web services beschikbaar gesteld. In dit hoofdstuk worden de technische uitgangspunten voor de koppelvlakken van de Services beschreven. In de technische bijlagen zijn de web services verder uitgewerkt. Tevens zijn er XSD’s beschikbaar van de individuele web services. 3.1

Identificatie

Principes Principe

Iedere Rechtspersoon bepaalt een ketenbreed unieke PartyId. Dit PartyId

(1)

wordt gebruikt ter identificatie bij systeem-naar-systeem (S2S) koppelingen.

Uitleg

Iedere Rechtspersoon kan met een PartyId uniek worden geïdentificeerd.

Rationale

Het PartyId wordt als basis voor vertrouwensrelaties gebruikt tussen Voorzieningen.

Principe

Een Service wordt geïdentificeerd met zijn endpoint.

(2) Uitleg

Het operationele endpoint (URL) van een Services is tegelijkertijd zijn identifier.

Rationale

Services dienen uniek geïdentificeerd te kunnen worden.

Principe

Een endpoint van een Service is duurzaam. Eventuele wijzigingen dienen

(3)

aan de afnemers te worden gecommuniceerd

Uitleg

Endpoints dienen zo duurzaam mogelijk te zijn. Bij wijzigingen dienen alle afnemers van de dienst geïnformeerd worden.

Rationale

De endpoints liggen aan de basis van de gegevensuitwisseling. Wijzigingen hierin kunnen dit ernstig verstoren.

Principe

Iedere aparte versie van een Service heeft een verschillend endpoint.

(4) Uitleg

Indien een nieuwe versie van een Service beschikbaar wordt gesteld aan partners, dan is deze toegankelijk via een verschillend endpoint dan de oude Service.

Rationale

Er wordt vanuit gegaan dat verschillende partners op dezelfde momenten in de tijd verschillende versies van de ECK-standaard gebruiken. Dit betekent doorgaans dat er meerdere versies van dezelfde Service in gebruik zijn. Dit maakt verschillende endpoints voor verschillende versies noodzakelijk.

48 / 68


Principe

Iedere ketenpartner communiceert zijn PartyId, zijn AdministratieId’s en

(5)

de endpoints van de relevante Services per AdministratieId.

Uitleg

Vooraf aan het gebruik van een service dient e.e.a. geregeld te zijn rond authenticatie, autorisatie en gebruiksvoorwaarden. Bij deze afspraken zullen KetentPartners ondermeer elkaars identificerend gegeven uitwisselen (PartyId) als basis voor vertrouwen. Verder worden per AdministratieId de endpoints van de relevante Services gecommuniceerd.

Rationale

De vertrouwensbasis wordt gelegd via de PartyId . De werkrelatie wordt gelegd tussen AdministratieId en Service-endpoints. Op die manier weten partners op basis van een AdministrationId welke AccountService of ProfileService zij kunnen aanroepen voor authenticatie of profielgegevens respectievelijk. Merk op dat ook een intermediaire ketenpartner op deze wijze services kan aanbieden.

3.2

Gebruikers identificeren, authenticeren en ophalen van profielinformatie

Principes

Principe

Voor authenticatie wordt het SAML Web Browser SSO profiel (SP initiated

(1)

SSO with POST/artifact bindings) toegepast De SAML2 specificatie beschrijft een aantal profielen. Het Web Browser SSO profiel (SP initiated SSO with POST/artifact bindings) zorgt ervoor dat er niet via een web browser redirect gegevens uitgewisseld worden, maar enkel een verwijzing. Met deze verwijzing kan later via een web service koppelvlak de informatie opgehaald worden.

Uitleg

Rationale

Door gegevens niet via de browser van de gebruiker te communiceren wordt de veiligheid verhoogd.

Principe (2) Uitleg

De gegevensuitwisseling om de gebruiker te authenticeren is beveiligd. De gegevens worden op transportniveau versleuteld middels enkelzijdige SSLv3/TLS. Een gebruiker authenticeert zich via een AccountService. De credentials die hierbij nodig zijn worden over een beveiligd kanaal naar de AccountService gestuurd.

Rationale

De gegevens worden over internet verstuurd. Door deze te versleutelen zijn deze niet herkenbaar en kunnen niet gewijzigd worden

49 / 68


Principe

Het AuthnRequest wordt door de dienstaanbieder ondertekend en de

(3)

AuthnResponse door de AccountService De AuthnRequest en AuthnResponse berichten worden ondertekend. Dit verhoogd de veiligheid van de gegevensuitwisseling.

Uitleg

SAML en berichten moeten ondertekend worden. Berichten worden versleuteld tijdens het transport via SSL / TLS, maar worden op de computer van de gebruiker gewoon getoond. Door ondertekening heeft het voor onbevoegden geen zin het bericht te wijzigen gezien dit gedetecteerd kan worden. Het risico dat gegevens door onbevoegden worden ingezien is beperkt want het bevat geen gevoelige gegevens. Overweging: Indien op transportniveau tweezijdige authenticatie op basis van SSL/TLS wordt uitgevoerd is ondertekening van het bericht niet noodzakelijk maar wel aanbevolen Rationale

Om integriteit en authenticiteit te garanderen MOET de AuthnRequest en AuthnResponse ondertekend worden.

Principe

Ondertekening is op basis van PKI certificaten met een RSA sleutel van

(4)

2048 bits en toepassing van het SHA-256 algoritme voor het digest.

Uitleg

Versleuteling en ondertekening wordt bij voorkeur op basis van PKI certificaten en betreffende algoritmen uitgevoerd.

Rationale

Eenduidigheid en interoperabiliteit wordt binnen de keten verhoogd met het toepassen van certificaten. Een minder geschikt alternatief is e.e.a. applicatief te ondersteunen (bij dit alternatief zal ook de betreffende plugins beheerd moeten worden).

Principe

De Common Name (CN) van het certificaat bevat de identificatie van de

(5)

KetenPartner (PartyId).

Uitleg

Op basis hiervan wordt de ketenpartner geïdentificeerd en kan op basis hiervan autorisatie plaatsvinden en eventueel aanvullende gegevens bepaald worden zoals het endpoint van een bepaalde service.

Rationale

Ketenpartners worden geauthenticeerd op basis van certificaten. De hierin opgenomen PartyId ondersteunt de autorisatie

Principe

De CN van het certificaat dient gelijk te zijn aan het SAML2.0

(6)

ProviderID/EntityID wat gelijk is aan de PartyId

Uitleg

Op basis van de certificaten en de hiermee samenhangende chain of trust kunnen de aangeboden gegevens vertrouwd worden en als integer worden beschouwd

Rationale

De gegevens uit het certificaat worden gekoppeld aan de SAML Assertions

Principe

De publieke sleutel van de ondertekening is in het betreffende bericht

(7)

opgenomen

Uitleg

Sleutels hoeven niet “out-of-band” uitgewisseld te worden maar zijn altijd opgenomen in het betreffende bericht

Rationale

Om de ondertekening te kunnen verifiëren is de publiek sleutel nodig

Principe

Ketenpartners maken bilateraal afspraken over het gebruik van bepaalde Profielgegevens (autorisaties)

(8) Uitleg

Partijen die gegevens van een ProfileService afnemen moeten geauthenticeerd worden waarna autorisatie kan plaatsvinden. Partijen dienen hierbij vooraf afspraken te maken welke gegevens geleverd mogen worden. Bij deze afspraken behoort ook het overleggen van benodigde endpoints die bij betreffende services

50 / 68


horen, de PartyId waartoe deze behoren en het uitwisselen van publieke sleutels (certificaten voor TLS/SSL communicatie) Rationale

Koppelingen kunnen niet dynamisch tot stand komen zonder dat partijen e.e.a. outof-band geregeld hebben.

3.3

Authenticatie van Ketenpartners

Principes

Principe

Indien een Ketenpartner bij gegevensuitwisseling geauthenticeerd moet

(1)

worden geschiedt dit op basis van certificaten welke middels (tweezijdige) TSL/SSLv3 gecommuniceerd worden

Uitleg

Het voordeel van een PKI certificaat is dat uitgifte beheerd wordt door een Certificate Authority (CA), deze identificeert de organisatie. Identificatie van de Ketenpartner vindt dus plaats bij het uitgifteproces van certificaten. Het identificeren is bij PKI impliciet door de “chain of trust”. Doordat de identiteit een certificaat heeft van een vertrouwde instelling (waar identificatie heeft plaatsgevonden) kan dit certificaat als authenticatiemiddel gebruikt worden bij S2S gegevensuitwisseling. Bij toepassing van deze methode is het identificerend gegeven opgenomen in de Common Name (CN) van het certificaat. Het identificerend gegeven is in dit geval de PartyId.

Rationale

Tweezijdige TSL/SSLv3 zorgt voor beveiliging en ondersteunt authenticatie van de communicerende Voorzieningen.

3.4

Beveiliging web service koppelvlakken

Principes

Principe (1) Uitleg

Beveiliging van de gegevensuitwisseling tussen services wordt op transportkanaal toegepast. Deze vorm van beveiliging op basis van PKI wordt breed toegepast. Er zijn wel ontwikkelingen rond de toe te passen certificaten. Een alternatief als beveiliging op berichtniveau wordt als te complex beschouwd voor de keten en eisen rond beveiliging op berichtniveau ontbreken

Rationale

Beveiliging van het transportkanaal biedt voldoende beveiliging voor de huidige beveiligingseisen.

51 / 68


3.5

Web service standaarden

Principes Principe

Er wordt één web service per service gedefinieerd

(1) Uitleg

Er zijn momenteel geen redenen om meerdere web service per service te definiëren. Later kan mogelijk besloten worden services op te delen i.v.m. efficiëntie of vanwege beveiliging.

Rationale

Op basis van PartyId’s en afspraken rond webservice namen kunnen webservices eenvoudiger gevonden worden. Hoe minder webservices nodig zijn hoe eenduidiger dit uitgevoerd kan worden.

Principe

Als communicatiekanaal wordt internet toegepast

(2) Uitleg

De onderwijssector voor BO, VO en MBO beschikt niet over een eigen afgesloten ketennetwerk. Partijen moeten elkaar goed kunnen bereiken en beheerkosten beperkt blijven. Services die communiceren met ketenpartners gebruiker hiervoor het internet netwerk

Rationale

Bij het ontbreken van een eigen netwerk ligt toepassing van internet voor de hand.

Principe

Bij communicatie over het internet wordt port 80 of 443 toegepast

(3) Uitleg

Bij beveiligde gegevensuitwisseling met toepassing van TLS/SSL wordt port 443 gebruikt. Bij geen beveiliging op transportkanaal wordt poort 80 toegepast

Rationale

Omdat internet toegepast wordt als transport kanaal ligt de keuze voor port 80 voor de hand.

Principe (4) Uitleg

De gegevensuitwisseling tussen Services is op basis van web services. Het berichtformaat hierbij is SOAP 1.143 Een populaire manier van gegevensuitwisseling binnen de keten is SOAP 1.1. Deze standaard is volwassen en kent vele aanvullende standaarden op basis waarvan andere functies geïmplementeerd kunnen worden.

Rationale

Er zijn vele manieren en standaarden om service georiënteerd gegevens uit te wisselen. Door koppelvlakken op basis van een beperkt aantal standaarden te implementeren worden beheer- en implementatielasten beperkt.

Principe (5) Uitleg

Web services worden beschreven op basis van de WSDL44 standaard versie 1.1 De de-facto standaard om SOAP 1.1 web services te beschrijven is WSDL versie 1.1. Deze beschrijving kan door software toolkits geconsumeerd worden om automatische koppelvlakken te implementeren.

Rationale

De functies moeten eenduidig beschreven kunnen worden. Afnemers kunnen deze beschrijving gebruiken bij de implementatie van het koppelvlak

43

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

44

http://www.w3.org/TR/wsdl

52 / 68


Principe

De berichten worden over HTTP 1.1 verstuurd.

(6) Uitleg

Een gangbaar protocol om SOAP berichten te kunnen versturen is HTTP 1.1. Dit protocol wordt al in de keten toegepast.

Rationale

Een breed toegepaste standaard beperkt de kans op het moeten doen van extra investeringen en het zich voordoen van technische problemen. Ook is de kans op kennis bij alle ketendeelnemers groter.

Principe (7) Uitleg

Bij het opstellen van een WSDL worden de elementen op basis van Camel Case45 genoteerd. Een WSDL kan door software toolkits geconsumeerd worden om een web service of web service client te implementeren. Een WSDL wordt beschreven op basis van XML waarbij de elementen door kleine en hoofdletters beschreven kunnen worden.

Rationale

Toolkits gaan verschillend om met het verwerken van kleine en hoofdletters. Om problemen hiermee te beperken worden de onderdelen van een WSDL op een standaard manier beschreven.

3.6

Diakrieten, de tekenset en encoding

Principes Principe (1) Uitleg

Er gelden geen beperkingen aan de te gebruiken karakters anders dan dat ze tot de Unicode karakterset moeten behoren. Er moeten afspraken gemaakt worden gemaakt met betrekking tot de toegestane karakters bij gegevensuitwisseling. De Unicode karakterset is ook bekend als ‘Universal Character Set’ of ook als ‘ISO 10646’.

Rationale

Unicode wordt breed ondersteund: in de gangbare Besturingssystemen, in XML en HTML, in Java en .Net. Hierbij wordt vooralsnog geen subset gedefinieerd voor de karakters die niet gebruikt worden. Deze aanscherping kan eventueel in later stadium uitgevoerd worden.

Principe

Een SOAP bericht wordt volgens UTF-8 ge-encodeerd.

(2) Uitleg

Voor een succesvolle gegevensuitwisseling moet er naast de toegestane karakters ook afspraken rond de (de)encoding gemaakt worden

Rationale

UTF-8 is een zeer gangbare encoding voor Unicode en wordt zeer goed ondersteund. Gebruik van UTF-8 garandeert dat alle nodige inhoud zoals diakritische tekens en het Euroteken ook daadwerkelijk gecodeerd kunnen worden. Ook gegevens die in een bericht gecodeerd dienen te zijn, vallen binnen het UTF-8 formaat.

45

Camel Case is vaak toegepaste notatiewijze om eenduidig termen in technische documenten, zoals een

WSDL, te definiëren (http://en.wikipedia.org/wiki/CamelCase). Dit verhoogt de interoperabiliteit.

53 / 68


3.7

Foutafhandeling

Principes Principe (1)

De webservice hebben een standaard foutmelding bericht. Dit bericht bevat een foutmelding, foutomschrijving en een foutcode. De foutcodes geven een indicatie of het een bericht succesvol is verwerkt (code = 0), of er een fout is opgetreden (code < 0), of dat het bericht verwerkt is maar dat er een waarschuwing van toepassing is (code > 0).

Uitleg

De web services hebben eenduidige foutmeldingen waar mogelijk.

Rationale

Het toepassen van dezelfde generieke foutmeldingen bevordert het kunnen oplossen van problemen en het creëren van een eenduidigheid binnen de hele keten.

54 / 68

55 / 68


4. Vrijwaring gebruik afspraak Hoewel

deze

afspraak

met

de

grootst

mogelijke

zorg

is

opgesteld,

kan

(kunnen

de

rechtsopvolgers van) Edustandaard geen aansprakelijkheid aanvaarden voor de juistheid, volledigheid of bruikbaarheid van de inhoud van dit document. De afspraak zal naar aanleiding van voortschrijdende inzichten en aanbevelingen van gebruikers aangepast kunnen worden. Eventuele kosten voortvloeiend uit deze aanpassingen zijn niet te verhalen op de (rechtsopvolgers van) Edustandaard of haar initiatiefnemers (de stichtingen SURFFoundation en Stichting Kennisnet). De afspraak kan conform de beschreven doelstellingen worden gebruikt. Gebruik van de afspraak gebeurt voor risico van de gebruiker. Het auteursrecht van de afspraak ligt bij (de rechtsopvolgers van) EduStandaard. De afspraak is vrij te verspreiden, te publiceren of te hergebruiken, mits de bron duidelijk vermeld wordt. Dit bestand valt onder de Nederlandse versie van de Creative Commons licentie "Naamsvermelding 3.0 Nederland". Zie http://creativecommons.org/licenses/by/3.0/nl/


5. Bronnen [1]

Wijnand Derks (2011). Wensen en knelpunten voor distributie en toegang van digitale leermiddelen, ECK-programma, Kennisnet, 21 juni 2011.

[2]

Bas Kruiswijk en Arjan Geurts (2012). Vernieuwd pakket van eisen (PvE) leermaterialenketen MBO, versie 2.2, saMBO-ICT, 26 juni 2012.

56 / 68

57 / 68


Bijlage: Deelnemers aan het standaardisatieproces Deelnemer

Organisatie

Stefan van Goor

KlasseTV

Peter Feenstra

Eisma

Mark Posthuma

Edu’Actief

Peter Stokvisch

Edu’Actief

Elze Kool

Edu’Actief

Jelle Pol

Deviant

Jorrit Jansen

Deviant

Hilde van der Togt

Noordhoff

Paul de Wit

Noordhoff

Lútsen Jansen

ThiemeMeulenhoff

Edwin Verwoerd

ThiemeMeulenhoff

Frank van Rooij

Malmberg

Wouter Huijnink

Malmberg

Claartje Bom

Malmberg

Bernadette Verberne

Malmberg

Hans Pronk

GEU

René Montenarie

GEU

Tony Heemskerk

Edupoort

Peter Boersema

Van Dijk Educatie

Herman van der Vegte

Van Dijk Educatie

Ronny Voorhuis

Van Dijk Educatie

Huib Schrijvers

Van Dijk Educatie

Wijnand Spring in ’t Veld

Iddink

Ben Koers

Iddink

Jelle van der Meulen

Iddink

Victor van Deelen

Lisette Werter Groep

Marga Werter

Lisette Werter Groep

Gijs van der Wielen

Schoolmaster

Heleen van der Laan

Schoolmaster

Kees Mastenbroek

Topicus

Johan Meijerhof

Natonco

Jan Kraaijenbrink

Cloudschool

Pascal van den Biggelaar

Three Ships

Roland Leijten

Three Ships

Quirijn Hamel

Itslearning

Judith Zwerver

Itslearning

Stephan Kahmann

Pearson

Arjen Kuik

Stoas

Martin Dias d'Ullois

Kennisnet

Maurice Pasman

Kennisnet

Mark Dobrinic

Kennisnet

Maries Dinaux

Knooppunt MBO

58 / 68


Pascal Marcelis

OMO

Antonie van der Staak

OMO

JaapJan Vroom

ROC6 / Deltion College

Arend Kok

Deltion College

Klaas Wever

Horizon College

Rob Smit

Nova College

Jan Bartling

SAMBO-ICT

Linda LeGrand

Mondriaancollege Oss

Fred Kulik

Carmel

Frank Evers

Kennisnet

Michiel Maas

Kennisnet

Leo Bakker

Kennisnet

Jan-Kees Meindersma

Kennisnet

Frans Schouwenburg

Kennisnet

Arjan van Venrooy

ECK

Jim Bijlstra

ECK

Erwin Reinhoud

ECK

Willem-Jan van Elk

LiMBO

Nico Verbeij

ECK

Wijnand Derks

ECK

Hans de Vries

SLO

Henk Nijstad

EduStandaard

Jeroen Hamers

EduStandaard

HP Köhler

Kennisnet/EduStandaard


Bijlage: Algemene web service specificaties Zie document ECK-DTDL dec12 Algemene specificaties voor web service v1.5.docx

59 / 68


Bijlage: ProfileService web service specificatie Zie document ECK-DTDL dec12 Web service ProfileService v1.5.docx

60 / 68


Bijlage: AccountService web service specificatie Zie document ECK-DTDL dec12 Web service en Authenticatie AccountService v1.5.docx

61 / 68


Bijlage: ProductListService web service specificatie Zie document ECK-DTDL dec12 Web service ProductListService v1.5.docx

62 / 68


Bijlage: EducationalContentListService web service specificatie Zie document ECK-DTDL dec12 Web service EducationalContentListService v1.5.docx

63 / 68


Bijlage: OrderService web service specificatie Zie document ECK-DTDL dec12 Web service OrderService v1.5.docx

64 / 68


Bijlage: PaymentService web service specificatie Zie document ECK-DTDL dec12 Web service PaymentService v1.5.docx

65 / 68


Bijlage: DistributionService web service specificatie Zie document ECK-DTDL dec12 Web service DistributionServicev1.5.docx

66 / 68


Bijlage: LicenseService web service specificatie Zie document ECK-DTDL dec12 Web service LicenseServicev1.5.docx

67 / 68


Bijlage: EntryLocationServicehuis web service specificatie Zie document ECK-DTDL dec12 Web service EntryLocationService v1.5.docx

68 / 68

DISTRIBUTIE EN TOEGANG VAN DIGITALE LEERMIDDELEN Deel II: Functioneel en Technisch model

Recommend Documents