IN3405 Bachelor Project
Eindverslag: Deliverance 6 juli 2011
Technische Universiteit Delft Opleiding: EWI - Technische Informatica - Software Technologie Studenten: Stefan van Wouw - 1543776 Lucas de Vries - 1522442 Bedrijf: Internationaal Instituut voor Sociale Geschiedenis Commissie: Ir. B.R. Sodoyer - Begeleidend docent en co¨ordinator TU Delft Dhr. E. Tuskan - Projectleider IISG
Voorwoord Dit rapport is het eindverslag van het vak IN3405 Bachelor Project, dat deel uit maakt van de bachelor opleiding Technische Informatica aan de Technische Universiteit Delft. Het bachelor project is het laatste vak van de opleiding waarin het de bedoeling is dat de opgedane kennis wordt toegepast tijdens een 10 tot 12 weken durende stage bij een bedrijf. Wij hebben deze stage uitgevoerd bij het Internationaal Instituut voor Sociale Geschiedenis (IISG), te Amsterdam. Wij willen graag het IISG en alle betrokken medewerkers bedanken voor het mogelijk maken van deze leerzame stage. Daarnaast willen wij dhr. Tuskan bedanken voor het co¨ordineren van het project binnen het IISG, en ir. Sodoyer voor de inhoudelijke begeleiding van de stage.
Delft, juli 2011 Lucas de Vries Stefan van Wouw
i
Samenvatting Het Internationaal Instituut voor Sociale Geschiedenis (IISG) beheert circa 3000 archieven, 1 miljoen boeken en tijdschriften en een rijke collectie beeld- en geluidsmateriaal. De meeste stukken die het IISG in beheer heeft zijn voor bezoekers vrij in te zien, wat mogelijk is op de speciaal daarvoor ingerichte studiezaal. Naast de fysieke collectie kunnen er ook reproducties van stukken (in de vorm van hoge resolutie bestanden en PDFs) worden besteld. Het IISG heeft hiervoor een aparte reproductie afdeling, die ervoor zorgt dat bestelde reproducties bij de klant terecht komen. De processen voor de inzage van fysieke stukken en voor de bestelling van een digitale reproductie binnen het IISG verlopen vooralsnog volledig handmatig. Om deze processen te automatiseren, te stroomlijnen en te versimpelen, is er tijdens de stage een prototype van een software systeem ontwikkeld dat dit bewerkstelligt. Voordat er begonnen is aan het ontwerpen en het implementeren van het systeem, is er eerst onderzoek gedaan naar zowel de bestaande systemen als bestaande standaarden binnen de archiveringswereld. Ook is er een bezoek gebracht aan het Stadsarchief Amsterdam ter verdere ori¨entatie. Na deze ori¨entatiefase zijn de eisen aan het systeem verzameld door het observeren van de processen op de werkvloer en door het houden van diverse gesprekken met betrokken medewerkers van het IISG. Er is daarna een globaal ontwerp gemaakt van het systeem, dat zowel het reserveren van fysieke stukken als het aanvragen van reproducties moet faciliteren. Hierbij is gekozen om een systeem op maat te maken, omdat de vereiste functionaliteit te veel afwijkt van de functionaliteit die bestaande systemen bieden. Aan het einde van de ontwerpfase is besloten om tijdens de stage slechts een deel van het systeem te implementeren. Dit betreft het deel dat verantwoordelijk is voor het afhandelen van reserveringen om fysieke stukken in te zien. Voor dit deel is een gedetailleerd ontwerp gemaakt en er is zowel een test- als implementatieplan opgesteld. Vervolgens is een prototype van dit deel van het systeem iteratief ge¨ımplementeerd. Er zijn in totaal 2 iteraties geweest met na elke iteratie een evaluatie gesprek, waar werd gekeken in hoeverre de doelstellingen waren gehaald. Uiteindelijk is er een werkend prototype opgeleverd dat aan de gestelde formele eisen voldoet, en waarmee de opdrachtgever bovendien tevreden is. In dit prototype is het via een web interface mogelijk om reserveringen te plaatsen om stukken in te kunnen zien. Het systeem houdt de locatie van de stukken bij en het is mogelijk om te specificeren welke inzage- en gebruiksrestricties er op een stuk gelden. De medewerkers kunnen een reservering uitprinten, zodat ze kunnen zien welke stukken er waar en wanneer uit het magazijn moeten worden opgehaald. Door de barcode op een van de uitgeprinte vellen te scannen kan de status van een reservering worden aangepast. Om het prototype om te zetten tot een systeem dat in een productie-omgeving kan draaien, dienen er nog een aantal stappen uitgevoerd te worden. Hieronder vallen het integreren van de huisstijl van het IISG, het koppelen van gebruikersauthenticatie aan CAS/LDAP en het uitvoeren van acceptatietests.
ii
Inhoudsopgave Voorwoord
i
Samenvatting
ii
1 Inleiding
1
2 Organisatie 2.1 Aanpak . . . . . . . 2.2 Fasering . . . . . . . 2.3 Deliverables . . . . . 2.4 Evaluatiemomenten .
. . . .
3 3 3 4 4
3 Onderzoek 3.1 Integrated Library Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Standaarden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Stadsarchief Amsterdam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 5 5 6
4 Analyse 4.1 Requirements . . . . 4.2 Toestandsovergangen 4.3 Systeem Interacties . 4.4 Voorbeeldinterface .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
7 7 8 8 9
Systeem . . . . . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
10 10 11 12 12
6 Implementatie 6.1 Planning en Resultaten . . . . . . . . . . . . . 6.2 Gebruikte Programmeertaal, Tools en Libraries 6.3 Structureel Ontwerp . . . . . . . . . . . . . . . 6.4 Test Methodiek . . . . . . . . . . . . . . . . . . 6.5 Code Evaluatie SIG . . . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
13 13 14 15 16 17
. . . . . Stukken . . . . . . . . . .
5 Ontwerp 5.1 Maatwerk vs Bestaand 5.2 Subsystemen . . . . . 5.3 Database . . . . . . . 5.4 API . . . . . . . . . .
7 Conclusies en Aanbevelingen 19 7.1 Resultaten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 7.2 Aanbevelingen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 7.3 Reflectie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Verklarende Woordenlijst
21
A Opdrachtomschrijving
25
B Plan van Aanpak
28 iii
C Logboek
34
D Ori¨ entatieverslag
40
E Requirements Document
51
F Architectural Design Document
84
G Technical Design Document
105
iv
Hoofdstuk 1
Inleiding Het Internationaal Instituut voor Sociale Geschiedenis (IISG) beheert circa 3000 archieven, 1 miljoen boeken en tijdschriften en een rijke collectie beeld- en geluidsmateriaal. De meeste stukken die het IISG in beheer heeft zijn voor bezoekers vrij in te zien, wat mogelijk is op de speciaal daarvoor ingerichte studiezaal. Er zijn ook een aantal stukken die pas na een bepaalde datum in te zien zijn, of als de eigenaar van het archief er expliciet toestemming voor heeft gegeven. Er bestaan gebruiksrestricties op stukken. Bepaalde stukken zijn te kostbaar om zonder speciale voorzorgsmaatregelen te worden ingezien. De originele exemplaren van deze stukken mogen daarom niet door bezoekers worden bekeken. In plaats daarvan wordt er een kopie van het origineel, zoals een microfilm, aan de bezoeker overhandigd. Naast de fysieke collectie kunnen er ook reproducties van stukken (in de vorm van hoge resolutie bestanden en PDFs) worden besteld. Het IISG heeft hiervoor een aparte reproductie afdeling, die ervoor zorgt dat bestelde reproducties bij de klant terecht komen. Probleemstelling De processen voor de inzage van fysieke stukken en voor de bestelling van een digitale reproductie binnen het IISG verlopen vooralsnog volledig handmatig. Om een stuk in te zien dient een papieren formulier ingevuld te worden. Doordat de status en locatie van een stuk niet centraal staan opgeslagen is het vaak pas bekend of stukken ingezien kunnen worden als bezoekers al ter plaatse zijn. Vervolgens moeten deze bezoekers vaak lang wachten totdat hun aangevraagde stuk uit het magazijn is gehaald omdat er veel tijd gemoeid is met het opzoeken van de status en locatie van de aangevraagde stukken. De status van de stukken wordt namelijk bijgehouden in een kaartenbak en de locatie in een spreadsheet, welke met de hand moeten worden doorzocht. Als het stuk na inzage weer teruggebracht wordt, moet opnieuw de locatie opgezocht worden om te weten waar het stuk in het magazijn hoort te staan. Het bestellen van reproducties gebeurt nu door het sturen van een e-mail naar de organisatie, waar na controle van de betaling handmatig de bestanden op een FTP server worden gezet. Een FTP account wordt aangemaakt voor de klant en daarna worden de inloggegevens met de hand in een e-mail naar de klant verstuurd. Projectdoel Dit project heeft als doel om de processen die bij de reservering van archiefstukken of de bestelling van een reproductie komen kijken te automatiseren en te stroomlijnen. Daarnaast dient het opzoeken en bijhouden van de status van de stukken versimpeld te worden. Er is tijdens de stage een software systeem ontwikkeld (in vorm van een prototype), dat dit doel bewerkstelligt. Structuur In dit verslag wordt beschreven hoe het ontwikkelde systeem tot stand is gekomen. Allereerst wordt de organisatie van het project beschreven in hoofdstuk 2. Daarna wordt in hoofdstuk 3 het vooronderzoek besproken, wat uitgevoerd is ter ori¨entatie op de al aanwezige systemen en standaarden in de archiveringswereld. De eisen aan het systeem en de totstandkoming daarvan worden besproken in hoofdstuk
1
4. Het daaropvolgende ontwerp en de implementatie van het prototype is uiteengezet in respectievelijk hoofdstuk 5 en 6. Tot slot zijn in hoofdstuk 7 de conclusies, aanbevelingen en persoonlijke ervaringen te lezen.
2
Hoofdstuk 2
Organisatie Dit hoofdstuk beschrijft hoe we het stage project hebben gestructureerd en gefaseerd. Ook worden de deliverables en evaluatiemomenten besproken.
2.1
Aanpak
Aan het begin van het project hebben we een Plan van Aanpak (bijlage B) opgesteld om duidelijk te maken wat precies de projectstructuur zou worden. Bij het schrijven van het plan van aanpak hebben we besloten om, na de ori¨entatiefase, te beginnen met een analyse- en ontwerpfase gevolgd door een iteratief opgebouwde implementatiefase. Omdat de nodige concepten en structuren voor het systeem van te voren duidelijk moesten zijn hebben we allereerst documenten betreffende de eisen en het globale ontwerp opgesteld. Dit zijn het Requirements document (bijlage E) en het Architectural Design document (bijlage F). Het specifieke deel dat ge¨ımplementeerd is binnen de context van dit project is later pas uitgewerkt in het Technical Design document (bijlage G). Al deze documenten zijn zowel naar aanleiding van feedback en tijdens de implementatiefase voortdurend aangepast op nieuw ontdekte situaties. Het deel van het systeem dat na afloop van het project werkend moest zijn hebben we milestone 1 genoemd. Binnen het IISG kunnen voor de overige functionaliteit (die wel globaal in het Architectural Design document is ontworpen) nog verdere milestones worden opgezet. De implementatie van milestone 1 heeft plaatsgevonden in twee iteraties met bijhorende systeem tests en evaluatiemomenten. Het betreft hier dus een 2-traps iteratief project.
2.2
Fasering
Voor de planning van het project hebben we allereerst een globale fasering opgesteld aan de hand van de bedachte aanpak. Hoewel er overlap plaatsvindt, voornamelijk bij het updaten van de ontwerpdocumentatie tijdens de implementatie van de iteraties, hebben we de weken van het project als volgt ingedeeld: Week 1 2 3 4 5 6 7 8 9 10 11
Taak Plan van Aanpak en Ori¨entatieverslag Ori¨entatieverslag Requirements Architectural Design Technical Design Iteratie 1 Evaluatie Iteratie 1 + Iteratie 2 Iteratie 2 Eindverslag + Evaluatie Iteratie 2 Eindverslag / Eindpresentatie
3
Er is een logboek bijgehouden van de activiteiten per dag, te vinden in bijlage C.
2.3
Deliverables
Gedurende het project zijn er na elke fase deliverables gemaakt en ingeleverd. Op de implementatie en gegenereerde code documentatie na zijn deze allen bij dit document bijgesloten. De gemaakte deliverables zijn: • Plan van Aanpak (Zie bijlage B) • Ori¨entatieverslag (Zie bijlage D) • Requirements (Zie bijlage E) • Architectural Design (Zie bijlage F) • Technical Design (Zie bijlage G) • Implementatie (iteraties 1-2) inclusief unit tests • Code Documentatie (doxygen) • Eindverslag
2.4
Evaluatiemomenten
Voor zowel het Architectural Design document als het Technical Design document zijn aan het begin van het project twee evaluatiemeetings gepland. De verificatie van de requirements heeft op een meer ge¨ıtereerde manier plaatsgevonden (Zie hoofdstuk 4). Tijdens deze evaluatiemeetings zijn de ontwerpconcepten en de genomen beslissingen besproken, waarna de documenten zijn aangepast naar aanleiding van de besproken veranderingen en opnieuw ingezonden. Het is na deze bewerking niet voorgekomen dat er een tweede evaluatie moest worden gepland, maar deze optie is niet uitgesloten. Na afloop van het implementeren van de gekozen functionaliteit in elke iteratie (zie hiervoor sectie 6.1) zijn de resultaten besproken en is het product gedemonstreerd tijdens de evaluatiemeetings. Tijdens de evaluatie van de iteraties is er besproken welke functionaliteiten er ge¨ımplementeerd waren en welke functionaliteiten er nog moesten volgen in de volgende iteratie. Er is bij elke geplande functie een demonstratie gegeven met test data, waarna er feedback is gegeven en aanpassingen zijn besproken. Tijdens de presentatie van de laatste iteratie hebben we ook onze aanbevelingen voor de voortzetting van het project gegeven.
4
Hoofdstuk 3
Onderzoek Voordat er begonnen is aan het vergaren van eisen aan het systeem en het bouwen ervan, hebben we ons eerst geori¨enteerd op de al bestaande systemen die mogelijk gebruikt zouden kunnen worden voor het automatiseren van de dienstverlening bij het IISG. We kwamen er al snel achter dat er voor het automatiseren van de dienstverlening bij bibliotheken en soortgelijke instellingen als archieven en musea vaak gebruik wordt gemaakt van een een Integrated Library System (ILS). Een ILS biedt een oplossing voor diverse zaken die voorheen met de hand werden gedaan, zoals het beheren en doorzoeken van de catalogus, en het reserveren en uitlenen van stukken. Omdat het IISG van plan is om gebruik te gaan maken van twee van zulke ILS systemen, en er veel overeenkomsten zijn tussen de werkwijze van het IISG en de mogelijkheden die een ILS biedt, hebben we besloten om ons hier verder op te ori¨enteren. Naast de ori¨entatie op de Integrated Library Systems hebben we gekeken wat de bestaande standaarden voor het beschrijven en uitwisselen van catalogus informatie zijn en hebben we het Stadsarchief Amsterdam bezocht om te kijken wat voor oplossingen zij hebben gevonden voor de problemen waar het IISG nu mee kampt. De waarnemingen tijdens het onderzoek zijn in dit hoofdstuk kort weergegeven. Voor een uitgebreidere documentatie verwijzen we naar het Ori¨entatieverslag dat te vinden is in bijlage D.
3.1
Integrated Library Systems
Er zijn diverse Integrated Library Systems op de markt, zowel open source als closed source. Tijdens de ori¨entatie is er een selectie gemaakt uit de bestaande systemen, waarbij naast de hoeveelheid gebruikers en de innovativiteit ook veel gekeken is naar open source systemen, omdat het IISG een doelstelling heeft om alleen maar open source software te gebruiken. De systemen Evergreen, Koha, Aleph en VuFind zijn onderzocht en op een aantal veelvoorkomende Integrated Library System aspecten met elkaar vergeleken. Hiervoor is gebruik gemaakt van de documentatie en beschikbare demo’s van deze systemen. De aspecten waar op vergeleken is, zijn: Catalogus beheer, Zoeken, Registratie, Circulatie, Authenticatie, Acquisitie, Reserveren, Digitale Afgeleiden, en Privacy. Uit deze vergelijking is gebleken dat behalve voor de digitale afgeleiden, elk van de systemen de gekozen aspecten voldoende ondersteunt.
3.2
Standaarden
Om bekend te worden met de veelgebruikte standaarden voor datarepresentatie, aggregatie en indexatie in de archiveringswereld, hebben wij er een aantal onder de loep genomen. Deze zijn hieronder kort weergegeven. MARC en EAD MARC staat voor “MAchine-Readable Cataloging” en is een standaard voor het opslaan van bibliografi-
5
sche informatie. Datavelden zijn numeriek gerepresenteerd en kunnen subvelden hebben. Velden kunnen informatie bevatten over algemene eigenschappen (auteur, publicatiedatum, ISBN) maar ook specifieke informatie als de fysieke locatie en het aantal exemplaren. De Encoded Archival Description (EAD) is een andere standaard voor het representeren van informatie over stukken waarbij de nadruk ligt op hierarchische relaties. Hiermee kunnen bijvoorbeeld archieven worden gespecificeerd. Z39.50, SRU en Dublin Core Z39.50 is een standaard voor het uitvoeren van zoekqueries en het verzenden van informatie van computer databases. Zoekfunctionaliteiten voor het uitlenen van boeken tussen verschillende bibliotheken worden vaak ge¨ımplementeerd als Z39.50 communicatie. Het SRU protocol is ontstaan na verschillende pogingen tot modernisatie van het Z39.50 protocol en dient hetzelfde doel. Het SRU formaat bevat naast alle andere velden een data veld, waarvan de inhoud vaak gespecificeerd is door de Dublin Core standaard. OAI-PMH Het OAI-PMH protocol, wat staat voor “Open Archives Initiative Protocol for Metadata Harvesting” is een protocol om grote hoeveelheden metadata op te vragen via een uniforme interface over het web. Het protocol wordt bijvoorbeeld gebruikt door Wikipedia, om artikel updates door te geven aan zoekmachines.
3.3
Stadsarchief Amsterdam
Om te kijken hoe andere archiefinstellingen hun dienstverlening hebben geautomatiseerd, hebben we een bezoek gebracht aan het Stadsarchief van Amsterdam. Toen we daar aankwamen werden we naar een vergaderkamer geleid waar werd verteld hoe het Stadsarchief precies te werk gaat. Bij het Stadsarchief worden er in principe geen fysieke stukken meer ter inzage gegeven als deze reeds zijn gedigitaliseerd. Gedigitaliseerde stukken zijn in een te zien via een webinterface. Een bezoeker dient een account aan te maken en dan kunnen er scans worden besteld met het scantegoed dat op dat account staat. Reproducties van beeldmateriaal kunnen worden besteld in een webshop. Na het gesprek in de vergaderkamer kregen we een demonstratie van dit systeem. Daarna werd uitgelegd hoe het inzien van nog niet gedigitaliseerde stukken in zijn werk gaat. Bezoekers dienen een speciaal pasje aan te vragen welke wordt gebruikt om de bezoeker te kunnen identificeren. We kregen te zien hoe het proces om een stuk in te zien verloopt. Een bezoeker vraagt een stuk aan via een webinterface. Vervolgens komt deze aanvraag uit de printer bij de afdeling logistiek, die het aangevraagde stuk ophaalt uit het magazijn. De status van een archiefstuk wordt bijgehouden, en kan worden gewijzigd door de barcode op het printvel te scannen. Tijdens het bezoek aan het Stadsarchief hebben we een aantal dingen gezien die we hebben meegenomen bij het ontwerpen van het systeem voor het IISG. De workflow van de stukken bijvoorbeeld, lijkt erg op hoe de mensen van het IISG zich de toekomstige workflow hadden voorgesteld.
6
Hoofdstuk 4
Analyse In dit hoofdstuk worden de resultaten van de analyse fase van het project weergegeven. Dit zijn de eisen aan het systeem en afgeleiden daarvan zoals use cases en voorbeeldschermen.
4.1
Requirements
Voor het opstellen van de requirements zijn verschillende gesprekken gevoerd met medewerkers uit zowel de studiezaal als de reproductie-afdeling. Daarnaast zijn een aantal processen op de werkvloer ge¨ observeerd, en zijn een aantal idee¨en die ooit op papier waren gezet bestudeerd. Nadat de huidige situatie bekend was hebben we een tentatieve opsomming van requirements van het te maken systeem opgesteld, en zijn we vervolgens nogmaals in gesprek gegaan voor de evaluatie. Omdat er tijdens deze gesprekken verscheidene veranderingen aan de voorgestelde workflows zijn voorgesteld, hebben we hierna nog een keer over het requirements document ge¨ıtereerd en heeft er een tweede evaluatie plaatsgevonden. Na het verwerken van de feedback en het optimaliseren van de voorgestelde workflows is de volgende lijst met functionele requirements opgesteld. Voor gedetailleerde omschrijvingen van elke benoemde requirement en voor een lijst van niet-functionele requirements, zie hoofdstuk 2 van het Requirements document (bijlage E). • [F:1] Uitleenstatus opvragen • [F:2] Stukken aanvragen • [F:3] Digitale reproductie kopen • [F:4] Toestemming verzoeken • [F:5] Inloggen medewerker • [F:6] Metadata invullen/bewerken • [F:7] Aanvragen bekijken • [F:8] Status van een aanvraag aanpassen • [F:9] Toestemming voor inzage bemiddelen • [F:10] Offerte digitalisatie • [F:11] Inscannen van stukken • [F:12] Bijhouden status van een stuk • [F:13] Bijhouden metadata over stukken • [F:14] Aanvragen automatisch uitprinten • [F:15] Geen registratie (account) voor bezoekers 7
4.2
Toestandsovergangen Stukken
Een belangrijke vraag bij het onderzoeken van de requirements was welke verschillende statussen en statusovergangen van stukken op te nemen in het ontwerp. Het aantal interacties tussen de medewerkers en het systeem moet minimaal gehouden worden voor een soepele workflow. Omdat het systeem toch moet weten waar de stukken op het moment aanwezig zijn hebben we de volgende statussen ge¨ıdentificeerd. Dit diagram (figuur 4.1) is opgesteld naar aanleiding van gesprekken met verschillende medewerkers van het IISG die met deze workflow te maken zouden krijgen.
!
Figuur 4.1: Toestandsdiagram Stukken
4.3
Systeem Interacties
Om de interacties tussen het systeem en de gebruiker weer te geven zijn er in het Requirements document voor de meest voorkomende acties use cases opgesteld. Elke use case beschrijft de stappen die door zowel de gebruiker als het systeem worden ondernomen en in welke volgorde dit gebeurt. De use cases zijn gepresenteerd aan de medewerkers van het IISG en er is hieruit nuttige feedback voortgekomen: de informatie- en plaatsvervangersvellen zouden automatisch uitgeprint moeten worden indien deze een reservering representeren die op de huidige dag is geplaatst. De use cases die in hoofdstuk 3 van het Requirements document (bijlage E) beschreven staan zijn:
8
• 3.1.1 Reserveren van stukken • 3.1.2 Bestel een digitale reproductie • 3.1.3 Toestemming aanvragen • 3.2.1 Inloggen • 3.2.2 Metadata aanpassen • 3.3.1 Aanvragen ophalen • 3.3.2 Toestemming geven/weigeren • 3.1.1 Reserveren van stukken • 3.3.3 Stuk wordt teruggebracht • 3.4.1 Stuk inscannen • 3.4.2 Prijsopgave invoeren
4.4
Voorbeeldinterface
Om een visuele weergave te maken van het proces dat de gebruikers en medewerkers moeten doorlopen tijdens de use cases, zijn er in de analysefase ook mockups van de user interface opgesteld. Voorbeelden van de volgende schermen zijn in hoofdstuk 4 van het Requirements document (bijlage E) te vinden: • 4.1 Printoverzicht • 4.2 Stukken reserveren • 4.3 Reproducties bestellen • 4.4 Aanvraagoverzicht • 4.5 Metadata Aanpassen • 4.6 Aanvraag Toestemming • 4.7 Toestemming Geven
9
Hoofdstuk 5
Ontwerp In de ontwerpfase hebben we alle globale elementen van het systeem gespecificeerd. Dit zijn de elementen die niet afhankelijk zijn van de specifieke implementatiedetails, zoals APIs die van buitenaf zichtbaar zijn, of het database ontwerp. Het opgeleverde ontwerpdocument is goedgekeurd in een evaluatiegesprek met de aanwezigheid van de projectleiding en een ontwikkelaar van het IISG. Tijdens de implementatiefase zijn geleidelijk elementen die nog in het ontwerp misten toegevoegd. Dit waren bijvoorbeeld nieuwe API calls of velden in de database waarvan duidelijk werd dat ze nodig waren. De rest van dit hoofdstuk beschrijft de afweging tussen een bestaand systeem en maatwerk, de opdeling in subsystemen, het database ontwerp, en de te implementeren API.
5.1
Maatwerk vs Bestaand Systeem
De eerste beslissing die genomen moest worden bij het ontwerpen van het systeem was of er een volledig op maat gemaakt systeem zou worden opgezet of dat er een plugin zou worden gemaakt voor een bestaand systeem. Tijdens de onderzoeksfase hebben we een aantal systemen bekeken, waaronder systemen die al voor andere doeleinden binnen het IISG in gebruik zijn of worden genomen (Evergreen en VuFind). We hebben gekeken in hoeverre de functionaliteiten die tijdens de analysefase naar boven zijn gekomen al ondersteund werden door deze systemen, en hoeveel er gemodificeerd of toegevoegd zou moeten worden. Uiteindelijk hebben we om verschillende redenen gekozen om een eigen systeem te ontwikkelen. Een van de voornaamste redenen hiervoor was de harde eis vanuit het IISG dat er voor het reserveren van stukken geen accounts nodig moesten zijn: het invullen van een naam en e-mail adres moet voldoen. Omdat alle ILS systemen die we onderzocht hebben zich baseren op een leden en registratiesysteem, zouden we voor de implementatie van het reserveringsdeel een groot deel van de systemen moeten veranderen. Een van de functies van het systeem moest zijn dat er op inventarisnummer kon worden gereserveerd. Dat wil zeggen dat elk archief in onderdelen is opverdeeld en dat de onderdelen ook los kunnen worden aangevraagd. Dit was een level van detail dat niet door de ILS systemen ondersteund werd. Omdat het systeem ook andere metadata en gegevens over inzagerestricties bij moet houden, zouden deze ook los moeten worden ingevoerd in een gekozen systeem. Het IISG heeft ook aangegeven dat ze deze gegevens liever in een losse database wilden hebben staan. Hier komt bij dat de ILS systemen die door het IISG in gebruik zijn allemaal een erg specifiek afgebakende functie hebben binnen de volledige workflow, en het uitbreiden hiervan zou de netheid van de informatiestroom inperken. Om deze redenen hebben we gekozen om een nieuw systeem te implementeren.
10
5.2
Subsystemen
Tijdens het ontwerpen hebben we het systeem opgesplitst in de in figuur 5.1 gespecificeerde subsystemen. Elk subsysteem beheert aparte functionaliteit en heeft aparte APIs en database entiteiten.
Figuur 5.1: Globale decompositie in subsystemen
5.2.1
Gebruikers
Het subsysteem voor gebruikersbeheer laat administrators nieuwe accounts toevoegen en rollen/groepen aanpassen van bestaande gebruikers, en beheert bovendien de authenticatie en loginsessies van gebruikers.
5.2.2
Metadata
Het record management subsysteem biedt functionaliteit om de opgeslagen metadata over stukken in de database op te vragen en aan te passen.
5.2.3
Reserveringen
Met het subsysteem voor reservation management kunnen reserveringen worden aangemaakt door bezoekers en kunnen de medewerkers reserveringsinformatie opvragen, uitprinten en bewerken. Onder dit subsysteem valt ook het inscannen van barcodes voor stukken, waarmee de status reserveringen worden bijgehouden.
5.2.4
Permissies
Permission management beheert de aanvragen voor toestemming die door bezoekers zijn aangemaakt. Bezoekers kunnen via dit subsysteem een formulier invullen om toestemming te vragen om een beperkt archief in te zien. Medewerkers kunnen daarna de aanvragen bekijken en, na bemiddeling met de contactpersoon van het archief, de aanvraag autoriseren of afwijzen. 11
5.3
Database
Voor het representeren en opslaan van de metadata van stukken en overige informatie benodigd in het systeem hebben we gekozen om een relationele database te gebruiken. Na geanalyseerd te hebben welke gegevens er per requirement en use case moeten worden opgeslagen, hebben we het generieke database diagram in hoofdstuk 3 van het Architectural Design document (bijlage F) opgesteld. Deze database is zoals alle andere dingen in het Architectural Design document ge¨evalueerd in de daarvoor geplande meeting, en is nagekeken door een van de ontwikkelaars van het IISG.
5.4
API
Vanuit de interface waaruit bezoekers naar stukken zoeken moet aan het reserveringssysteem kunnen worden opgevraagd of een stuk beschikbaar is en/of er inzagerestricties op zitten. Het zoeksysteem baseert hierop of er een knop om een reservering of bestelling te plaatsen aanwezig is. In overleg met de ontwikkelaar die deze functionaliteit binnen het zoeksysteem gaat implementeren hebben we besloten om een op REST-principes gebaseerde HTTP API te maken. De API maakt gebruik van JSON en JSONP voor het representeren en overgeven van data, en staat volledig gespecificeerd in hoofdstuk 4 van het Architectural Design document (bijlage F).
12
Hoofdstuk 6
Implementatie In de implementatiefase hebben we een prototype van het ontworpen systeem gebouwd. Deze fase wordt beschouwd als milestone 1 van het algehele ontwikkeltraject. Het ontwerp beschreven in hoofdstuk 5 is vrij globaal. Daarom is er, voordat er begonnen is aan het implementeren van het prototype, eerst een gedetailleerd ontwerp gemaakt voor dat deel van het systeem. Tijdens de implementatie is zowel dit Technical Design als het globale Architectural Design telkens bijgewerkt naar de nieuwe inzichten die we tijdens de implementatie kregen. In dit hoofdstuk wordt de implementatiefase van het project besproken. Zowel de planning en gebruikte tools en libraries, als het gedetailleerde ontwerp en de gebruikte test methodiek komen aan bod. Tot slot wordt de code evaluatie besproken die door de Software Improvement Group (SIG) gegeven is.
6.1
Planning en Resultaten
In overleg met de ontwikkelaars en de projectleider hebben we afgesproken welk deel van het systeem ge¨ımplementeerd zou worden. Het deel van het systeem wat het bestellen van reproducties mogelijk maakt is afhankelijk van nog niet bestaande externe systemen. Daarom hebben we ook gekozen om niet dit deel, maar het reserveringsgedeelte van het systeem te gaan implementeren. Er zijn twee iteraties geweest van elk twee weken. Na elke iteratie is er een evaluatie gesprek gehouden waar zowel de projectleider als een aantal ontwikkelaars bij aanwezig is geweest. We presenteerden het geleverde werk aan de hand van een demonstratie, en namen daarna feedback in ontvangst. Mensen dachten actief mee om oplossingen te vinden voor kleine problemen waar we tegenaan liepen. Over het algemeen waren ze tevreden met het resultaat. De opmerkingen die ze hadden gingen vooral over details (extra database velden e.d.). Deze opmerkingen hebben we na de evaluatie meteen verwerkt. Naast de evaluatie gesprekken hebben we na iteratie 2 ook een korte demonstratie gegeven van het prototype. Dit gebeurde tijdens een halfjaarlijkse personeelsbijeenkomst van het IISG, waarin alle huidige ICT projecten de revue passeerden. Hieronder volgt het MoSCoW schema per iteratie. Daarbij is respectievelijk met een vinkje of een kruisje aangegeven of wel of niet aan de requirement is voldaan. Dit is besloten aan de hand van het testscript bijgevoegd bij het Technical Design Document uit bijlage G. Er is bewust gekozen om het sturen van toestemmingsverzoeken naar contactpersonen niet te implementeren, omdat het achterliggende beleid nog niet aanwezig is. Het automatisch uitprinten van aanvragen hebben we niet ge¨ımplementeerd omdat het ons uiteindelijk toch handiger leek om dat te doen bij het installeren van het systeem op een test/productieserver. Printfunctionaliteit is namelijk afhankelijk van het besturingssysteem en de aanwezige printers.
13
Legenda M S C W
Must have Should have Could have Won’t have (but would like)
Iteratie 1
! ! ! ! ! ! ! ! ! !
Prioriteit M M M S S S S C C C
Timespan Week 1 Week 1 Week 1 Week 2 Week 2 Week 2 Week 2 Week 2 Week 2 Week 2
Requirement [F:13] Bijhouden metadata over stukken [F:12] Bijhouden status van een stuk [F:6] Metadata invullen/bewerken [F:2] Stukken aanvragen [F:2a] Maximaal 3 stukken per aanvraag [F:2c] Reserveren huidige dag voor 16:00 [F:1] Uitleenstatus opvragen [F:7] Aanvragen bekijken [F:2b] Wachtnummer aanvragen huidige dag [F:14a] Informatie- en plaatsvervangingsvellen printen
Prioriteit M M M M M M M M S S S S C C W
Timespan Week 3 Week 3 Week 3 Week 3 Week 3 Week 3 Week 3 Week 3 Week 4 Week 4 Week 4 Week 4 Week 4 Week 4 Week 4
Requirement [F:5] Inloggen medewerker [F:15] Geen registratie (account) voor bezoekers [F:7] Aanvragen bekijken [F:8] Status van een aanvraag aanpassen [F:1] Uitleenstatus opvragen [F:2] Stukken aanvragen [F:2a] Maximaal 3 stukken per aanvraag [F:2c] Reserveren huidige dag voor 16:00 [F:4] Toestemming verzoeken [F:2b] Wachtnummer aanvragen huidige dag [F:9] Toestemming voor inzage bemiddelen [F:14a] Informatie- en plaatsvervangingsvellen printen [F:14] Aanvragen automatisch uitprinten [F:4a] Bericht ter goedkeuring/afwijzing toestemming [F:9a] Toestemmingsverzoek direct naar contactpersoon
Iteratie 2
! ! ! ! ! ! ! ! ! ! ! ! # ! # 6.2
Gebruikte Programmeertaal, Tools en Libraries
Voordat we zijn begonnen met implementeren hebben we een aantal afwegingen moeten maken wat betreft de te gebruiken programmeertaal, tools en libraries. Deze afwegingen staan uitgebreid beschreven in hoofdstuk 2 van het Technical Design document (bijlage G). Hier volgt een kort overzicht. Programmeertaal De programmeertalen die we tegen elkaar afgewogen hebben zijn PHP, Python en Java. Uiteindelijk is voor Java gekozen omdat dit een veelgebruikte programmeertaal is (goedkoper/makkelijker onderhoud), en deze taal over een goede object geori¨enteerde standaard bibliotheek beschikt.
14
Framework We hebben het Spring MVC framework gebruikt om het systeem in te implementeren. Het Spring MVC framework wordt ook bij andere projecten van het IISG gebruikt. Door ook bij ons project dit framework te gebruiken is het systeem makkelijker onderhoudbaar en uitbreidbaar door andere ontwikkelaars van het IISG. Libraries We hebben gekozen om JUnit te gebruiken voor unit tests en Hibernate voor de database communicatie. Beiden zijn al in Spring ge¨ıntegreerd en dus makkelijk naast elkaar te gebruiken. Software en Tools Als database software hebben we PostgreSQL gebruikt en de project afhankelijkheden hebben we geregeld in Maven. Om taken te verdelen en bugs te melden is gebruik gemaakt van Trac. Het versiebeheer is bijgehouden in Git, en later ge¨exporteerd naar een centrale SVN repository naar wens van het IISG. Met Doxygen hebben we de code documentatie gegenereerd.
6.3
Structureel Ontwerp
De implementatie bevat 4 hoofdonderdelen/packages van het systeem, namelijk: record, permission, user, en reservation. Om de globale werking en structuur van elk van deze packages te illustreren volgt een gesimplificeerd klassendiagram van de record package in figuur 6.1, waarin de stippellijnen de globale control flow aangeven. Elk package heeft een Controller klasse, welke de aanroepen van zowel externe systemen als van gebruikers afvangt. De controller roept vervolgens een Service klasse aan. Deze klasse vertegenwoordigt de service die een package biedt. De controller kan aanroepen doen naar de service laag van zijn eigen package, maar ook naar die van andere packages. De service laag kan op zijn beurt weer aanroepen doen naar de Data Access Object (DAO) laag, welke de objecten die data (stukken, locaties etc.) representeren beheert. De gekozen structuur bleek voor ons systeem goed te werken. Er zijn geen problemen ontstaan tijdens de implementatie omdat er met bepaalde dingen geen rekening was gehouden in het ontwerp. Het enige dat gezegd kan worden is dat er een aantal DAO klassen zijn die nauwelijks gebruikt worden. Zo wordt de LocationDAO uit de record -package alleen gebruikt om locaties van stukken uit de database te verwijderen. Het toevoegen van locaties aan de database gebeurt door het toevoegen van locaties aan een Record object, waardoor de locaties automatisch worden opgeslagen indien dat Record object wordt opgeslagen. Dat dit gebeurt is ook niet heel gek, want een Location is geen entiteit die zonder een bijbehorend Record in de database zou bestaan.
15
$
$
$
$ !
" " " "
# #
" "
"
#
# #
# #
! "
#
"
#
Figuur 6.1: Klassenvoorbeeld Record Package.
6.4
Test Methodiek
In het testplan bijgesloten bij het Technical Design document (bijlage G) is gespecificeerd op welke manieren het systeem getest zou worden. Hieronder een overzicht hoe dit uiteindelijk heeft uitgepakt. Voor elke iteratie zijn er verschillende test categorie¨en: 1. Unit Tests: Binnen een klasse op methode niveau testen van code. Dit is gedaan bij alle niettriviale methoden. Het is gebleken dat er niet veel niet-triviale methoden waren die niet al door de volgende categorie van tests werd getest. Er zijn daarom ook niet veel van deze tests geschreven. 2. Integration Tests: Dit type tests zorgt ervoor dat de samenwerking tussen klassen wordt getest. Alle API aanroepen die ge¨ımplementeerd zijn in het prototype zijn door middel van geautomatiseerde JUnit tests getest. We hebben hiervoor een test scaffold gebouwd die een aantal reserveringen en stukken in de database zet, en de HTTP Request aanroep nadoet (mockt). De web interface is met de hand getest. Geautomatiseerde tests hiervoor schrijven heeft volgens ons weinig zin. De user interface kan per iteratie veranderen (andere knop namen/ posities), wat de tests waardeloos maakt. 3. System Tests: Dit type tests zorgt ervoor dat er aan de requirements wordt voldaan. Aan de hand van het test script bijgevoegd bij het Technical Design document (bijlage G) is gekeken of het systeem aan de opgestelde functionele requirements voldoet.
16
4. Acceptance Tests: Dit type tests zorgt ervoor dat het systeem ook daadwerkelijk doet wat de gebruiker ervan verwacht. Aangezien er een prototype is opgeleverd, zijn er geen acceptance tests uitgevoerd. Dit zal worden gedaan in een vervolgproject dat wordt aanbevolen in sectie 7.2.
6.5
Code Evaluatie SIG
De Software Improvement Group (SIG) heeft onze code tweemaal doorgemeten om te kijken hoe onderhoudbaar onze code is. Hieronder volgen de twee aanbevelingen die we hebben gekregen, en onze onderbouwing waarom we deze wel of niet hebben opgevolgd.
6.5.1
Meting na iteratie 1
Na de eerste iteratie hebben we de code uit zowel de reservation als de record -package opgestuurd ter evaluatie. De permission en user packages waren na iteratie 1 nog niet ge¨ımplementeerd, en zijn daarom dus ook niet meegezonden. Aanbeveling SIG De code van het systeem scoort net 3 sterren op ons onderhoudbaarheidsmodel, wat betekent dat de code gemiddeld onderhoudbaar is. De score wordt naar beneden gehaald door de Unit Complexity en de Unit Size. Voor Unit Complexity wordt er gekeken naar het percentage code wat bovengemiddeld complex is. Het opsplitsen van dit soort methodes in kleinere stukken zorgt ervoor dat elk onderdeel simpel wordt en daardoor makkelijker is om te begrijpen, te testen en daardoor te onderhouden. De meest complexe methode in dit systeem is te vinden in de ’ReservationController’, maar ook in de ’RecordController’ zijn dit soort methodes te vinden. Commentaar regels zoals ’// Add result to model’ en ’// Set the current page’ geven meestal al aan dat er aparte blokken van functionaliteit te onderscheiden zijn binnen de methodes welke makkelijk los te trekken zijn. Op eenzelfde manier word er voor Unit Size gekeken naar het percentage code wat bovengemiddeld lang is. Ook hier geldt dat het opsplitsen van dit soort methodes in kleinere stukken ervoor zorgt dat elk onderdeel makkelijker te begrijpen, te testen en daardoor te onderhouden wordt. In dit geval komen de meest complexe methoden ook naar voren als de langste methoden, waardoor het oplossen van het eerste probleem ook dit probleem zal verhelpen. Alhoewel het systeem nu gemiddeld scoort lijkt het erop dat de onderhoudbaarheid makkelijk te verbeteren is met een relatief kleine inspanning. Daarnaast is het goed om te zien dat er al wat test-code aanwezig is om het systeem automatisch te testen, hopelijk zal het volume van de test code groeien op het moment dat er nieuwe functionaliteit toegevoegd wordt. Commentaar op Aanbeveling We hebben deze aanbeveling overgenomen omdat we zelf ook vonden dat er een aantal methoden waren die opgesplitst zouden kunnen worden, zodat de complexiteit zou verminderen. Het voorbeeld uit ReservationController dat in de aanbeveling wordt gegeven is een methode die het reserveringsoverzicht afhandelt. De resultaten die in het reserveringsoverzicht worden weergegeven kunnen met diverse filters worden verfijnd. Het toevoegen van die filters aan de database query gebeurde allemaal in dezelfde methode, wat we nu hebben opgesplitst in een aparte methode per filter. De andere aanpassingen die we hebben gedaan betreffen vooral het reduceren van code duplicaten die zijn ontstaan doordat er meerdere manieren zijn waarop het systeem kan worden aangeroepen. Dit kan zowel via de API als door bezoekers via de daarvoor aangewezen web interface worden gedaan. De foutafhandeling is het enige wezenlijke verschil tussen beide manieren van aanroepen. Desondanks is het toch best lastig gebleken om gedeelde code hiervoor te schrijven dat ook nog eens effici¨ent is. Het is uiteindelijk gelukt om dit te doen voor het gros van alle methoden. Alleen het toevoegen van stukken zou naar ons insziens dermate ineffici¨ent worden als we deze duplicaten zouden proberen te verminderen, dat we deze hebben laten staan. Om dit probleem op te lossen is waarschijnlijk een extra
17
abstractielaag nodig, waar wordt besloten op welke manier de fout moet worden gepresenteerd aan de gebruiker, afhankelijk van de manier van aanroepen. Naast deze aanpassingen hebben we bij het implementeren van de resterende packages ook extra zorg besteed aan het voorkomen van nieuwe complexe/lange methoden.
6.5.2
Meting na iteratie 2
Na de tweede iteratie hebben we de code van alle packages meegezonden, aangezien ook alle packages uiteindelijk zijn ge¨ımplementeerd. Aanbeveling SIG In de tweede upload zien we dat de omvang van het systeem bijna is verdubbeld en dat daarbij de score voor onderhoudbaarheid is gestegen. Deze stijging is voornamelijk toe te schrijven aan het feit dat het percentage code in zowel lange als complexe methodes flink is gedaald. Daarnaast is er ook een stijging waar te nemen in het percentage duplicatie binnen het systeem, wat de totale score iets naar beneden haalt. Als laatste laten de metingen voor abstractie zien dat ’Record.java’ wellicht een te prominente rol aan het innemen is binnen het systeem. Uit deze observaties kunnen we concluderen dat de aanbevelingen van de vorige evaluatie zijn meegenomen in het ontwikkeltraject. Alhoewel er op verschillende plaatsen nog ruimte over is voor verbetering lijkt de onderhoudbaarheid van het systeem de goede kant op te gaan. Commentaar op Aanbeveling De aanbeveling komt overeen met onze verwachtingen. We hebben namelijk inderdaad getracht de code complexiteit per methode te verminderen, maar dit is zoals gezegd in het commentaar op de eerste aanbeveling niet volledig gelukt. Wij zijn het niet eens met de uitspraak dat ‘Record.java’ wellicht een te prominente rol aan het innemen is binnen het systeem (vanuit het onderhoudbaarheidsperspectief). De Record klasse, welke bevat is in het ‘Record.java’ bestand en een (archief)stuk representeert, vervult zeker een prominente rol binnen het systeem. Maar als je dit in de context plaatst, en het doel van het systeem naast deze constatering legt, is het meer dan logisch dat er veel gebruik wordt gemaakt van deze klasse. Het is immers de verantwoordelijkheid van het systeem om allerlei metadata over stukken te beheren. Men reserveert stukken, vraagt toestemming aan om stukken in te zien, en past metadata aan over de stukken. De Record klasse is daarom ook in zowel de reservation, permission, als record package gebruikt. Dit is onvermijdelijk wil men het doel van het systeem naleven. De Record klasse vervult daarom naar onze mening niet een te prominente rol binnen het systeem, maar wordt alleen gebruikt op de plekken waar dat essentieel is. Dat wil zeggen dat er geen gebruik van de klasse binnen het systeem is dat leidt tot onnodige koppeling en daarmee de onderhoudbaarheid van het systeem omlaag haalt.
18
Hoofdstuk 7
Conclusies en Aanbevelingen In dit hoofdstuk worden zowel de conclusies wat betreft de resultaten als aanbevelingen van het project uiteengezet. Daarna volgt onze persoonlijke reflectie op de stage.
7.1
Resultaten
Het doel van het project was om de processen die bij de reservering van archiefstukken of de bestelling van een reproductie komen kijken te automatiseren en te stroomlijnen, en tevens te versimpelen. Om dit doel te bereiken hebben we de workflows geanalyseerd, requirements opgesteld en een ontwerp gemaakt van het software systeem waarmee we dit doel wilden bereiken. Omdat het te veel tijd zou kosten om het hele systeem te implementeren, is er een prototype ontwikkeld van een deel van het systeem. In dit prototype is het via een web interface mogelijk om reserveringen te plaatsen om stukken in te kunnen zien. Het systeem houdt de locatie van de stukken bij en het is mogelijk om te specificeren welke inzage- en gebruiksrestricties er op een stuk gelden. De medewerkers kunnen een reservering uitprinten, zodat ze kunnen zien welke stukken er waar en wanneer uit het magazijn moeten worden opgehaald. Door de barcode op een van de uitgeprinte vellen te scannen kan de status van een reservering worden aangepast. Het opgeleverde prototype voldoet aan de formele eisen die zijn gesteld. De opdrachtgever is bovendien tevreden met het resultaat. Er kan dus geconcludeerd worden dat het project succesvol is afgerond. Na een aantal extra stappen kan het systeem in productie worden genomen. De aanbevelingen voor het in productie nemen van het systeem zijn beschreven in de volgende sectie.
7.2
Aanbevelingen
Na afloop van het project is er een prototype van de geplande functionaliteiten van milestone 1 ingeleverd. Om dit prototype in productie te nemen zijn nog een aantal stappen vereist. In dit hoofdstuk zullen we zowel deze stappen en onze aanbevelingen over het uitvoeren er van geven. Voor het in productie nemen van milestone 1 moeten en nog een aantal integratie-features worden toegevoegd: het gebruikerssysteem moet gekoppeld worden aan het CAS/LDAP authenticatiesysteem dat al in de organisatie aanwezig is, en moet er een proces geschreven worden dat automatisch nieuwe aanvragen uitprint op de hardware in de studiezaal. Hiernaast moet de user interface van het systeem opgemaakt worden naar de huisstijl van het IISG, en moet deze door middel van acceptatie tests optimaal worden gemaakt voor gebruik.
19
Een mogelijke planning van alle nog te ondernemen stappen voor milestone 1 zou kunnen zijn: Week 1 2 3 4 5
Taak Stijl aanpassen aan huisstijl Koppeling gebruikersauthenticatie CAS/LDAP Implementatie automatisch uitprinten Testen systeem met barcode scanners Opzet server en implementatie op server Acceptatietests Verwerken feedback acceptatietests
vanuit
Personeel Ontwikkelaars Ontwikkelaars Ontwikkelaars Ontwikkelaars, Sysadmins Ontwikkelaars, Studiezaal Ontwikkelaars
Tijdens dit gehele proces kunnen de gegevens/metadata over de stukken handmatig danwel gescript vanuit andere databases worden omgezet.
7.3
Reflectie
Het is leuk om je opgedane kennis van drie jaar studeren in de praktijk te brengen. Het bachelor project is het eerste project in de opleiding waar je voor een echte opdrachtgever een systeem ontwerpt en implementeert. Daarnaast is het, op de vaste onderdelen na, volledig aan ons geweest hoe we het project vormgegeven werd. Het bezoek aan het Stadsarchief Amsterdam en de interviews met de medewerkers van het IISG vonden we interessant en nuttig, omdat je dan ook de menselijke kant leert kennen voordat je meteen een systeem begint te maken zonder de eindgebruikers er bij te betrekken. Tijdens de ontwerpfase van het project werkten we voornamelijk op onze toegewezen kamer op het IISG en tijdens de implementatiefase hebben we vooral vanuit huis gewerkt. We communiceerden dan via Skype met elkaar. Dat werkte op zich goed, aangezien we slechts met twee personen in de groep zaten. Met een groep van vier personen had dit waarschijnlijk minder goed gewerkt. Behalve tijdens de implementatiefase spraken we bijna elke dag de projectleider om de huidige status van het project te bespreken. Een aantal van de ontwikkelaars spraken we alleen tijdens tussentijdse evaluatie gesprekken. Het had misschien leuk geweest om op dezelfde verdieping als hen te zitten zodat we ze wat vaker konden spreken, ook al waren we dan waarschijnlijk minder productief geweest dan nu. De door ons gekozen project fasering was nieuw voor ons, maar het bleek goed te werken. We waren tevens niet bekend met het Spring MVC framework. Het kostte aardig wat tijd om aan dit framework te wennen. Het viel ons op dat er soms wel 4 manieren waren om een bepaalde functionaliteit voor elkaar te krijgen. Op het Internet stond vaak verouderde documentatie en het kostte dan vaak veel tijd om op te zoeken hoe je een bepaalde functionaliteit kon toevoegen die ook nog eens compatibel was met de door ons gebruikte versie van het framework. Het opleveren van het systeem in iteraties waar dan stapje voor stapje steeds meer functionaliteit bij kwam is goed bevallen. Het is ook leuk om te zien dat mensen tijdens de demonstraties enthousiast reageren en dat er zelfs wordt gezegd dat er van onze manier van documenteren wordt geleerd als zijnde een goed voorbeeld. Al met al is deze stage ons goed bevallen en we hopen ons systeem uiteindelijk een keer in productie te mogen meemaken.
20
Verklarende Woordenlijst Aanvraag Een bezoeker kan een aanvraag doen om bepaalde stukken in te zien. Een aanvraag is dus een verzameling stukken die gereserveerd danwel uitgeleend zijn voor inzage door een bezoeker. Actor Een type gebruiker van het systeem (bijv. bezoeker of studiezaalmedewerker). API Application Programming Interface; Een verzameling functies om de services die een bibliotheek of ander programma biedt te kunnen gebruiken/aanroepen. Bezoeker Een persoon die te gast is bij het IISG om danwel stukken in te zien, danwel reproducties te bestellen. De bezoeker kan zowel via het internet, als op locatie een service van het IISG gebruiken. Contactpersoon Persoon waarmee contact dient te worden opgenomen indien er een inzage restrictie op een archief(stuk) rust. Embargodatum Datum waarna een stuk vrij wordt gegeven voor inzage. De inzage restrictie zal dan automatisch naar ‘Open’ veranderen. Framework Een raamwerk aan software componenten dat standaard-oplossingen biedt voor bepaalde handelingen die vaak worden uitgevoerd bij het schrijven van software. Voorbeeld: Django is een framework dat standaard-oplossingen biedt voor het schrijven van een web-applicatie in de programmeertaal Python. FTP File Transfer Protocol; een gestandaardiseerd protocol om bestanden uit te wisselen tussen verschillende computers. Functionele Requirement Eis die beschrijft wat het systeem moet kunnen. Dit type eis is direct af te leiden uit de probleemstelling. Gebruiksrestrictie Beperking wat betreft het gebruik van een stuk. Het kan bijvoorbeeld zijn dat alleen de microfilm mag worden uitgeleend en het origineel niet. Hoog Resolutie Bestand Een afbeelding met hoge resolutie/kwaliteit. Exacte resolutie/kwaliteit is door een extern systeem bepaald (De Shared Object Repository).
21
iDeal Veelgebruikte Nederlandse online betalingsmethode. Informatievel Vel papier met informatie (locatie in magazijn, titel, datum aanvraag e.d.) van een aangevraagd stuk erop. Dit vel wordt aan de bezoeker overhandigd zodra deze een stuk uitleent. Als de bezoeker een stuk terugbrengt kan de magazijnmedewerker aan de hand van dit vel zien op welke plekken in het archief de stukken terug moeten worden gezet. Inzage Restrictie Restrictie wat betreft de inzage. Stukken kunnen ‘Open’ zijn, dan mag iedereen ze inzien, en dan mogen er ook reproducties van worden gemaakt. ‘Restricted’ geeft aan dat een stuk beperkt mag worden ingezien, de exacte beperkingen zijn per stuk vastgelegd. ‘Closed’ geeft aan dat de stukken helemaal niet in mogen worden gezien. Iteratie Een periode waarin een beperkt aantal nieuwe dingen wordt toegevoegd aan een programma, of waarin fouten worden opgelost. Een iteratie duurt meestal een aantal weken tot een maand, afhankelijk van het project, en is onderdeel van een milestone. Na elke iteratie wordt vaak een evaluatie gehouden om het project indien nodig een andere koers te geven. JSON JavaScript Object Notation; Manier van noteren van Javascript objecten. JSONP JSON with Padding; Een manier om data uit te wisselen tussen verschillende websites. Site A doet een aanvraag naar Site B, met een callback functie als parameter. Site B geeft een JSON object terug, met de callback als omhulsel. Site A voert de callback functie met het JSON object als parameter uit. Library Een bibliotheek aan software componenten, welke gebruikt kan worden bij het schrijven van andere software. Magazijnmedewerker Een medewerker die stukken van en naar het magazijn brengt. Medewerker Een magazijn-, studiezaal-, of reproductiemedewerker. Metadata Gegevens over andere data. Denk aan de uitleenstatus, of inzage restrictie die een stuk kan hebben. Milestone Een periode waarin een groot aantal nieuwe dingen wordt toegevoegd aan een software programma. Een milestone kan uit meerdere iteraties bestaan om de tijd tussen implementatie en feedback te verkorten. Na elke milestone wordt een nieuwe versie van de software opgeleverd, met daarin veel nieuwe toevoegingen. Een milestone duurt meestal een aantal maanden tot een jaar, afhankelijk van de omvang van het project. MoSCoW Must have, Should have, Could have, Won’t have but would like to have; Een prioritiseringsmethode gebruikt om aan te geven welke onderdelen essentieel zijn en welke onderdelen minder belangrijk zijn voor het slagen van een implementatiefase in een (software) project. De must-haves zijn essentieel, de should-haves zijn niet essentieel maar het zou jammer zijn als deze onderdelen niet werden ge¨ımplementeerd. De could-haves zijn optioneel, en worden alleen ge¨ımplementeerd als er nog tijd over is. De won’t-haves worden niet ge¨ımplementeerd omdat ze niet haalbaar zijn binnen het gestelde tijdsbestek. 22
MVC Model-View-Controller; Ontwerppatroon waarbij een duidelijke scheiding is gemaakt tussen de stukken code die de data beheert (Model), de stukken code die zorgen voor de presentatie(View), en de code die de logica van het programma bevat (Controller). Niet-Functionele Requirement Eis die de randvoorwaarden aan het systeem die niet direct uit de probleemstelling zijn af te leiden beschrijft. OAI-PMH Open Archives Initiative Protocol for Metadata Harvesting; Protocol om metadata tussen grote archiefinstellingen uit te wisselen. Dit protocol is ge¨ımplementeerd door het IISG (api.iisg.nl). Open Source Een term gebruikt om aan te duiden dat de broncode van de software voor iedereen toegankelijk is. ORM Object Relational Mapper; Een stuk software dat ervoor zorgt dat objecten uit een Object Geori¨enteerd programma aan tabellen uit een relationele database worden gekoppeld. PDF Portable Document Format; een veelgebruikt bestandsformaat om documenten in op te slaan. PID Persistant Identifier; Een persistente unieke code die gebruikt kan worden om bepaalde objecten (in dit geval: stukken) te identificeren. Doordat het in zekere zin globale identifiers zijn, kunnen verschillende systemen deze gebruiken om naar hetzelfde object te refereren. Plaatsvervangingsvel Vel papier met informatie (locatie in magazijn, titel, datum aanvraag e.d.) van een aangevraagd stuk erop. Dit vel wordt op de plek waar een stuk in het magazijn stond gelegd als plaatsvervanger. Als het stuk terug wordt gebracht is zo gemakkelijk te zien waar het stuk op plank-niveau precies hoort te staan. Postconditie Gegeven conditie die geldt na het uitvoeren van een reeks acties (zoals een use case). Preconditie Gegeven conditie die geldt voor aanvang van een reeks acties (zoals een use case). Rechthebbende De persoon die eigenaar is van een verzameling van stukken/archief. Dit is in vele gevallen ook de contactpersoon. Reproductiemedewerker Een medewerker die zorgt dat de aanvragen voor reproductie worden afgehandeld. Reservering Zie Aanvraag. REST Representational State Transfer; Een architecturele stijl om websites op te bouwen. Per URL kunnen maximaal 4 verschillende request methoden worden gebruikt: GET om data van een bepaalde URL locatie op te vragen, POST om data onder de gespecificeerde URL aan te maken, PUT om data op de exact opgegeven locatie aan te maken/overschrijven, en DELETE om de data op de locatie te verwijderen.
23
SOR Shared Object Repository; Een extern systeem waar gedigitaliseerde stukken in worden opgeslagen. Studiezaalmedewerker Een medewerker van de studiezaal die bezoekers te woord staat en stukken uitleent ter inzage. Stuk Een archiefstuk, boek, brochure, tijdschrift, of andere ge¨ındexeerde eenheid uit het archief of bibliotheek van het IISG. Indien een archief niet ge¨ındexeerd is, wordt het hele archief als ´e´en stuk beschouwd. Alle stukken zijn analoog, d.w.z. fysiek aanwezig, tenzij er wordt gesproken over digitale stukken. Uitleenstatus Een status van een stuk dat aangeeft waar het stuk zich op dit moment bevindt. Mogelijke waarden zijn: Beschikbaar, Aangevraagd, Uitgeleend, Teruggebracht. Use Case Een bepaalde sequentie van handelingen die de interactie tussen een gebruiker en een systeem weergeeft. User Interface Deel van het systeem dat de interactie tussen de gebruiker en het systeem mogelijk maakt. VuFind Zoeksysteem veelal gebruikt om catalogi te doorzoeken. Wachtnummertje Een nummer dat kan worden gebruikt om een bezoeker in een wachtrij te plaatsen. Als de bezoeker een aanvraag ter inzage doet krijgt hij/zij dit nummer. Als de stukken uit het magazijn zijn gehaald wordt het wachtnummer meegedeeld en kan de bezoeker de stukken komen ophalen. Web Interface User interface toegankelijk via een webbrowser, zie User Interface.
24
Bijlage A
Opdracht Beschrijving Lucas de Vries & Stefan van Wouw
25
Samenvatting opdrachtomschrijving Huidige Situatie Er is een fysiek archief met stukken die mensen in een studiezaal kunnen bekijken. Om een stuk in te zien dient een formulier met de hand ingevuld te worden. Vervolgens wordt het stuk met behulp van verschillende fysieke handelingen opgezocht en aangeleverd. Er wordt in een kaartenbak bijgehouden wat er allemaal in gebruik is en de plaatsingscode van een archiefstuk moet handmatig opgezocht worden. Daarom is het ook niet bekend of stukken toegankelijk zijn voordat mensen op het pand aankomen. Reserveringssysteem Er moet een systeem komen dat deze processen automatiseert en stroomlijnt. Deze moet via het internet bereikbaar zijn zodat mensen kunnen controleren of een stuk beschikbaar is en het ook kunnen reserveren. Daarnaast dient het opzoeken en bijhouden van de stukken versimpeld te worden. Infrastructuur Los van het te ontwerpen reserveringssysteem zijn er nog twee andere systemen in de maak. Het uiteindelijke doel is dat deze twee systemen door middel van een API met het reserveringssysteem kunnen communiceren. Er komt een object repository welke alle basisgegevens van de digitale stukken bevat. In de toekomst dient men ook digitale stukken te kunnen aanvragen via het reserveringssysteem. Daarnaast komt er een zoeksysteem dat de catalogus van zowel de analoge (fysieke) als digitale stukken online laat zien. Dit systeem dient met het reserveringssysteem te kunnen communiceren om beschikbaarheidsstatus en dergelijke andere metadata op te vragen.
Minimale Eisen 1. Zowel via internet als op locatie moeten (potenti¨ele) bezoekers kunnen controleren of een fysiek stuk beschikbaar is*. Via een digitaal formulier dienen ze een tijd te kunnen reserveren om een fysiek stuk in te kunnen zien. 2. Medewerkers in de studiezaal dienen een overzicht van alle reserveringen en stukken te kunnen zien zodat ze de stukken uit het archief kunnen halen op de gewenste inzage tijd. 3. In het systeem moet informatie staan / kunnen worden ingevuld over de plaatsingslocatie (in het archief) en inzage permissie (vrij, gesloten, beperkt)** van een stuk. 4. Het systeem moet zowel de status van een reservering als van een archiefstuk bijhouden, zodat er bekend is wanneer en door wie een stuk is/wordt ingezien en waar het stuk zich op dit moment bevindt. * De digitale stukken en de communicatie tussen het reserveringssysteem en de object repository maken dus geen deel uit van de minimale eisen. De communicatie tussen het zoeksysteem en het reserveringssysteem is wel benodigd om aan deze eis te voldoen.
** Voor stukken met beperkte inzage moet toestemming worden gevraagd aan de rechthebbende, de automatisering hiervan maakt echter geen deel uit van de minimale eisen.
Stakeholders 1. Bezoeker: Stukken opvragen, status controleren. 2. Studiezaal/archief medewerker: Plaatsingslocatie van stukken opzoeken, reserveringen administreren. 3. Administratie medewerker: Invullen van metadata 26
4. Rechthebbende: Wel/niet toestemming geven voor inzage bepaalde stukken
27
Bijlage B
Plan van Aanpak Lucas de Vries & Stefan van Wouw
28
1
Opdrachtomschrijving
1.1
Huidige situatie
Het Internationaal Instituut voor Sociale Geschiedenis (IISG) beheert circa 3000 archieven, 1 miljoen boeken en tijdschriften en een rijke collectie beeld- en geluidsmateriaal. Om een stuk in te zien dient een formulier met de hand ingevuld te worden. Vervolgens wordt het stuk met behulp van verschillende fysieke handelingen opgezocht en aangeleverd. Er wordt in een kaartenbak bijgehouden wat er allemaal in gebruik is en de plaatsingscode van een archiefstuk moet handmatig opgezocht worden. Daarom is het ook niet bekend of stukken toegankelijk zijn voordat mensen op het pand aankomen. Naast de fysieke collectie kunnen er ook reproducties (in de vorm van hoge resolutie bestanden en PDFs) worden aangevraagd. Dit gebeurt nu door middel van het sturen van een e-mail naar de organisatie, waar na controle van de betaling handmatig de bestanden op een FTP server worden gezet. Een FTP account wordt aangemaakt voor de klant en daarna worden de inloggegevens weer met de hand in een e-mail naar de klant verstuurd.
1.2
Doelstelling project
Er moet een systeem komen dat de processen die bij de reservering van archiefstukken of de bestelling van een reproductie komen kijken automatiseert en stroomlijnt. Dit systeem moet via het internet bereikbaar zijn zodat mensen kunnen controleren of een stuk beschikbaar is en het ook kunnen reserveren of bestellen. Daarnaast dient het opzoeken en bijhouden van de status van de stukken versimpeld te worden.
1.3
Stakeholders
1. Bezoeker: Stukken opvragen, status controleren. 2. Studiezaal/archief medewerker: Plaatsingslocatie van stukken opzoeken, reserveringen administreren. 3. Administratief medewerker: Invullen van metadata 4. Rechthebbende: Wel/niet toestemming geven voor inzage bepaalde stukken
1.4
Opdrachtformulering
De volgende eisen aan het reserveringssysteem kunnen worden onderscheiden: 1. Het kunnen inzien van fysieke stukken: (a) Archiefstukken (b) Bibliotheekmateriaal • Zowel via internet als op locatie moeten (potenti¨ele) bezoekers kunnen controleren of een fysiek stuk beschikbaar is. Via een digitaal formulier dienen ze een tijd te kunnen reserveren om een fysiek stuk in te kunnen zien. • Medewerkers in de studiezaal dienen een overzicht van alle reserveringen en stukken te kunnen zien zodat ze de stukken kunnen klaarzetten voor de gewenste inzage tijd. • In het systeem moet informatie staan / kunnen worden ingevuld over de plaatsingslocatie (in het archief/bibliotheek). • Voor de archiefstukken moet het systeem inzage permissie (vrij, gesloten, beperkt)* van een stuk en de gebruiksrestrictie (microfilm, origineel, kopie, e.d.) bijhouden. • Het systeem moet zowel de status van een reservering als van een stuk bijhouden, zodat er bekend is wanneer en door wie een stuk is ingezien en waar het stuk zich op dit moment bevindt.
29
2. Het kunnen aanvragen van reproducties: • Er moet via internet vol-automatisch een reproductie van een stuk uit het (beeld)archief te bestellen zijn als PDF of hoge resolutie scan. • De betaling voor de reproductie moet gecontroleerd worden.
• In het systeem moet informatie staan / kunnen worden ingevuld over de inzage permissie (vrij, gesloten, beperkt)* van een stuk. • Via het systeem moet toegang worden aangevraagd voor het digitale reproductie bestand. De manier om toegang te krijgen moet worden doorgegeven aan de gebruiker. • Indien een stuk aangevraagd wordt dat nog niet gedigitaliseerd is, dient de afdeling repro een bericht krijgen zodat zij het stuk kunnen digitaliseren. • Het systeem moet bijhouden welke bestanden door welke personen op welke tijdstippen zijn besteld. * Voor stukken met beperkte inzage moet toestemming worden gevraagd aan de rechthebbende, de automatisering hiervan maakt echter geen deel uit van de minimale eisen.
Het algehele systeem zal worden ontworpen in het Architectural Design document. Daarna wordt afgesproken welk deel we voor de eerste milestone gaan implementeren, namelijk het deel met de hoogste prioriteit en dat bovendien haalbaar is binnen het tijdsbestek van het Bachelor project.
2
Fasering
Week 1 2 3 4 5 6 7 8 9 10 11
16 17 18 19 20 21 22 23 24 25 26
Datum 18 - 22 April 25 - 29 April 2 - 6 Mei 9 - 13 Mei 16 - 20 Mei 23 - 27 Mei 30 - 3 Juni 6 - 10 Juni 13 - 17 Juni 20 - 24 Juni 27 - 1 Juli
Taak Plan van Aanpak en Ori¨entatieverslag Ori¨entatieverslag Requirements Architectural Design Technical Design Iteratie 1 Evaluatie Iteratie 1 + Iteratie 2 Iteratie 2 Eindverslag + Evaluatie Iteratie 2 Eindverslag / Eindpresentatie
IISG Dicht: 22 April, 25 April, 5 Mei, 6 Mei, 2 Juni, 13 Juni
3
Deadlines & Afspraken • 29 April: Ori¨entatieverslag • 13 Mei: Meeting over architectural design** • 20 Mei: Meeting over technical design** • 23 Mei: Test server ready • 3 Juni: Code en documentatie Iteratie 1 • 7 Juni: Evaluatiemeeting Iteratie 1** • 14 Juni: Inleveren code voor Software Improvement Group • 20 Juni: Code en documentatie Iteratie 2 • 22 Juni: Evaluatiemeeting Iteratie 2** 30
• 24 Juni: Draft 1 eindverslag • 1 Juli: Final eindverslag • 8 Juli: Uiteindelijke code en documentatie voor milestone 1 opleveren • 3 dagen voor eindpresentatie: Tweede iteratie inleveren aan Software Improvement Group. ** Deze datum dient ter indicatie. De projectleider zorgt dat er rond deze datum een bijeenkomst wordt georganiseerd.
4
Deliverables • Plan van Aanpak • Ori¨entatieverslag • Requirements – Requirements / MOSCOW – Use Cases / Use Case Model – Sequence Diagrams • Architectural Design – Sub system design – Database design – Infrastructuur – API design • Technical Design – Beslissing over het te implementeren deel in milestone 1 – Keuze programmeertaal & database systeem – Package/Class/Method specifications – Test specifications – Implementatie planning • Implementatie (iteraties 1-2) inclusief unit tests • Code Documentatie (doxygen) • Eindverslag
5
Methodiek & Guidelines
5.1
Rapportage
• Elke dag wordt van de hoofdlijnen van de bezigheden van die dag een logboek bijgehouden. • Belangrijke gesprekken of overleggen worden in hoofdlijnen genotuleerd. • Elke 2 weken wordt richting de TU een progress report ingevuld.
31
5.2 5.2.1
Documenten Protocol
• Deliverable documenten krijgen genummerde draft versies. • Na goedkeuring IISG / TU (eindverslag) wordt het document een genummerde RC versie. • De RC wordt opgestuurd naar de TU voor feedback. • De eerste RC die niet meer wordt aangepast is de Final. 5.2.2
Omgeving
• Alle documenten hebben voertaal Nederlands. • Documenten worden opgeleverd in PDF formaat. • Documenten worden geschreven in LaTeX en in versiebeheer (git) gestopt.
5.3 5.3.1
Code Protocol
• Code wordt opgeslagen in een git repository. • Documentatie van code wordt gegenereerd d.m.v. doxygen. • Test Driven Development. • Iteraties worden getagged met een versienummer “v0.x.y”. – x: Feature addities (nieuwe iteraties i.h.a.) – y: Alleen bug fixes. 5.3.2
Stijl
Voor het programmeren in Java en PHP zijn er binnen het IISG code conventies, die wij voor dit project aan zullen houden. Zowel de code als de doxygen code documentatie heeft voertaal Engels. 5.3.3
Omgeving
• Programmeertaal wordt beslist als onderdeel van het technical design op basis van de requirements. Keuze zal vallen volgens de richtlijnen van het IISG tussen PHP en Java. • Uiteindelijke applicatie moet draaien op een linux server systeem. • Database systeem moet MySQL of PostgresSQL zijn. Deze keuze zal ook worden gemaakt bij het technical design.
6
Inrichting
6.1
Faciliteiten
• Werkplek. • Remote ontwikkelomgeving. • Test server voor uiteindelijke systeem tests.
32
6.2
Personeel
• Interviews met personeel over workflows. • Feedback tijdens interviews over voorgestelde aanpak. • Technische feedback van andere ontwikkelaars over architectural en technical design.
7
Kwaliteitswaarborging • Logboek • Progress Reports • Doxygen generated docs • Unit Tests • Iteratie feedback meetings • Drafts van deliverables
33
Bijlage C
Logboek Dag Maandag 18 april
Bezigheden • Requirements overleg met projectleider • Start plan van aanpak • Computers op de werkplek geconfigureerd
Dinsdag 19 april • Requirements overleg met projectleider • Rondleiding IISG door projectleider • Plan van aanpak afmaken Woensdag 20 april • Bespreking plan van aanpak met projectleider en begeleidend docent • Concretiseren plan van aanpak • Ori¨enteren op Integrated Library Systems Donderdag 21 april • Bespreking geconcretiseerd plan van aanpak met projectleider • Conceptualisatie ori¨entatieverslag Dinsdag 26 april • Van kamer verhuisd • Gesprek met projectleider en software ontwikkelaar • PvA draft 3 ingeleverd • Ori¨entatieverslag RC1 (geen feedback dus meteen RC)
34
Woensdag 27 april • PvA draft 3 besproken met projectleider, verbeterd en RC 1 naar begeleidend docent gezonden • Ori¨entatieverslag RC1 • Access Database met inzage permissies ingezien Donderdag 28 april • Ori¨entatieverslag RC1 Vrijdag 29 april • Ori¨entatieverslag RC1 afgemaakt en opgestuurd naar projectleider en begeleidend docent Maandag 2 mei • Interviews medewerkers studiezaal en reproductie • Opzet requirements document draft 1 Dinsdag 3 mei • Requirements document draft 1: requirements, begin use cases Woensdag 4 mei • Requirements document draft 1: use cases en user interface mock-ups Maandag 9 mei • Bespreking Persistant Identifiers + API contract met VuFind ontwikkelaar • Opzet Architectural Design Dinsdag 10 mei • Architectural Design draft 1 Woensdag 11 mei • Bespreking requirements document draft 1 met studiezaal en repro • Bezoek stadsarchief Amsterdam Donderdag 12 mei • Bespreking requirements document draft 1 en architectural design draft 1 met ontwikkelaars. Het systeem heet vanaf nu Deliverance. • Requirements draft 2
35
Donderdag 12 mei • Bespreking requirements document draft 1 en architectural design draft 1 met ontwikkelaars • Requirements draft 2 • Architectural Design draft 2 Vrijdag 13 mei • Ori¨entatieverslag RC 2 (toevoegen stadsarchief) • Requirements draft 2 • Architectural Design draft 2 Maandag 16 mei • Implementatieplan opgezet en goed laten keuren • Technical Design draft 1 Dinsdag 17 mei • Opzetten ontwikkelomgeving (Spring/Maven) • Technical Design draft 1 • Architectural Design RC 1 en Requirements RC 1 opgestuurd naar de begeleider. Woensdag 18 mei • Voortgangsgesprek met begeleider • Opzetten ontwikkelomgeving (Spring/Maven) • Technical Design draft 1 Donderdag 19 mei • Opzetten ontwikkelomgeving (Spring/Maven) • Technical Design draft 1 Vrijdag 20 mei • Opzetten ontwikkelomgeving (Spring/Maven) • Technical Design draft 1 Maandag 23 mei • Spring verder bestuderen • Requirements RC 2, Architectural Design RC 2
36
Dinsdag 24 mei • Requirements RC 2, Architectural Design RC 2 • Spring boilerplate laten genereren d.m.v. Python script die het database ontwerp interpreteert. Woensdag 25 mei • Opzetten Trac • Besloten hoe de JSON request/responses af te vangen binnen Spring • Start implementatie Record package Donderdag 26 mei • Start implementatie Reservation package • Verder aan Record package Vrijdag 27 mei • Testscaffold opgezet • Verder aan implementatie Reservation en Record package API Maandag 30 mei • Verder aan implementatie Reservation en Record package API Dindsdag 31 mei • Verder aan implementatie Reservation en Record package API Woensdag 1 juni • Verder aan implementatie Reservation en Record package • Unit/Integration tests voor API Vrijdag 3 juni • Verder aan implementatie Reservation en Record package • Unit/Integration tests voor API Maandag 6 juni • Laatste features iteratie 1 ge¨ımplementeerd
37
Dinsdag 7 juni • Bijwerken documentatie (Architectural/Technical) n.a.v. beslissingen die gemaakt zijn tijdens iteratie 1 • Web-interface opleuken met cascading stylesheets en jQuery Woensdag 8 juni • System tests • Voorbereiden evaluatie presentatie van 9 juni Donderdag 9 juni • Evaluatie iteratie 1 • Kennismaking andere ontwikkelaars (eindelijk) • Verwerken feedback iteratie 1 Vrijdag 10 juni • Code documentatie updaten • Code iteratie 1 naar SIG • Begin mail functionaliteit (iteratie 2) • Verwerken feedback iteratie 1 Maandag 13 juni • Permission API • User Authenticatie Dinsdag 14 juni • Permission API tests • User Authenticatie Woensdag 15 juni • Permission Handling • User Authenticatie Donderdag 16 juni • Permission Handling • Permission Request Screen Vrijdag 17 juni • Permission en Reservation E-mail Notificaties • Begin opzet Eindverslag
38
Maandag 20 juni • Documentatie geupdate naar iteratie 2 • Globale projectplanning eventueel vervolgproject met acceptatietests • Code Complexiteit verminderen waar mogelijk Dinsdag 21 juni • Bespreking voortgang met docent begeleider • Voorbereiden demonstratie van het systeem bij halfjaarlijkse personeelsvergadering • Bug fixes en testen iteratie 2 Woensdag 22 juni • Evaluatie iteratie 2 • Verwerken feedback evaluatie iteratie 2 • Reduceren code complexiteit • Iteratie 2 opsturen naar SIG • Iteratie 2 code draaiend op test server Donderdag 23 juni • Eindverslag bijlagen, voorwoord, inleiding, analyse Vrijdag 24 juni • Eindverslag onderzoek, ontwerp, organisatie Maandag 27 juni • Eindverslag implementatie, conclusie, aanbevelingen • Draft Eindverslag naar begeleider Vrijdag 1 juli • Bespreking draft Eindverslag met begeleider Woensdag 6 juli • Verwerken commentaar eindverslag • Voorbereiden eindpresentatie Donderdag 7 juli • Eindpresentatie
39
Bijlage D
Ori¨entatieverslag: Integrated Library Systems Lucas de Vries & Stefan van Wouw
40
1
Inleiding
Een Integrated Library System (ILS) is de generieke benaming voor een IT-systeem dat gebruikt wordt door bibliotheken en soortgelijke instellingen als archieven en musea voor het automatiseren van de dienstverlening [4]. Het ILS biedt een oplossing voor diverse zaken die voorheen met de hand werden gedaan. Het beheren en doorzoeken van de catalogus, en het reserveren en uitlenen van stukken zijn veel voorkomende zaken waarvoor een ILS een geautomatiseerde oplossing biedt. Het Internationaal Instituut voor Sociale Geschiedenis (IISG) is van plan om gebruik te maken van twee van zulke ILS systemen (namelijk: Evergreen in combinatie met VuFind). Daarnaast zijn er veel overeenkomsten tussen de werkwijzen van de bibliotheek en het archief van het IISG en de mogelijkheden van een ILS. Naar aanleiding hiervan is dit verslag een ori¨entatie op de verschillende mogelijkheden, aspecten en oplossingen die door de bestaande ILS systemen worden aangeboden. Als eerste worden de veel gebruikte ILS systemen beschreven in sectie 2, waarna aan de hand van deze systemen de veel voorkomende systeem aspecten van Integrated Library Systems besproken worden in sectie 3. Vervolgens worden de standaarden voor het beschrijven en uitwisselen van catalogus informatie uiteengezet in sectie 4. Tot slot volgt een conclusie in sectie 5. Voor verdere ori¨entatie op de procedures en systemen die al gebruikt worden op een andere archiefinstelling hebben we het Stadsarchief Amsterdam bezocht. Omdat het hier geen traditioneel ILS systeem betreft, maar er wel voor ori¨entatie nuttige resultaten uit zijn gekomen, hebben we de observaties bij dit bezoek opgenomen in appendix A.
2
Bestaande Systemen
Er zijn diverse Integrated Library Systems op de markt, zowel open source als closed source. In deze sectie zal een selectie uit de meest gebruikte systemen globaal worden besproken, zonder in detail te treden over de systeem aspecten, deze worden in de volgende sectie toegelicht. Bij het maken van een selectie uit de bestaande systemen is naast de hoeveelheid gebruikers en de innovativiteit ook veel gekeken naar open source systemen, omdat het IISG een doelstelling heeft om alleen maar open source software te gebruiken. Bovendien stappen er steeds meer bibliotheken over op open source pakketten omdat deze in vele gevallen goedkoper en makkelijker aanpasbaar blijken [17].
2.1
Evergreen
Evergreen is een open source ILS dat voortgekomen is uit een samenwerkingsverband tussen bibliotheken uit Georgia in de Verenigde Staten [18]. In september 2006 is de eerste stabiele versie uitgerold om het Public Information Network for Electronic Services te ondersteunen. Op het moment van schrijven zijn er meer dan 544 instellingen wereldwijd die Evergreen gebruiken. Evergreen is ontwikkeld in de programmeertaal Perl en heeft een web-interface voor bezoekers waarmee ze in de catalogus kunnen zoeken en waarmee ze exemplaren kunnen reserveren. Daarnaast is er een desktop applicatie voor de bibliotheek-/archiefmedewerkers.
2.2
VuFind
VuFind [9] is geen volledig ILS, maar een uitgebreide versie van een OPAC, wat staat voor Online Public Access Catalog. Het faciliteert het uitgebreid zoeken in de catalogus van een ILS via een web-interface. Er zijn verschillende drivers beschikbaar om VuFind aan een ILS als Evergreen te koppelen. VuFind indexeert de catalogus van het ILS en maakt deze op allerlei manieren doorzoekbaar. Hiervoor wordt gebruik gemaakt van het Apache Solr zoekplatform. Het is hierdoor ook mogelijk om de belasting van het systeem te spreiden over meerdere servers. VuFind is een open source pakket ontwikkeld in de programmeertaal PHP en wordt onderhouden door de bibliotheek van Villanova University. Sinds juli 2010 is er een stabiele versie publiekelijk beschikbaar, het pakket is dus nog vrij jong, maar is in vele aspecten uitgebreider dan de standaard OPACs die bij de ILS systemen worden meegeleverd. Bezoekers kunnen bijvoorbeeld ook zelf meehelpen om de indexering van items te verbeteren door tags en commentaar aan items toe te kennen.
41
2.3
Koha
Net als Evergreen is Koha een open source ILS geprogrammeerd in Perl. Koha biedt echter geen desktop applicatie voor de medewerkers, alles gaat via een web-interface. Koha bestaat sinds 2000, wordt hoofdzakelijk onderhouden door LibLime en BibLibre, en wordt op dit moment gebruikt door meer dan 1000 instellingen [8].
2.4
Aleph
Aleph [10] is de enige closed source ILS die voor dit ori¨entatieverslag is geselecteerd. Dit komt doordat het, ondanks dat het al sinds 1990 bestaat en dus vrij oud is, een nog veel gebruikt systeem is. Universiteiten in Nederland zoals de Technische Universiteit Delft, de Universiteit van Amsterdam en de Universiteit Utrecht zijn afnemers van dit systeem van Ex Libris.
3
Systeem Aspecten
Er zijn een aantal aspecten of mogelijkheden te onderscheiden in het bestuderen van integrated library systems. De belangrijkste worden in deze sectie besproken. Per aspect wordt eerst omschreven wat de functionaliteiten zijn die aan de gebruiker worden geboden, en daarna zal kort worden besproken hoe de systemen uit sectie 2 deze aspecten hebben gerealiseerd. Hiervoor is gebruik gemaakt van de documentatie en demo’s van de ILS systemen.1
3.1
Catalogus
Een essentieel onderdeel van een ILS is de catalogus waarin alle stukken die de bibliotheek of archief instelling in bezit heeft bevat. Alle bestaande ILS systemen uit sectie 2 bieden zowel ondersteuning voor het automatisch aanvullen van de catalogus door middel van het Z39.50 protocol (zie sectie 4.3), als het handmatig invoeren van nieuwe items.
3.2
Zoeken
Zoekfunctionaliteit binnen een ILS omvat in het algemeen het opzoeken van stukken op basis van verschillende gegevens. Dit kan door zowel baliemedewerkers, administratieve medewerkers, bezoekers van de website, en bezoekers op lokatie worden gebruikt. ILS systemen kunnen een Online Public Access Catalog (OPAC) ge¨ıntegreerd hebben, maar het is ook mogelijk dat externe applicaties als web frontend gebruikt worden welke dan via een Application Programming Interface (API) met het ILS communiceren. Een voorbeeld hiervan is VuFind (zie sectie 2.2). De manier waarop het zoeken verloopt in een ILS is een belangrijke factor. Alle besproken ILS systemen bieden standaard zoek opties op basis van velden als titel auteur en ISBN. Daarnaast is het in VuFind, de OPAC van Evergreen en de OPAC van Koha mogelijk om de zoekresultaten op eigenschappen te verfijnen. Aleph heeft deze functie niet. Naast het zoeken in metadata is het soms gewenst om een zogenaamde full-text search uit te voeren, waarbij ook de inhoud van de aangeboden stukken wordt doorzocht (Dit kan alleen als de aangeboden stukken gedigitaliseerd zijn). Geen van de besproken ILS systemen biedt deze functionaliteit standaard aan. Bij VuFind is het wel mogelijk om dit redelijk eenvoudig toe te voegen aangezien Apache Solr, waar VuFind gebruik van maakt, wel ondersteuning voor full-text search biedt.
3.3
Registratie
Om bij te houden wie er materiaal leent hebben de instellingen vaak een ledenadministratie met een lidmaatschapskaart. Met ILS systemen die ledenadministratie ondersteunen kan deze ledendatabase 1 Er is geen publieke demo versie van de medewerker kant van Aleph beschikbaar, daarom is voor Aleph alleen gebruik gemaakt van [10] en [11].
42
centraal via het systeem worden bijgehouden. Bij instellingen waar mensen minder frequent materiaal lenen of inzien, kan er ook voor worden gekozen om de leden niet apart te registreren maar om bijvoorbeeld aan de balie om een naam te vragen. Afhankelijk van het ILS kan een vorm van ledenadministratie worden ondersteund. Alle besproken ILS systemen gaan ervan uit dat er een ledendatabase is. Het is dus ook verplicht om jezelf te registreren alvorens je iets kan lenen. De persoonsgegevens die hiervoor nodig zijn dienen zorgvuldig te worden behandeld (zie sectie 3.9). Naast het lokaal bijhouden van de ledenadministratie zou dit ook in regionaal of (inter)nationaal verband kunnen gebeuren. Zo is er in 2003 een Nationale Archiefkaart ingevoerd waarmee kaarthouders in alle aangesloten archieven terecht kunnen. Deze kaart was echter geen succes en is sinds 2007 afgeschaft [1].
3.4
Circulatie
Bibliotheken en soortgelijke instellingen hebben over het algemeen een gelimiteerd aantal exemplaren van een bepaald boek of archiefstuk. Om bij te houden welk fysiek exemplaar zich waar bevindt is er een module in het ILS systeem beschikbaar om de status van elk exemplaar bij te houden. Op deze manier kunnen bezoekers en medewerkers zien of er een exemplaar beschikbaar is en kunnen er eventueel ook automatisch boetes worden uitgedeeld aan bezoekers die te laat zijn met retourneren van bepaalde stukken. Zowel Evergreen, Koha en Aleph bieden een circulatie module waar tevens wordt bijgehouden welke stukken te laat zijn geretourneerd en hoeveel boete elke klant heeft openstaan. In de OPAC kan worden gezien of er exemplaren beschikbaar zijn en bestaat er een mogelijkheid om een stuk te lenen. VuFind kan met speciale drivers verbonden worden met een ILS om ook de uitleenstatus te kunnen tonen.
3.5
Authenticatie
Om de administratieve functies van de instelling te verrichten, moeten medewerkers toegang krijgen tot specifieke delen van het systeem waar data toegevoegd en gemuteerd kan worden. Bij de besproken ILS systemen dienen bezoekers alleen in te loggen als ze een stuk willen lenen of reserveren. De medewerkers dienen in te loggen voordat ze het ILS kunnen beheren. Er zijn verschillende permissies per medewerker instelbaar, zoals het wel/niet mogen inkopen van exemplaren of het wel/niet mogen toevoegen van nieuwe gebruikers.
3.6
Acquisitie
Gegevens over exemplaren van stukken die nieuw toegevoegd worden moeten ook via de administratieve interface van het ILS kunnen worden ingevoerd of besteld. Evergreen, Koha en Aleph bieden functionaliteit om nieuwe exemplaren te kunnen bestellen bij verschillende leveranciers die in het systeem ingevoerd zijn.
3.7
Reserveren
Indien alle exemplaren van een stuk zijn uitgeleend bestaat er een mogelijkheid om een een exemplaar te reserveren. Het kan tevens zo zijn dat een ander filiaal wel nog exemplaren beschikbaar heeft. Dan dient het systeem een exemplaar bij het andere filiaal te reserveren. Alle besproken ILS systemen bieden ondersteuning voor het toevoegen van meerdere filialen en het uitlenen van exemplaren tussen deze filialen.
3.8
Digitale Afgeleiden
Bibliotheken en archief instellingen hebben steeds vaker ook een aanbod in gedigitaliseerd materiaal als e-books en hoge resolutie scans beschikbaar. Copyright aspecten zijn ook steeds vaker onderwerp van gesprek. Er zijn verschillende manieren om copyright schending in te perken. Er kan bijvoorbeeld gebruik gemaakt worden van Digital Rights Management (DRM), zodat het zeer moeilijk wordt om de bestelde afgeleiden onrechtmatig te dupliceren.
43
Een andere manier zou kunnen zijn om de digitale afgeleide maar voor beperkte tijd downloadbaar te maken nadat het is besteld. De besproken bestaande systemen hebben opties om electronische items aan de catalogus toe te voegen. Dit komt in de praktijk vaak neer op het linken naar een externe website waar het item te downloaden is. Er is dus geen speciale module ge¨ıntegreerd die het afhandelen van digitale afgeleiden als taak heeft. Aangezien het downloaden door een externe site wordt afgehandeld, worden er ook geen maatregelen in het ILS genomen om copyright schending in te perken.
3.9
Privacy
Aangezien er bij veel ILS systemen wordt bijgehouden wie wat heeft besteld, gereserveerd of uitgeleend en dit gekoppeld is aan persoonlijke informatie, is het van belang dat er zorgvuldig wordt omgegaan met deze gegevens om de privacy van de gebruiker te waarborgen en misbruik door derden te voorkomen. Het College Bescherming Persoonsgegevens ziet er op toe dat de Wet Bescherming Persoonsgegevens wordt nageleefd [19, 3]. Hierin staat onder andere dat persoonsgegevens als naam, geboortedatum en e-mailadres alleen mogen worden verwerkt met de toestemming van de eigenaar van deze gegevens en bovendien alleen als de verwerking verenigbaar is met het doel waarvoor de gegevens zijn verkregen. Bovendien moet de verwerking zorgvuldig gebeuren. Een beveiligde SSL verbinding voor de overdracht van gegevens en beveiligde opslag servers is dus ook aan te raden. Daarnaast moet de gebruiker ten alle tijden de mogelijkheid hebben om informatie over hem of haar te corrigeren. Behalve de manier van authenticatie en manier van opslaan van persoonsgegevens, hebben de systemen weinig invloed op het beschermen van gevoelige informatie. Aangezien alle systemen via het web bereikbaar zijn, hangt het meer af van de keuze van de afnemer of er wel of geen beveiligde verbinding wordt gebruikt en of de servers wel of geen versleuteld bestandssysteem hebben. Desalniettemin is beschermen van persoonsgegevens geen overbodige luxe.
4
Standaarden
Om de communicatie en interoperabiliteit tussen systemen te bevorderen zijn er meerdere beschrijvingsen uitwisselingsstandaarden die ge¨ımplementeerd kunnen worden. Deze standaarden gaan veelal over de manieren waarop data en metadata over stukken wordt gerepresenteerd en over de protocollen waarmee systemen gegevens (zoals zoekqueries) worden uitgewisseld. In deze sectie hebben we een selectie gemaakt van standaarden die belangrijk zijn in de ILS sfeer, danwel al gebruikt worden door het IISG.
4.1
MARC Records
MARC staat voor “MAchine-Readable Cataloging” en is een pre-web standaard voor het eerst gebruikt in de jaren zestig voor het opslaan van bibliografische informatie. De meest gebruikte variant voortvloeiend uit het oorspronkelijke MARC formaat is MARC21, dat een set van data velden en een formaat om het in door te geven specificeert [13]. Velden zijn numeriek gerepresenteerd en kunnen subvelden hebben. Velden kunnen informatie bevatten over algemene eigenschappen (auteur, publicatiedatum, ISBN) maar ook specifieke informatie als de fysieke locatie en het aantal exemplaren. Verder kan er gebruik gemaakt worden van een afgeleid formaat, MARCXML [14], dat dezelfde datavelden in een xml schema gebruikt. Door XML te gebruiken is er geen gespecialiseerde parser nodig voor MARC, wat de implementatie versimpeld. Een ander verschil tussen MARCXML en MARC21 is dat er in de XML variant meerdere MARC records in ´e´en bestand kunnen worden gespecificeerd. De velden zijn echter nog steeds numeriek gespecificeerd, en de XML is daarom nog net zo (on)leesbaar voor de mens als het MARC21 formaat. De MARC21 standaard is universeel geaccepteerd door ILS systemen, en wordt dan ook ondersteund door zowel Evergreen, Koha en Aleph voor record import. Evergreen kan MARC21 exporteren, en voor MARCXML bestaan er gedocumenteerde tools om collecties te importeren. Koha kan exporteren naar zowel MARC21 en MARCXML via de OPAC interface. In Aleph is er geen mogelijkheid voor het exporteren van MARC via de OPAC interface.
44
Er volgt een voorbeeld van zowel een MARC21 record met dezelfde record in MARCXML weergegeven. Listing 1: Een typisch MARC21 record LDR 001 003 005 008 020 100 245 260 901
00620 cam a2200205Ka 4500 14544 CONS 20110429081527.0 070101 s eng d . _a0330267388 . _aDouglas Adams . _aLife , the Universe and Everything . _c1982 . _a14544 _b _c14544 _tbiblio Listing 2: Een MARCXML record
00620 cam a2200205Ka 4500 14544 CONS 20110429081527.0 070101 s eng d <subfield code=”a”>0330267388 <subfield code=”a”>Douglas Adams <subfield code=”a”>Life , the Universe and Everything <subfield code=”c”>1982 <subfield code=”a”>14544 <subfield code=”b”> <subfield code=”c”>14544 <subfield code=”t”>biblio
4.2
EAD
De Encoded Archival Description (EAD), waarvan de eerste versie uit 1998 stamt, is een andere standaard voor het representeren van informatie over stukken waarbij de nadruk ligt op hierarchische relaties [12]. Een EAD document bestaat bijvoorbeeld uit een collectie, die bestaat uit files welke allen bestaan uit 45
een aantal items. Op deze manier kunnen archieven worden gespecificeerd. EAD is gebaseerd op XML, en de hierarchie van de documenten is direct zichtbaar in de XML hierarchie van het document. Het is in EAD ook mogelijk om velden te labellen met analoge veldnamen in andere encodings (bijvoorbeeld MARC of Dublin Core). Hierdoor kunnen zelfs systemen die normaalgesproken met een andere, danwel oudere, standaard werken makkelijk omgezet worden naar EAD. Omdat EAD vooral een standaard is voor archieven wordt deze niet ondersteund door de besproken ILS systemen. Het wordt echter wel gebruikt door het IISG voor indexatie van de archieven. Listing 3: Een extract van een EAD beschrijving <eadheader [ . . ] audience=”internal”> <eadid countrycode=”NL ” mainagencycode=”AmISG ” identifier=” IISGb10767897”/>
Dora Winifred Russell Papers 1906−1986 ( −1987) <..> <archdesc type=”Inventory ” level=”collection”>
INVENTORY DORA RUSSELL GENERAL <..> 2−5 (Pocket ) diaries . 1922−1986. <extent>4 folders 2 1922−1936. 2.1 1922.
46
4.3
Z39.50
Z39.50 is een pre-web standaard uit de jaren zeventig voor het uitvoeren van zoekqueries en het verzenden van informatie van computer databases. De standaard geeft aan hoe commando’s voor zoeken, informatie opvragen, sorteren en browsen moeten worden verstuurd, en definieert een syntax voor het construeren van queries en data responses [16]. Zoekfunctionaliteiten voor het uitlenen van boeken tussen verschillende bibliotheken worden vaak ge¨ımplementeerd als Z39.50 communicatie tussen de twee Integrated Library Systems. Alhoewel de standaard aangeeft welke mogelijke velden kunnen worden opgevraagd, is er geen mandaat om deze velden daadwerkelijk te ondersteunen, en is er geen specificatie voor de procedure als er een onbekend of onge¨ımplementeerd veld wordt gebruikt. Om dit probleem op te lossen is er een rigide set van elementen en syntax opgesteld: de zogeheten Bath Profile [5]. ILS systemen die zich houden aan de Bath Profile van Z39.50 zijn beter interoperabel met elkaar. Evergreen, Koha en Aleph hebben allen een Z39.50 server beschikbaar. Ook kunnen ze allemaal hun catalogus invullen door records op te zoeken in andere Z39.50-ondersteunende systemen.
4.4
SRU
Z39.50 is een oude standaard gebaseerd op een zeer specifieke syntax. Er zijn verschillende pogingen tot modernisatie geweest, waarvan het SRU protocol de meest prominente is. SRU specificeert op welke manier en met welke parameters zoekqueries moeten worden verstuurd: in de URL van een GET request naar de resultaten. Ook wordt er een formaat waarin de gevraagde resultaten moeten worden teruggegeven gedefinieerd. Dit betreft een XML document dat een lijst van records bevat. Elk record heeft een aantal verplichte en optionele velden. Daarnaast is er ruimte voor de daadwerkelijke data van de record, waarvan de opbouw niet door de SRU standaard wordt gespecificeerd [15]. In praktijk zal de record data vaak in een XML representatie van de Dublin Core standaard zijn. Hierover meer in de volgende paragraaf. Net als Z39.50 hebben de bekeken ILSen allen een SRU server. Er zijn echter geen manieren om records van andere SRU servers direct te importeren aanwezig zoals bij de Z39.50 implementaties.
4.5
Dublin Core
Dublin core is geen standaard voor het representeren van metadata, maar een standaard voor de naamgeving en veldinhoud van de metadata. Dublin Core definieerd 15 verschillende elementen of termen en welke data er in die elementen moet voorkomen [6]. Er is een RDF specificatie beschikbaar voor Dublin Core, en de data wordt vaak als XML weergegeven. In het voorbeeld een XML-ge¨encodeerde Dublin Core record. Aangezien alle ILS systemen die zijn onderzocht SRU ondersteunen, kunnen ze ook allemaal records in Dublin Core verzenden. Alleen Koha heeft echter een mogelijkheid om de Dublin Core XML direct vanuit de OPAC op te vragen. Listing 4: Een Dublin Core record
Life , the Universe and Everything Douglas Adams ISBN :0330267388 1982
47
4.6
OAI-PMH
Het OAI-PMH protocol, wat staat voor “Open Archives Initiative Protocol for Metadata Harvesting” is een protocol om grote hoeveelheden metadata op te vragen via een uniforme interface over het web [7]. Harvesters (zoekmachines, indexeerders) kunnen informatie opvragen over datasets op basis van meerdere criteria die het indexeren van records vereenvoudigen. Er kan om de meest recente updates worden gevraagd of om een specifieke aangeboden dataset. Het protocol wordt bijvoorbeeld gebruikt door zoekmachines (o.a. Google) om data over items op te vragen, door wikipedia om artikel updates door te geven aan zoekmachines en andere herpublicaties, en door NASA voor het Mercury Metadata Search System [2]. Systemen die OAI-PMH ondersteunen moeten volgens de standaard tenminste in staat zijn om data weer te geven in een XML Dublin Core formaat, maar mogen ook andere formaten ondersteunen. Alleen voor Koha is er offici¨ele ondersteuning om data te exporteren via OAI-PMH. Er is een plugin beschikbaar voor Aleph om als OAI-PMH data provider te fungeren, maar geen standaard ondersteuning. Geen van de systemen heeft tools om als harvester van andere OAI-PMH providers data binnen te halen.
5
Conclusie
In dit verslag zijn een aantal aspecten die voorkomen in ILS systemen uitgelicht. We hebben aandacht besteed aan de catalogus, zoekfunctionaliteit, de registratie van gebruikers, het bijhouden van de circulatiegegevens van boeken, de authenticatie van medewerkers in het systeem, de acquisitie en invoer van nieuwe boeken of exemplaren, het reserveren van boeken voor inzage of uitleen, het uitgeven van digitale afgeleiden en de privacystandaarden die voor ILS systemen gelden. Ook is er onderzocht welke standaarden relevant zijn in de ILS ecosfeer. Er is gekeken naar de MARC, EAD en Dublin Core standaarden voor datarepresentatie, en de Z39.50, SRU en OAI-PMH standaarden voor zoeken, aggregatie en indexatie. Bij de analyse van de aspecten en standaarden hebben we gekeken naar de ILS/OPAC systemen Evergreen, Koha, VuFind en Aleph. Behalve voor de digitale afgeleiden, heeft elk van de systemen voldoende functionaliteit bij de gekozen aspecten. De standaarden worden ook voldoende ondersteund. Bij het IISG is de keuze gemaakt om gebruik te gaan maken van Evergreen voor het beheer van de catalogus, in combinatie met VuFind om de catalogus te kunnen doorzoeken. Het IISG zal dus niet alle aspecten van het ILS gebruiken. Het is goed om te kijken of de uitleenfunctionaliteit van Evergreen geschikt is voor het te ontwerpen uitleensysteem of dat er een eigen uitleensysteem zal moeten worden geschreven omdat de wensen te veel afwijken van de standaard oplossing. Dit zal blijken uit de nog op te stellen eisen aan het te ontwerpen systeem.
Referenties [1] Redactie Automatiseringsgids. Chipkaart voor archieven wordt afgeschaft. http://www.automatiseringgids.nl/artikelen/2006/51/ chipkaart-voor-archieven-wordt-afgeschaft.aspx [Bezocht 27 april 2011]. [2] R. Devarakonda, G. Palanisamy, J.M. Green, and B.E. Wilson. Data sharing and retrieval using OAI-PMH. Earth Science Informatics, pages 1–5, 2010. [3] A. Engelfriet. Persoonsgegevens op Internet. http://www.iusmentis.com/maatschappij/ privacy/persoonsgegevens [Bezocht 29 april 2011]. [4] C.M. Goldstein. Integrated Library Systems. Bulletin of the Medical Library Association, 71(3):308, 1983. [5] The Bath Group. The Bath Profile. http://www.ukoln.ac.uk/interop-focus/activities/ z3950/int_profile/bath/draft/stable1.html [Bezocht 27 april 2011]. [6] Dublin Core Metadata Initiative. Dublin Core. http://dublincore.org/ [Bezocht 28 april 2011].
48
[7] Open Archives Initiative. The Open Archives Initiavtive Protocol for Metadata Harvesting. http: //www.openarchives.org/OAI/openarchivesprotocol.html [Bezocht 28 april 2011]. [8] LibLime. Koha. http://www.koha.org/ [Bezocht 28 april 2011]. [9] Villanova University’s Falvey Memorial Library. VuFind. http://www.vufind.org [Bezocht 27 april 2011]. [10] Ex Libris. Aleph. http://docs.exlibrisgroup.com/aleph.htm [Bezocht 28 april 2011]. [11] Ex Libris. Aleph OPAC Universiteit Utrecht. http://aleph.library.uu.nl [Bezocht 29 april 2011]. [12] Library of Congress. Encoded Archival Description Version 2002. http://www.loc.gov/ead [Bezocht 27 april 2011]. [13] Library of Congress. MARC 21 Formats. http://www.loc.gov/marc/marcdocz.html [Bezocht 27 april 2011]. [14] Library of Congress. MARC 21 XML Schema. http://www.loc.gov/standards/marcxml/ [Bezocht 27 april 2011]. [15] Library of Congress. Search/Retrieval via URL. http://www.loc.gov/standards/sru/ [Bezocht 28 april 2011]. [16] National Information Standards Organzation. Information Retrieval (Z39.50): Application Service Definition and Protocol Specification. 2003. [17] Linda M. Riewe. Survey Of Open Source Integrated Library Systems. http://users.sfo.com/ ~lmr/ils-survey/080831-paper-Riewe.pdf [Bezocht 27 april 2011], 2008. [18] Georgia Public Library Service. Evergreen. http://www.open-ils.org [Bezocht 28 april 2011]. [19] Ministerie van Justitie. Wet Bescherming Persoonsgegevens. BWBR0011468 [Bezocht 29 april 2011].
49
http://wetten.overheid.nl/
A
Stadsarchief Amsterdam
´ en voor de beeldbank (foto’s, bouwHet Stadsarchief maakt gebruik van twee verschillende systemen. E´ tekeningen, etc.) en ´e´en voor de archiefbank (persoonsregisters, documenten, etc.). De beeldbank gebruikt een online interface waarmee in het archief gezocht kan worden. Zoekopdrachten zijn verder te specificeren door middel van speciale filters, en voor de beelden zijn thumbnails beschikbaar. Het is via een webshop interface mogelijk om zowel digitale downloads van de hoge resolutie formaten als fysieke prints van de stukken uit de beeldbank te bestellen. Om gebruik te maken van de archiefbank moet men een account aanmaken. Er kan daarna tegoed op deze account worden gezet, en dit tegoed kan gebruikt worden om scans te downloaden van documenten in het archief. Als er nog geen digitale reproductie aanwezig is van het document dat iemand wil inzien kan een scan worden aangevraagd. De betaling voor een scan vindt pas plaats na de daadwerkelijke digitalisatie. Scans die zijn gekocht kunnen altijd vanaf de account van de gebruiker worden bekeken. In principe mogen documenten die al zijn gedigitaliseerd niet fysiek worden ingezien. Voor documenten die nog niet zijn ingescand moet een procedure worden doorlopen om het origineel in handen te krijgen. Er is allereerst identificatie nodig, en er wordt een pasje aangemaakt waarmee de documenten kunnen worden aangevraagd. De pasjes zijn verbonden aan een foto, om te kunnen verifi¨eren dat het daadwerkelijk die persoon is. Als de bezoeker een pasje heeft kan hij een document opvragen vanuit de studiezaal. Er komt dan bij de afdeling logistiek een printje uitrollen dat in twee delen is verdeeld. Het ene deel wordt achtergelaten op de plaats van het stuk in het archief om bij te houden aan wie het is uitgeleend. Als het stuk wordt teruggebracht wordt de plaatsvervanger weggegooid. De status waar het archiefstuk zich op dat moment bevindt kan worden veranderd door de barcode op de uitgeprinte vellen in te scannen. Om de inzage restricties te regelen heeft het stadsarchief standaard-contracten afgesloten met de rechthebbenden van archieven. In een standaard-contract zijn een aantal opties opgenomen, waaronder opties om het wel of niet mogelijk te maken om reproducties te bestellen en om inzage te limiteren. Als er voor archieven toestemming nodig is voor inzage dient de bezoeker zelf contact op te nemen met de rechthebbende, en vervolgens moet de bezoeker aan het stadsarchief kunnen aantonen dat hij/zij toestemming heeft gekregen.
50
Bijlage E
Deliverance: Requirements Lucas de Vries & Stefan van Wouw
51
Inhoudsopgave 1 Inleiding
2
2 Requirements 2.1 Functionele Requirements . . . . . . 2.1.1 Bezoeker . . . . . . . . . . . 2.1.2 Medewerker . . . . . . . . . . 2.1.3 Studiezaalmedewerker . . . . 2.1.4 Een Reproductiemedewerker 2.1.5 Het Systeem (geen actor) . . 2.2 Niet-Functionele Requirements . . . 2.2.1 Applicatie Stack . . . . . . . 2.2.2 Client Specificaties . . . . . . 2.2.3 Overig . . . . . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
3 3 3 4 4 4 5 5 5 6 6
3 Use Cases 3.1 Bezoeker . . . . . . . . . . . . . . . . . . . . . 3.1.1 Reserveren van stukken . . . . . . . . 3.1.2 Bestel een digitale reproductie . . . . 3.1.3 Toestemming aanvragen archieven met 3.2 Medewerker . . . . . . . . . . . . . . . . . . . 3.2.1 Inloggen . . . . . . . . . . . . . . . . . 3.2.2 Metadata aanpassen . . . . . . . . . . 3.3 Studiezaalmedewerker . . . . . . . . . . . . . 3.3.1 Aanvragen ophalen . . . . . . . . . . . 3.3.2 Toestemming geven/weigeren . . . . . 3.3.3 Stukken worden teruggebracht . . . . 3.4 Reproductiemedewerker . . . . . . . . . . . . 3.4.1 Stuk inscannen . . . . . . . . . . . . . 3.4.2 Prijsopgave invoeren . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . beperkte inzage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
7 7 7 10 12 13 13 14 15 15 17 19 21 21 22
4 User Interface 4.1 Printoverzicht . . . . . . 4.2 Stukken reserveren . . . 4.3 Reproducties bestellen . 4.4 Aanvraagoverzicht . . . 4.5 Metadata Aanpassen . . 4.6 Aanvraag Toestemming 4.7 Toestemming Geven . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
23 23 24 25 26 27 28 29
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
A Toestandsdiagram voor Stukken
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . . . . .
. . . . . . .
. . . . . . .
30
B Workflows Afdeling Reproductie 31 B.1 Huidige procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 B.2 Gewenste procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
52
Requirements - 1
Hoofdstuk 1
Inleiding Huidig Systeem Het Internationaal Instituut voor Sociale Geschiedenis (IISG) beheert circa 3000 archieven, 1 miljoen boeken en tijdschriften en een rijke collectie beeld- en geluidsmateriaal. Om een stuk in te zien dient een formulier met de hand ingevuld te worden. Vervolgens wordt het stuk met behulp van verschillende fysieke handelingen opgezocht en aangeleverd. Er wordt in een kaartenbak bijgehouden wat er allemaal in gebruik is en de plaatsingscode van een archiefstuk moet handmatig opgezocht worden. Daarom is het ook niet bekend of stukken toegankelijk zijn voordat mensen op het pand aankomen. Naast de fysieke collectie kunnen er ook reproducties (in de vorm van hoge resolutie bestanden en PDFs) worden aangevraagd. Dit gebeurt nu door middel van het sturen van een e-mail naar de organisatie, waar na controle van de betaling handmatig de bestanden op een FTP server worden gezet. Een FTP account wordt aangemaakt voor de klant en daarna worden de inloggegevens weer met de hand in een e-mail naar de klant verstuurd. Voorgesteld Systeem Er moet een systeem komen dat de processen die bij de reservering van archiefstukken of de bestelling van een reproductie komen kijken automatiseert en stroomlijnt. Dit systeem moet via het internet bereikbaar zijn zodat mensen kunnen controleren of een stuk beschikbaar is en het ook kunnen reserveren of bestellen. Daarnaast dient het opzoeken en bijhouden van de status van de stukken versimpeld te worden. Stakeholders Er zijn verschillende belanghebbenden van het huidige en voorgestelde systeem. Er zijn bezoekers, welke stukken moeten kunnen reserveren en reproducties kunnen bestellen. Voor inzien van sommige stukken is toestemming vereist van de rechthebbende. Daarnaast zijn er studiezaal-, magazijn- en reproductiemedewerkers die bijvoorbeeld metadata over stukken moeten kunnen beheren en aanvragen voor inzage moeten kunnen afhandelen. Documentstructuur Dit document is tot stand gekomen met behulp van informatie verkregen uit interviews en aangeleverde workflows. De workflows van de reproductie kunt u vinden in bijlage B. In hoofdstuk 2 zullen de eisen aan het systeem uiteengezet worden. Vervolgens worden er use cases gepresenteerd in hoofdstuk 3 en tot slot een impressie van de user interface geschetst in hoofdstuk 4.
53
Requirements - 2
Hoofdstuk 2
Requirements In dit hoofdstuk worden zowel de functionele als niet-functionele requirements aan het systeem opgesteld. De functionele requirements geven aan wat het systeem moet kunnen. De niet-functionele requirements zijn de overige eisen waar het systeem aan moet voldoen.
2.1
Functionele Requirements
Er volgt een lijst van eisen waaraan het systeem moet voldoen, gecategoriseerd per actor.
2.1.1
Bezoeker
N.B. Dit betreft zowel online bezoekers als bezoekers op locatie die toegang verkrijgen tot het systeem via een terminal. [F:1] Uitleenstatus opvragen Een bezoeker moet kunnen opvragen wat de huidige uitleenstatus van een stuk is. [F:2] Stukken aanvragen Een bezoeker moet een stuk voor een bepaalde dag kunnen aanvragen indien het nog niet in gebruik is door iemand anders en indien het stuk open 1 is voor inzage. [F:2a] Maximaal 3 stukken per aanvraag Er kunnen maximaal 3 stukken tegelijkertijd worden aangevraagd. [F:2b] Wachtnummer aanvragen huidige dag Indien de bezoeker voor de huidige dag reserveert, dient deze een wachtnummertje te krijgen dat kan worden meegedeeld als het stuk uit het magazijn is opgehaald. [F:2c] Reserveren huidige dag voor 16:00 Er kan alleen voor 16:00 een aanvraag voor de huidige dag worden gedaan. [F:3] Digitale reproductie kopen Een bezoeker moet een digitale reproductie van een stuk kunnen bestellen in de vorm van een hoge-resolutie afbeelding of een PDF 2 . [F:3a] Betaling reproductie De bezoeker dient vooraf te kunnen betalen met betalingsmethoden iDeal en creditcard (het IISG heeft al een contract met Ogone3 voor het afhandelen van de betalingen). 1 Stukken kunnen toestemming open, closed, en restricted hebben. Stukken die restricted zijn mogen pas worden ingezien na toestemming. Stukken die closed zijn mogen niet worden ingezien. 2 De digitale bestanden staan in een extern systeem opgeslagen, het reserveringssysteem kan controleren en toegang verlenen via een nader te specificeren API. 3 Ogone Payment Services http://www.ogone.nl/
54
Requirements - 3
[F:3b] Klantnummer grootafnemers Er moet een mogelijkheid zijn om aan grootafnemers een klantnummer toe te kennen waardoor ze niet langer vooraf hoeven te betalen. [F:3c] Reproductie beperkt downloadbaar De bezoeker dient voor een beperkte tijd (bijv. 2 weken; dit is instelbaar) de bestelde reproducties te kunnen downloaden. [F:3d] Keuze wel/niet digitaliseren Indien het stuk nog niet digitaal beschikbaar is dient de bezoeker de keuze te worden gegeven om na een prijsopgaaf (eventueel gegeven door een medewerker indien geen standaard prijs aanwezig) te kunnen kiezen om de bestelling wel of niet voort te zetten. Als de bezoeker de bestelling voortzet dient ook vooraf betaald te worden. [F:3e] Notificatie indien gedigitaliseerd Als een besteld stuk dat nog niet gedigitaliseerd was eenmaal gedigitaliseerd is dient de bezoeker een notificatie te krijgen per e-mail. [F:4] Toestemming verzoeken Een bezoeker moet een toestemmingsverzoek kunnen invullen/opsturen voor stukken waar de inzage voor beperkt is (Dit geldt voor zowel inzage van stukken als voor reproductie ervan). [F:4a] Bericht ter goedkeuring/afwijzing toestemming De bezoeker moet per e-mail bericht krijgen of er wel of geen toestemming is verleend.
2.1.2
Medewerker
[F:5] Inloggen medewerker Een medewerker moet op het systeem kunnen inloggen. [F:6] Metadata invullen/bewerken Een medewerker moet de opgeslagen metadata over stukken kunnen invullen, bewerken en verwijderen (zie ook [F:13] Bijhouden metadata over stukken).
2.1.3
Studiezaalmedewerker
Een studiezaalmedewerker kan alles wat een medewerker kan en kan ook de volgende dingen: [F:7] Aanvragen bekijken Een studiezaalmedewerker moet reserveringen op datum, naam aanvrager, naam (archief), type, signatuur en status kunnen opvragen. [F:8] Status van een aanvraag aanpassen Een studiezaalmedewerker moet de status van aanvragen aan kunnen passen. [F:9] Toestemming voor inzage bemiddelen Een studiezaalmedewerker moet toestemmingsverzoeken kunnen zien om te kunnen bemiddelen en moet kunnen aangeven of de toestemming wel of niet is verleend. [F:9a] Toestemmingsverzoek direct naar contactpersoon Het moet mogelijk zijn om toestemmingsverzoeken direct naar de contactpersoon te sturen, zodat de contactpersoon zelf toestemming kan geven of weigeren en bemiddeling door het IISG niet meer nodig is.
2.1.4
Een Reproductiemedewerker
Een reproductiemedewerker kan alles wat een medewerker kan en kan ook de volgende dingen: [F:10] Offerte digitalisatie Een reproductiemedewerker moet een lijst met digitaliseringsverzoeken kunnen zien en voor elk verzoek een offerte met prijsopgaaf kunnen versturen. 55
Requirements - 4
[F:11] Inscannen van stukken Een reproductiemedewerker moet een lijst met te digitaliseren stukken kunnen opvragen.
2.1.5
Het Systeem (geen actor)
[F:12] Bijhouden status van een stuk Het systeem moet bijhouden welke stukken er in gebruik zijn en welke stukken er nog opgehaald moeten worden uit het magazijn. [F:13] Bijhouden metadata over stukken Het systeem moet metadata over stukken kunnen bijhouden. [F:13a] Inzage restricties bijhouden De inzage restricties van een stuk (open, restricted, closed) [F:13b] Gebruiksrestricties bijhouden Restricties betreffende het gebruik (bijv. alleen microfilm of kopie i.p.v. het origineel) [F:13c] Locatie informatie bijhouden Locatie informatie (op welke plek in het magazijn staat welk exemplaar (bijv. microfilm/origineel) van het stuk). [F:13d] Uitleenstatus bijhouden Uitleenstatus, welke alleen gewijzigd mag worden indien er op dat moment geen reservering aan gekoppeld is. (zie bijlage A voor de mogelijke statussen) [F:13e] Embargodatum bijhouden Een optionele embargodatum. Als deze datum verstreken is wordt de inzage restrictie van het stuk automatisch op “open” gezet. [F:14] Aanvragen automatisch uitprinten Het systeem moet alle aanvragen die op de huidige dag (en voor 16:00 uur) worden gedaan automatisch uitprinten. [F:14a] Informatie- en plaatsvervangingsvellen printen Er dient voor elk stuk uit een aanvraag zowel een plaatsvervangingsvel als een informatievel te worden afgedrukt (Het plaatsvervangingsvel komt op de plek van het stuk in het archief te liggen, en het informatievel wordt aan de bezoeker meegegeven). [F:15] Geen registratie (account) voor bezoekers Het systeem moet bezoekers de gelegenheid bieden om zonder zich vooraf te registreren stukken te kunnen inzien of reproducties van stukken te kunnen bestellen.
2.2 2.2.1
Niet-Functionele Requirements Applicatie Stack
[NF:1] Server omgeving Het systeem moet kunnen draaien op een linux gebaseerde distributie: Ubuntu 10.04 of hoger, of CentOS 5.5 of hoger. [NF:2] Databases Het systeem moet gebruik maken van MySQL 5.1 of hoger, of PostgreSQL 9.04 of hoger, als database software. [NF:3] Open source Alle frameworks, software of libraries die het systeem nodig heeft dienen onder open source licentie beschikbaar te zijn.
56
Requirements - 5
2.2.2
Client Specificaties
[NF:4] Browser compatibiliteit Het systeem moet functioneel compleet te gebruiken zijn met alle webbrowsers die zich aan de W3C standaarden houden en daarbij specifiek met minimaal de volgende browsers: Mozilla Firefox versie 3.6 of hoger, Microsoft Internet Explorer versie 7 of hoger, Safari versie 5 of hoger en Google Chrome versie 10 of hoger. [NF:5] Ondersteunde schermresolutie De user interface dient compleet te bekijken zijn met een schermresolutie van 1024px breed of meer.
2.2.3
Overig
[NF:6] Lokalisatie systeem Het systeem dient volledig lokaliseerbaar te zijn wat betreft taal. [NF:7] Meertaligheid systeem Het systeem moet zowel een Nederlandse als Engelse user interface hebben. [NF:8] Uitbreidbaarheid systeem Het systeem moet ontworpen zijn met het oog op uitbreidbaarheid. [NF:9] Configureerbaarheid systeem Het systeem moet configureerbaar zijn. Het moet mogelijk zijn om de constante waarden uit bijvoorbeeld requirement [F:2a], [F:2c] en [F:3c] aan te passen.
57
Requirements - 6
Hoofdstuk 3
Use Cases In dit hoofdstuk worden de niet-triviale use cases besproken. De use cases geven weer hoe de interactie tussen de gebruikers en het systeem verloopt. Per use case wordt een korte beschrijving gegeven wat deze use case inhoudt, welke requirements gerelateerd zijn, welke actors de use case kunnen uitvoeren, en welke precondities er gelden voordat de use case wordt uitgevoerd. Daarna worden de uit te voeren stappen en eventuele alternatieve stappen beschreven om te leiden tot een bepaalde postconditie.
3.1 3.1.1 1
Bezoeker Reserveren van stukken
Beknopte Omschrijving
Deze use case beschrijft hoe een bezoeker stukken reserveert via de web interface. 2
Gerelateerde Requirements • [F:2] Stukken aanvragen • [F:12] Bijhouden status van een stuk • [F:13] Bijhouden metadata over stukken • [F:2b] Wachtnummer aanvragen huidige dag
3
Gerelateerde Schermen • 4.2 Stukken reserveren
4
Speciale Requirements • [F:15] Geen registratie (account) voor bezoekers • [F:2a] Maximaal 3 stukken per aanvraag • [F:2c] Reserveren huidige dag voor 16:00
5
Actors • Bezoeker
6
Precondities • De bezoeker heeft een stuk/stukken opgezocht via het externe zoeksysteem.
58
Requirements - 7
7
Stappen 1. De use case begint als een bezoeker op de “Reserveer” knop drukt in het externe zoeksysteem. 2. Het systeem geeft een scherm met informatie over de te reserveren stukken en een invulformulier. 3. De bezoeker vult zijn/haar naam, e-mail adres en de datum vanaf waarop het stuk moet klaarliggen in (dit kan vandaag zijn). 4. De bezoeker klikt op de knop “Reserveren”. 5. Het systeem geeft aan dat de stukken succesvol gereserveerd zijn. 6. Het systeem verstuurt een e-mail naar het opgegeven adres met de gegevens van de stukken, het reserveringsnummer en de gereserveerde dag.
8
Alternatieve Stappen
8.1 Een stuk is niet beschikbaar Als voor een willekeurige stap een stuk niet beschikbaar is: 1. Het systeem geeft een pagina weer met bericht dat het stuk niet beschikbaar voor inzage is. 2. Het systeem vraagt of er een e-mail notificatie moet worden verstuurd zodra de niet beschikbare stukken aanwezig zijn. 3. Als er stukken worden gereserveerd die wel beschikbaar zijn vraagt het systeem om door te gaan met alleen deze stukken. Zo ja, ga verder met stap 2. 4. De use case eindigt zonder succes. 8.2 De bezoeker vraagt een stuk voor vandaag aan Als de bezoeker op locatie aanwezig is of de huidige datum in het datum veld invult verloopt het proces na stap 4 als volgt: 1. Het systeem geeft een pagina weer met bericht dat het stuk is aangevraagd, en laat het nummer van de reservering zien. 2. Een medewerker voert use case 3.3.1 Aanvragen ophalen uit. 3. De bezoeker ontvangt het stuk als zijn nummer bekend wordt gemaakt of als de bezoeker er aan de balie om vraagt (in het geval dat er vanaf buiten het IISG een reservering is geplaatst). 8.3 Stuk heeft restricties Als er restricties op de inzage van het stuk zijn gebeurt er na stap 1: 1. De gebruiker voert use case 3.1.3 Toestemming aanvragen uit. 2. Een medewerker voert na verloop van tijd use case 3.3.2 Toestemming geven/weigeren uit. 3. Als er toestemming is verleend, notificeer de gebruiker door middel van een e-mail en ga verder met stap 2 van de oorspronkelijke stappen. 4. Als er geen toestemming is verleend, notificeer de gebruiker door middel van een e-mail. De use case eindigt zonder succes. 9
Gerelateerde Use Cases • 3.3.1 Aanvragen ophalen • 3.1.3 Toestemming aanvragen • 3.3.2 Toestemming geven/weigeren 59
Requirements - 8
10
Postcondities
10.1
Successvolle Uitvoering
• Het systeem heeft bijgehouden dat het stuk niet meer beschikbaar is en dat het op de aangegeven datum moet worden klaargelegd.
60
Requirements - 9
3.1.2 1
Bestel een digitale reproductie
Beknopte Omschrijving
De bezoeker kan via de website een reproductie bestellen. Deze reproductie zal in de vorm van een hoge-resolutie afbeelding of een PDF zijn. 2
Gerelateerde Requirements • [F:3] Digitale reproductie kopen • [F:13a] Inzage restricties bijhouden • [F:3e] Notificatie indien gedigitaliseerd • [F:3d] Keuze wel/niet digitaliseren
3
Speciale Requirements • [F:3c] Reproductie beperkt downloadbaar • [F:3b] Klantnummer grootafnemers • [F:15] Geen registratie (account) voor bezoekers
4
Gerelateerde Schermen • 4.3 Reproducties bestellen
5
Actors • Bezoeker
6
Precondities • De bezoeker heeft een stuk opgezocht via het externe zoeksysteem.
7
Stappen 1. De use case begint als een bezoeker op de “Bestel Reproductie” knop drukt in het externe zoeksysteem. 2. Het systeem geeft een scherm met informatie over de te bestellen stukken, de prijs van de reproducties en een invoerformulier. 3. De bezoeker vult een naam, e-mail adres en per stuk het te bestellen type in, en drukt op “Plaats Bestelling”. 4. De bezoeker verricht een online betaling via een extern systeem. 5. Het systeem stuurt een e-mail naar de bezoeker met de gegevens die nodig zijn voor het downloaden van de reproductie. Ook wordt de maximale downloadtermijn (zie [F:3c]) hierin genoemd. 6. De gebruiker download de reproductie met de gegevens.
61
Requirements - 10
8
Alternatieve Stappen
8.1 Nog niet gedigitaliseerd Als het stuk nog niet in digitale vorm aanwezig is wordt dit bij stap 2 aangegeven (met eventuele waarschuwing als het stuk op dit moment uitgeleend is) en gebeurt er het volgende: 1. Het systeem geeft een scherm met een bericht dat het stuk nog niet is gedigitaliseerd en de vraag of de bezoeker een prijsopgaaf wil. 2. De bezoeker klikt op “Vraag Prijsopgaaf Aan”. 3. Een medewerker voert na verloop van tijd use case 3.4.2 Prijsopgave invoeren uit. 4. De gebruiker voert oorspronkelijke stappen 2 tot 4 uit. 5. Een medewerker voert use case 3.4.1 Stuk inscannen uit. 6. Ga verder met oorspronkelijke stap 5. 8.2 Stuk heeft restricties Als er restricties op de inzage van het stuk zijn gebeurt er na stap 1: 1. De gebruiker voert use case 3.1.3 Toestemming aanvragen uit. 2. Een medewerker voert na verloop van tijd use case 3.3.2 Toestemming geven/weigeren uit. 3. Als er toestemming is verleend, notificeer de gebruiker door middel van een e-mail en ga verder met stap 2 van de oorspronkelijke stappen. 8.3 Klant heeft klantnummer Als de klant een klantnummer bezit en deze wil gebruiken verloopt de use case na stap 2 als volgt; 1. De bezoeker vult een klantnumer in en drukt op “Plaats Bestelling”. 2. Ga verder met stap 5 van de oorspronkelijke stappen. 8.4 Betaling is Mislukt Als bij stap 4 het externe systeem aangeeft dat de betaling is mislukt: 1. Het systeem geeft een scherm met de details van het probleem (indien mogelijk). 2. De use case be¨eindigt zoder succes. 9
Gerelateerde Use Cases • 3.4.1 Stuk inscannen • 3.4.2 Prijsopgave invoeren • 3.1.3 Toestemming aanvragen • 3.3.2 Toestemming geven/weigeren
10
Postcondities
10.1
Successvolle Uitvoering
• De bezoeker is toegang verleend voor het downloaden van de reproductie voor een beperkte tijd.
62
Requirements - 11
3.1.3 1
Toestemming aanvragen archieven met beperkte inzage
Beknopte Omschrijving
Deze use case beschrijft hoe een bezoeker toestemming vraagt om een stuk te kunnen inzien of er een reproductie ervan te mogen bestellen indien het een stuk betreft waar inzage restricties voor gelden. 2
Gerelateerde Requirements • [F:4] Toestemming verzoeken • [F:4a] Bericht ter goedkeuring/afwijzing toestemming • [F:13a] Inzage restricties bijhouden
3
Gerelateerde Schermen • 4.6 Aanvraag Toestemming
4
Actors • Bezoeker
5
Precondities • De bezoeker heeft een stuk opgezocht via het externe zoeksysteem dat inzage restricties heeft, en wil dat inzien of er een reproductie van bestellen.
6
Stappen 1. De use case begint als een bezoeker op de “Reserveer” knop of “Reproductie bestellen” knop drukt in het externe zoeksysteem, voor respectievelijk het bij het IISG inzien of het bestellen van een reproductie van een stuk met beperkte inzage. 2. Het systeem geeft een scherm met informatie over de te reserveren stukken en een invulformulier voor het toestemming vragen. 3. De bezoeker vult zijn/haar naam, e-mail adres, de gevraagde tijdsduur van de toestemming en overige informatie voor een aanvraag voor toestemming in. 4. De bezoeker klikt op de knop “Toestemming aanvragen”. 5. Het systeem geeft aan dat de toestemmingsaanvraag is ontvangen. 6. Het systeem verstuurt een e-mail naar het opgegeven adres met de gegevens van de stukken waarvoor toestemming is aangevraagd.
7
Gerelateerde Use Cases • 3.1.1 Reserveren van stukken • 3.1.2 Bestel een digitale reproductie
8 8.1
Postcondities Successvolle Uitvoering • Het systeem heeft bijgehouden dat er een toestemmingsverzoek is gedaan.
63
Requirements - 12
3.2
Medewerker
3.2.1 1
Inloggen
Beknopte Omschrijving
Om taken te verrichten die alleen door medewerkers mogen worden benaderd moet een medewerker eerst inloggen op het systeem. 2
Gerelateerde Requirements • [F:5] Inloggen medewerker
3
Actors • Medewerker
4
Stappen 1. Het systeem geeft een inlogscherm. 2. De medewerker vult zijn inloggegevens in en drukt op “Inloggen”.
5
Alternatieve Stappen
5.1
Verkeerde inloggegevens
1. Het systeem gaat terug naar stap 1 (inlogpagina) en geeft een foutmelding weer. 5.2 Al ingelogd Als voor stap 1 de gebruiker al ingelogd is wordt de use case meteen met succes be¨eindigd. 6 6.1
Postcondities Successvolle Uitvoering • De gebruiker is ingelogd en heeft toegang tot medewerker-functionaliteiten (afhankelijk van het type medewerker).
64
Requirements - 13
3.2.2 1
Metadata aanpassen
Beknopte Omschrijving
De metadata die wordt opgeslagen over stukken moet worden ingevuld door medewerkers. 2
Gerelateerde Requirements • [F:6] Metadata invullen/bewerken • [F:13] Bijhouden metadata over stukken
3
Gerelateerde Schermen • 4.5 Metadata Aanpassen
4
Actors • Medewerker
5
Stappen 1. De medewerker voert use case 3.2.1 Inloggen uit. 2. De medewerker klikt op “Metadata Aanpassen”. 3. Het systeem geeft een scherm met invulvelden voor het selecteren van stukken. 4. De medewerker vult de identifiers van de stukken om te bewerken in, of zoekt met een zoekdialoog de identifiers van de stukken op titel op. 5. Het systeem geeft een pagina met de metadata velden. Als er al metadata bestaat voor die identifiers wordt deze al ingevuld. 6. De medewerker vult de nieuwe metadata in. 7. De medewerker klikt op de knop “Opslaan”. 8. Het systeem geeft een bericht dat de gegevens zijn opgeslagen en stuurt de medewerker terug naar het metadata scherm.
6 6.1
Postcondities Successvolle Uitvoering • De opgegeven informatie is voor de geselecteerde stukken in het systeem opgeslagen.
65
Requirements - 14
3.3 3.3.1 1
Studiezaalmedewerker Aanvragen ophalen
Beknopte Omschrijving
Medewerkers moeten de fysieke stukken uit het magazijn halen voor inzage door de bezoeker. 2
Gerelateerde Requirements • [F:8] Status van een aanvraag aanpassen • [F:7] Aanvragen bekijken • [F:12] Bijhouden status van een stuk
3
Speciale Requirements • [F:14a] Informatie- en plaatsvervangingsvellen printen • [F:14] Aanvragen automatisch uitprinten
4
Gerelateerde Schermen • 4.4 Aanvraagoverzicht • 4.1 Printoverzicht
5
Actors • Studiezaalmedewerker
6
Precondities • Er zijn items aangevraagd voor vandaag/morgen maar nog niet opgehaald.
7
Stappen 1. De medewerker voert use case 3.2.1 Inloggen uit. 2. De use case begint aan het begin van de ochtend/ eind middag vorige dag. De medewerker klikt op “Aanvragen Vandaag/Morgen”. 3. Het systeem geeft een lijst met aanvragen die moeten worden opgehaald. 4. De medewerker klikt op “Locaties uitprinten”. 5. Het systeem print voor elk stuk zowel een informatievel als een plaatsvervangingsvel. 6. De medewerker haalt de stukken en legt de plaatsvervangers op hun plaats. 7. De medewerker scant de informatievellen en legt de stukken klaar op de studiezaal. 8. Het systeem verandert de status van de stukken van “Aangevraagd” naar “Uitgeleend”. 9. De medewerker overhandigt de stukken wanneer de bezoeker aan de balie komt.
66
Requirements - 15
8
Alternatieve Stappen
8.1 De bezoeker vraagt het stuk voor vandaag aan De vellen worden automatisch afgedrukt en hebben ook een wachtnummer. De alternatieve use case begint bij stap 6: 1. De medewerker deelt na oorspronkelijke stap 8 de opgehaalde stukken mede, a.d.h.v. het wachtnummer. 2. De use case vervolgt bij oorspronkelijke stap 9. 8.2 Een stuk blijkt niet aanwezig Als er een stuk vermist blijkt te zijn gebeurt er na stap 6: 1. De medewerker verandert de restrictie van het stuk in “Closed” en vult bij het commentaar veld in dat het stuk vermist is. 2. Het systeem stuurt een notificatie e-mail naar de bezoeker. 3. De use case eindigt zonder succes. 9
Gerelateerde Use Cases • 3.1.1 Reserveren van stukken
10
Postcondities
10.1
Successvolle Uitvoering
• De stukken behorende bij de gemarkeerde aanvragen zijn van status “Aangevraagd” naar status “Uitgeleend” veranderd. • De gemarkeerde aanvragen zijn van de nog af te handelen status naar de in-gebruikstatus veranderd.
67
Requirements - 16
3.3.2 1
Toestemming geven/weigeren
Beknopte Omschrijving
Deze use case beschrijft hoe een studiezaalmedewerker aanvragen tot inzage/reproductie van een bepaald stuk kunnen toestaan of weigeren voor een bepaalde bezoeker. 2
Gerelateerde Requirements • [F:9] Toestemming voor inzage bemiddelen • [F:4a] Bericht ter goedkeuring/afwijzing toestemming • [F:4] Toestemming verzoeken • [F:13a] Inzage restricties bijhouden
3
Gerelateerde Schermen • 4.7 Toestemming Geven • 4.6 Aanvraag Toestemming
4
Actors • Studiezaalmedewerker
5
Precondities • Er zijn toestemmingsverzoeken die nog niet zijn goedgekeurd of geweigerd (Status: “Pending”).
6
Stappen 1. De medewerker voert use case 3.2.1 Inloggen uit. 2. De medewerker klikt op “Toestemmingsverzoeken”. 3. Het systeem geeft een overzicht van alle verzoeken. 4. De medewerker klikt op een verzoek. 5. Het systeem toont gedetailleerde informatie over het verzoek, de geldende restricties op de stukken en de contact informatie van de rechthebbende. 6. De medewerker beslist per stuk op basis van de restrictie informatie (en door eventueel de contactpersoon op te bellen) of er wel of geen toestemming wordt gegeven. 7. De medewerker zet de stukken op “Toestaan” en klikt op “Opslaan en bevestiging versturen”. 8. Het systeem stuurt een e-mail met een authenticatiecode naar de bezoeker waarmee de bezoeker de bestelling of reservering kan plaatsen. 9. Het systeem toont een ververste versie van de lijst van alle openstaande verzoeken.
7
Alternatieve Stappen
7.1 Toestemming weigeren Als bij stap 6 wordt gekozen om geen toestemming te verlenen: 1. De medewerker ze de stukken op “Weigeren” en drukt op “Opslaan en bevestiging versturen”. 2. Het systeem stuurt een e-mail naar de bezoeker waarin hij/zij op de hoogte wordt gesteld dat het verzoek tot toestemming is geweigerd. 3. De use case gaat verder bij stap 9. 68
Requirements - 17
7.2 Direct Contactadres is beschikbaar Als er voor de contactpersoon een direct e-mail adres aanwezig is gaat deze use case als volgt: 1. Het systeem verstuurt een e-mail naar de contactpersoon met de informatie van de toestemmingsaanvraag, de aangevraagde stukken en een link met een identificatiecode. 2. De contactpersoon klikt op de link. 3. De contactpersoon voert soortgelijke stappen aan de oorspronkelijke use case uit. 8
Gerelateerde Use Cases • 3.1.3 Toestemming aanvragen
9 9.1
Postcondities Successvolle Uitvoering • Het toestemmingsverzoek is van status “Pending” naar ofwel “Accepted” ofwel “Declined” veranderd, afhankelijk van de keuze van de medewerker of contactpersoon.
69
Requirements - 18
3.3.3 1
Stukken worden teruggebracht
Beknopte Omschrijving
Studiezaalmedewerkers moeten de status van een aanvraag van uitgeleende status naar de geretourneerde status kunnen veranderen wanneer de stukken weer worden ingeleverd. 2
Gerelateerde Requirements • [F:8] Status van een aanvraag aanpassen
3
Gerelateerde Schermen • 4.4 Aanvraagoverzicht
4
Actors • Studiezaalmedewerker
5
Precondities • Er zijn stukken uitgeleend in de studiezaal.
6
Stappen 1. De use case begint als een bezoeker stukken behorende bij een aanvraag bij de balie van de studiezaal komt terugbrengen. 2. De medewerker voert use case 3.2.1 Inloggen uit. 3. De medewerker scant de barcodes op de informatievellen die bij elk stuk zijn meegegeven. 4. Het systeem verandert de status van de stukken van “Uitgeleend” naar “Teruggebracht”. 5. De fysieke stukken worden bij de stapel te retourneren stukken gelegt. 6. De medewerker brengt na verloop van tijd de stukken terug naar het magazijn. 7. De medewerker scant de barcodes op de teruggenomen plaatsvervangers van de stukken die zijn teruggezet. 8. Het systeem verandert de status van de stukken van “Teruggebracht” naar “Beschikbaar”.
7
Alternatieve Stappen
7.1 Bezoeker wil stuk houden Als de bezoeker na stap 1 aangeeft de stukken beschikbaar te willen houden voor inzage een volgende dag: 1. Het fysieke stuk wordt bij de stapel te houden stukken gelegd. 2. De use case eindigt met conditie “Houden”. 8
Gerelateerde Use Cases • 3.1.1 Reserveren van stukken
70
Requirements - 19
9 9.1
Postcondities Retour • De aanvraag is van de uitgeleende status naar de geretourneerde status veranderd. • De stukken zijn van de status “Uitgeleend” naar de status “Beschikbaar” veranderd. (En zijn tussen de twee scans op de status “Teruggebracht” gezet)
9.2
Houden • De aanvraag is niet van status veranderd. • In het systeem staat de status van de stukken nog steeds op “Uitgeleend”.
71
Requirements - 20
3.4
Reproductiemedewerker
3.4.1 1
Stuk inscannen
Beknopte Omschrijving
Reproductiemedewerkers moeten bestelde stukken die nog geen digitale versies hebben inscannen. 2
Gerelateerde Requirements • [F:11] Inscannen van stukken
3
Actors • Reproductiemedewerker
4
Precondities • Er zijn bestelde stukken zonder digitale versie aanwezig.
5
Stappen 1. De medewerker voert use case 3.2.1 Inloggen uit. 2. Het systeem geeft een lijst met te digitaliseren stukken weer, die tevens niet aangevraagd zijn voor inzage (Er is automatisch een speciale reproductie reservering voor aangemaakt). 3. De medewerker drukt voert use case 3.3.1 Aanvragen ophalen uit voor zijn aanvraag. 4. De medewerker digitaliseert de stukken. 5. De medewerker voert use case 3.3.3 Stuk wordt teruggebracht uit voor zijn aanvraag.
6
Gerelateerde Use Cases • 3.1.2 Bestel een digitale reproductie • 3.1.1 Reserveren van stukken • 3.3.1 Aanvragen ophalen • 3.3.3 Stuk wordt teruggebracht
7 7.1
Postcondities Successvolle Uitvoering • Het systeem kan zien dat er nu een digitale reproductie van de stukken aanwezig is.
72
Requirements - 21
3.4.2 1
Prijsopgave invoeren
Beknopte Omschrijving
Reproductiemedewerkers moeten kunnen aangeven wat de prijs van reproducties van een nog niet ingescande set stukken is. 2
Gerelateerde Requirements • [F:11] Inscannen van stukken
3
Actors • Reproductiemedewerker
4
Stappen 1. De medewerker voert use case 3.2.1 Inloggen uit. 2. Het systeem geeft een lijst met prijsaanvragen weer. 3. De medewerker kiest een prijsaanvraag. 4. De medewerker geeft het aantal scans en (in zover als niet automatisch berekenbaar) de uiteindelijke prijs van de order op. 5. De medewerker drukt op “Verzend Offerte”. 6. De prijsopgaaf wordt opgeslagen en naar de klant verstuurd voor een mogelijke bestelling.
5
Gerelateerde Use Cases • 3.1.2 Bestel een digitale reproductie
73
Requirements - 22
Hoofdstuk 4
User Interface In dit hoofdstuk wordt een impressie gegeven van de user interface. Hierbij zijn alleen de niet-triviale schermen uitgewerkt om de use cases en requirements te ondersteunen.
4.1
Printoverzicht
Naam: John Doe
BARCODE/Reserveringsnummer
Wachtnummer: 456
1/1/2011
Titel/naam archief: Dora Russell Papers Inventaris: 18 Type: origineel Verdieping: 4 Richting: Zuid Oost Kast: 432 Plank: Nog niet gespecificeerd
74
Requirements - 23
Baker Val 1966-1970
Barry 1944 en 1973
19
20
[email protected]
E-mail
75
Reserveren
Ik ga akkoord met de voorwaarden
John Doe
Naam
Datum
5/2/2011
Arnold 1970-1979
18
.....
Omschrijving
Inventaris
Overzicht
---
ma
di wo
---
do
Mei
vrij
Kies Datum:
002a422 002a486 002b555 ...
za
zo
Opgevraagde PIDs
Reserveren: Dora Winifred Russell Papers - Items 18 - 20
4.2 Stukken reserveren
Requirements - 24
....
....
TIFF JPG
TIFF JPEGg
PDF PDF
Type
76
Betaling Uitvoeren
Ik ga akkoord met de voorwaarden
[email protected]
Barry 1944 en 1973
....
20
E-mail
Baker Val 1966-1970
19
John Doe
Arnold 1970-1979
18
Naam
Omschrijving
Inventaris
Overzicht 002a422 002a486 002b555 ...
Opgevraagde PIDs
Totaalprijs (incl btw): €30.00
€15.00
€5.00
€5.00
€5.00
Prijs
Bestellen: Dora Winifred Russell Papers - Items 18-20
4.3 Reproducties bestellen
Requirements - 25
Reserveringen Morgen
Archief
Met Geselecteerd:
5/2/2011
John Doe
Naam aanvrager
5/2/2011
Markeer Opgehaald
t/m
Uitgeleend Materiaal
Markeer Teruggebracht
Filter op Stuk/Naam/Signatuur
Dora Russell 18 - 20
Niets
Archiefstukken
Type
Alles
Elke Status
Aanvragen Vandaag
Stukken
Selecteer:
Filter
Aanvraagoverzicht
5/2/2011
Datum
Statussen: - Aangevraagd / In Magazijn - Uitgeleend / In Gebruik - Teruggebracht / Op studiezaal - Beschikbaar / In Magazijn
Uitgeleend
Status
Locaties Uitprinten
4.4 Aanvraagoverzicht
77
Requirements - 26
4.5
Metadata Aanpassen
Metadata Aanpassen PID
Zoek PID
Bewerk op PID
Archief
Stukken
Bewerk Archief
Archief B Status
Uitgeleend
Inzage
Restricted
Embargo datum
1/1/2016
Restricties
Stukken 1-22 mogen alleen met toestemming worden aangevraagd.
Commentaar
2/3/2009: Is recentelijk vermist geweest maar nu weer terug
Contactinformatie
Gebruiksrestrictie Locaties/Typen
Voornaam
Contact
Tussenvoegsel
-
Achternaam
Joe
Adres
Cruquiusweg 31
Postcode
1019 AT
Plaats
Amsterdam
Land
Nederland
E-mail
[email protected]
Telefoon
020-1234567
Fax
020-1234567
Microfilm Type
Verdieping
Origineel
4
Microfilm
5
Richting West
Kast
Plank
456
1
543
...
Opslaan
78
Requirements - 27
Barry 1944 en 1973
20
79
Toestemming Aanvragen
John Doe
1/1/2011 12/12/2011
Van Tot
IISG intern
Biografie Dora Russell
[email protected]
Cruquiusweg 31 1019 AT Amsterdam The Netherlands
Ik ga akkoord met de voorwaarden
Opmerkingen
Periode
Opdrachtgever
Onderzoeksomschrijving
E-mail
Post adres
Naam
Voor inzage van dit stuk is toestemming van de rechthebbende vereist. Vul het onderstaand formulier in en u krijgt een notificatie e-mail wanneer de aanvraag is verwerkt.
.....
Arnold 1970-1979 Baker Val 1966-1970
19
Omschrijving
18
Inventaris
Overzicht
Aanvraag Toestemming 002a422 002a486 002b555 ...
Opgevraagde PIDs
4.6 Aanvraag Toestemming
Requirements - 28
Opmerkingen:
80
Opslaan
geen
Opslaan en bevestiging versturen
Commentaar:
Alleen na akkoord contactpersoon
Restricties:
Dora Russell, Inventaris 19, Baker Val 1966-1970
2/3/2009: Is recentelijk vermist geweest maar nu weer terug
Commentaar:
Alleen na akkoord contactpersoon
Restricties:
Contactpersoon:
Contactpersoon:
Weigeren
Meer gegevens
Contact Joe
[email protected] 020-1234567
Toestaan
Meer gegevens
Contact Joe
[email protected] 020-1234567
geen
Periode:
Cruquiusweg 31 1019 AT Amsterdam The Netherlands
Dora Russell, Inventaris 18, Arnold 1970-1979
1/1/2011 tot 12/12/2011
Opdrachtgever:
[email protected]
IISG intern
Onderzoeksomschrijving: Dora Russell Biografie
John Doe
Gegevens Aanvrager
Toestemming geven/weigeren
4.7 Toestemming Geven
Requirements - 29
Bijlage A
Toestandsdiagram voor Stukken
!
81
Requirements - 30
Bijlage B
Workflows Afdeling Reproductie B.1
Huidige procedure
Intern
Balie
[email protected]
[email protected]
ibl
Opdrachtformulier invullen
Scannen/Kopië ren/Printen/fotograferen
Digitaal
Ja
Plaatsen op de server
Nee
Envelop
Mail naar klant
Wegen
Bestelformulier naar administratie
Posten
Rekening maken en versturen
Einde
82
Requirements - 31
B.2
Gewenste procedure
E - Levering
0.01 Zoeken
0.02 Selecteren binnen resultaat
Nee
0.03 Gewenst resultaat gevonden?
Ja 0.04 Is er een contractuele beperking op het object?
Nee
1.04 Toon detail resultaat
Ja 0.05 Wil je toestemming vragen?
1.05 Bestellen?
Ja
Ja 1.06 Toon copyright melding
0.06 Krijgt klant toestemming? Nee Ja
1.07 Is de hoeveelheid bekend?
Nee
2.07 Wil de klant een offerte voor bestelling?
0.07 Geef klant toestemming en inlog Ja
Ja
1.08 Plaats in winkelmandje
2.08 Schatting maken van de kosten
1.09 Klaar met bestellen?
2.09 Gaat de klant akkoord?
Ja
Ja
1.10 E-mail/postadres doorgeven
2.10 Bestelling plaatsen
Nee
0.08 Geef feedback aan klant Nee
Einde
1.11 Toon inhoud winkelmandje
0.12 Verwijder object
Opnieuw?
1.12 Akkoord?
Nee
Nee 2.11 kopië ren/scannen
2.12 Mail naar de klant met kosten
Ja 1.13 Toon rekening overzicht
1.14 Betalen
1.15 Bevestiging naar klant sturen
Nee
1.16 Leveren aan klant
nee
Einde
83
Requirements - 32
Bijlage F
Deliverance: Architectural Design Lucas de Vries & Stefan van Wouw
84
Inhoudsopgave 1 Inleiding
2
2 Systeem Ontwerp 2.1 Subsysteem Decompositie . . . . . . . . . . . . . . . . . 2.2 Concurrency Problemen . . . . . . . . . . . . . . . . . . 2.2.1 Tegelijkertijd hetzelfde stuk reserveren . . . . . . 2.2.2 Reproduceren van een (continu) uitgeleend stuk . 2.3 Toegangsrechten . . . . . . . . . . . . . . . . . . . . . . 2.4 Start- en Herstelprocedures . . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
3 Database Ontwerp 4 API Specificaties 4.1 Deliverance API . . . . . . . . . . . . 4.1.1 Conventies . . . . . . . . . . . 4.1.2 Formulieren . . . . . . . . . . . 4.1.3 Record/Metadata Management 4.1.4 Reservering Management . . . 4.1.5 Order Management . . . . . . . 4.1.6 Permission Management . . . . 4.2 Externe Informatie API . . . . . . . . 4.3 Externe Reproductie API . . . . . . .
3 3 4 4 4 4 5 6
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
85
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
8 8 8 9 10 12 14 16 20 20
Architectural Design - 1
Hoofdstuk 1
Inleiding Het Internationaal Instituut voor Sociale Geschiedenis (IISG) heeft circa 3000 archieven, 1 miljoen boeken en tijdschriften en een rijke collectie beeld- en geluidsmateriaal in beheer. De stukken kunnen worden ingezien op de studiezaal en er kunnen reproducties worden besteld. De processen die bij het inzien en reproduceren van stukken komen kijken gaan op dit moment nog met de hand. In het Requirements document zijn eisen opgesteld aan het IT-systeem dat deze processen dient te stroomlijnen en automatiseren. Daarbij is door middel van use cases aangegeven hoe de interactie tussen de gebruikers en het systeem zal verlopen. In dit document wordt de ontworpen systeem architectuur gepresenteerd. In hoofdstuk 2 wordt het systeem ontwerp besproken. Vervolgens wordt het database ontwerp beschreven in hoofdstuk 3 en wordt de Application Programming Interface (API) specificatie uiteengezet in hoofdstuk 4.
86
Architectural Design - 2
Hoofdstuk 2
Systeem Ontwerp Dit hoofdstuk beschrijft het systeem ontwerp. Als eerste wordt er een decompositie in subsystemen gegeven in sectie 2.1. De problemen die komen kijken bij het (vrijwel) tegelijkertijd modificeren van data worden besproken in sectie 2.2. Daarna worden de globale toegangsrechten besproken in sectie 2.3. Tot slot worden de start- en herstelprocedures uiteengezet in sectie 2.4.
2.1
Subsysteem Decompositie
Voor de indeling van het systeem wordt een MVC (Model-View-Controller) ontwerppatroon gebruikt. De benodigde data die in de database van het systeem staat (zie hoofdstuk 3) wordt door middel van de model klassen opgevraagd. Er is een API waarmee zoeksystemen als VuFind uitleenstatus e.d. kunnen opvragen. Ook is er een abstractielaag voor de APIs waarmee het systeem meer informatie over stukken kan opvragen. Zo wordt er bij elke reservering een overzicht gegenereerd aan de hand van informatie verkregen uit OAI, en wordt de Shared Object Repository (SOR) gebruikt om periodiek te kijken of bepaalde analoge stukken al gedigitaliseerd zijn.
Figuur 2.1: Globale decompositie in subsystemen 87
Architectural Design - 3
2.2
Concurrency Problemen
Er kunnen zich verscheidene problemen voordoen indien men bepaalde acties tegelijkertijd uitvoert. Hieronder een overzicht van de belangrijkste problemen en de genomen beslissingen om deze problemen op te lossen.
2.2.1
Tegelijkertijd hetzelfde stuk reserveren
Probleem Meerdere bezoekers zijn via het externe zoeksysteem op de reserveringspagina gekomen om hetzelfde stuk te reserveren (de status is op dat moment immers nog ‘beschikbaar’). Er kan slechts ´e´en persoon tegelijk het stuk reserveren. Oplossing Het systeem dient op het moment dat de gebruiker de reserveringspagina betreedt en elke keer dat een gebruiker het reserveringsformulier submit te controleren of de te reserveren stukken nog beschikbaar zijn. Op het moment dat een stuk in de selectie van te reserveren items al gereserveerd blijkt te zijn, krijgt de bezoeker een bericht met daarin de keuze om door te gaan met reserveren voor de overige stukken in de selectie, of om de reservering af te breken.
2.2.2
Reproduceren van een (continu) uitgeleend stuk
Probleem Een bezoeker heeft een reproductie van een nog niet gedigitaliseerd stuk aangevraagd. De reproductiemedewerker ziet dat hij het stuk dient te digitaliseren, maar het stuk is (continu) uitgeleend voor inzage. Oplossing Om te voorkomen dat een stuk nooit gedigitaliseerd kan worden doordat het continu uitgeleend is voor inzage, wordt er door het systeem een speciale reproductie reservering aangemaakt voor een stuk, ook als deze al uitgeleend is voor inzage. Op het moment dat de bezoeker het stuk retourneert, checkt het systeem voordat het stuk de status ‘beschikbaar’ krijgt of er een reproductie reservering bestaat. Indien dat het geval is wordt de reproductie reservering actief in plaats van dat het systeem het stuk weer vrij geeft voor inzage.
2.3
Toegangsrechten
Bij het IISG zijn er twee groepen medewerkers die gebruik moeten gaan maken van het systeem: studiezaal- en reproductiemedewerkers. Elke groep medewerkers mag bepaalde acties binnen het systeem uitvoeren. Deze acties zijn gespecificeerd door middel van bepaalde rechten in de database, en kunnen indien gewenst uitgebreid worden. Elke medewerker krijgt een apart user account, gelinkt aan een bepaalde medewerker groep. De bezoekers die gebruik maken van het systeem krijgen geen apart user account, en worden dus als ´e´en homogene groep beschouwd, waar geen configureerbare permissies voor aanwezig zijn in de database. De volgende basisrechten voor medewerkers kunnen worden onderscheiden: Recht record:modify reservation:view reservation:modify order:view order:modify permission:view permission:modify
Uitleg Mag metadata over een stuk aanpassen of verwijderen. Mag actieve en gearchiveerde reserveringen bekijken. Mag de informatie bij een reservering aanpassen of verwijderen. Mag actieve en gearchiveerde orders bekijken. Mag de informatie bij een order aanpassen of verwijderen. Mag actieve en gearchiveerde verzoeken voor toestemming bekijken. Mag de informatie bij een verzoek aanpassen of verwijderen. 88
Groepen IISG Studiezaal Allen Allen Reproductie Reproductie Studiezaal Studiezaal
Architectural Design - 4
2.4
Start- en Herstelprocedures
Het systeem komt in zijn geheel op een webserver te draaien en kan door middel van HTML formulieren of API calls worden aangesproken. Als het systeem uitvalt terwijl een gebruiker het systeem wil raadplegen krijgt de gebruiker geen verbinding met het systeem. Als de oorzaak van het probleem (verbinding/server uitgevallen) is opgelost kan de gebruiker weer verbinding maken met de server en is het systeem weer functioneel beschikbaar. Behalve het opnieuw opstarten van het systeem of het oplossen van verbindingsproblemen hoeven er geen speciale acties te worden ondernomen. Het systeem maakt gebruik van meerdere externe systemen (zie hoofdstuk 4). Voor het uitvallen van deze systemen geldt dat indien dat gebeurt tijdens een use case (een bezoeker of medewerker is betrokken), er een gebruikersvriendelijke foutmelding dient te worden weergegeven. Als de informatie van het externe systeem essentieel is voor de voortzetting van de use case dient deze be¨eindigd te worden, anders dient er doorgegaan te worden met de use case. Voor het uitvallen van de externe systemen tijdens een periodieke update aanvraag van het systeem geldt dat het systeem het na korte tijd opnieuw moet proberen en anders de ingestelde periodieke tijd moet wachten met opvragen.
89
Architectural Design - 5
Hoofdstuk 3
Database Ontwerp In de onderstaande figuren is het database ontwerp te zien. Zoals besproken in sectie 2.3 is te zien dat elke gebruiker in meerdere groepen ingedeeld kan worden en dat elke groep vervolgens weer een aantal geassocieerde permissies heeft. De Record entiteit kan zowel een enkel archiefitem of boek beschrijven, als een heel archief. Hiervoor is gekozen omdat niet alle archieven ge¨ındexeerd zijn. Ook kan er op deze manier voor een heel archief een inzage restrictie worden opgelegd door gebruik te maken van de parent-child relatie tussen verschillende records. Er kan een reservering worden aangemaakt voor meerdere records indien deze nog niet uitgeleend zijn. Het special attribuut in Reservation geeft aan dat het in plaats van een reguliere inzage reservering, een automatische reproductie reservering betreft (zie ook sectie 2.2.2). Als er toestemming wordt gevraagd d.m.v. het toestemmingsformulier, wordt er een PermissionRequest aangemaakt, gelinkt aan de bijbehorende stukken d.m.v. de RecordPermission kruistabel. Als de daadwerkelijke reservering/order wordt geplaatst wordt deze ook nog aan het permissieverzoek gekoppeld. Voor een digitaliseringsaanvraag kan een offerte worden gemaakt, welke wordt opgeslagen in de Quote entiteit. Voor een digitale reproductie wordt een Order aangemaakt. Grootafnemers krijgen een klantnummer, wat wordt bijgehouden in de Customer entiteit.
Figuur 3.1: Database Schema (1 van 2)
90
Architectural Design - 6
!
# #
! "
!
$
%
Figuur 3.2: Database Schema (2 van 2)
91
Architectural Design - 7
Hoofdstuk 4
API Specificaties In dit hoofdstuk worden zowel de specificaties van de Application Programming Interface (API) die het systeem aanbiedt, als de externe APIs die het systeem gebruikt besproken in respectievelijk sectie 4.1, en sectie 4.2 en 4.3.
4.1
Deliverance API
Voor de binnenkomende API wordt gebruik gemaakt van een zover mogelijk op REST1 gebaseerd protocol in combinatie met in JSON-ge¨encodeerde data2 . De specificaties van alle acties en mogelijke data velden volgen.
4.1.1 1
Conventies
PIDs
Persistant identifiers (PIDs) voor archiefstukken kunnen worden opgegeven in het formaat “[PID archief].[item nummer]”. Als een PID eindigt met een punt gevolgt door een nummer wordt ook aangenomen dat het hier een sub-item betreft: het laatste nummer wordt er voor alle externe informatie requests afgehaald zodat informatie over het gehele stuk/archief kan worden opgevraagd. 2
Output Formaat
Het systeem kan voor bepaalde pagina’s output geven zowel als een JSON-ge¨encodeerde datastructuur als een human-readable HTML pagina. Standaard zal het systeem kijken naar de HTTP “Accept:” header om te bepalen welk formaat te gebruiken (‘text/html’ of ‘application/json’). Voor compatibiliteit is het ook mogelijk om “?format=hhtml/jsoni” als URL parameter te specificeren. Het wordt echter aangeraden om de Accept-header te gebruiken. 3
Request Methode
Het systeem maakt gebruik van zowel DELETE als PUT requests naast de normale GET en POST, maar deze methoden worden niet door alle clients ondersteund of overcompliceren het mechanisme om requests te verzenden. Hiervoor zal het systeem alle URLs die eindigen met “!DELETE” of “!PUT” en POST als request methode gebruiken behandelen alsof de methode repectievelijk DELETE danwel PUT is. Voor clients, daar waar praktisch, wordt echter aangeraden om de daadwerkelijke methodes te specificeren. 1 Representational
State Transfer (REST) http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.
htm 2 JavaScript
Object Notation http://www.json.org
92
Architectural Design - 8
4
Authenticatie
Elke gebruiker krijgt een authentication token toegewezen. Deze wordt in een cookie geset en daardoor met de requests in een header meegegeven. Voor geautomatiseerde API calls kan eerst een call om in te loggen worden gedaan - deze geeft de authentication token van de gebruiker terug - of een token kan worden opgeslagen in de configuratie. 5
JSONP
Bij elke GET request kan aan de URL een parameter “?callback=hfunci” worden toegevoegd. Voor de output zal dan in plaats van simpele JSON een JSONP response met die callback worden gegeven.
4.1.2
Formulieren
De volgende URLs worden gegarandeert om naar formulieren voor bepaalde acties te leiden. /reservation/createform/[pid,pid,pid] Een formulier om een aanvraag te doen voor de stukken die horen bij de opgegeven pids. /order/createform/[pid,pid,pid] Een formulier om een bestelling te doen voor reproducties van de stukken die horen bij de opgegeven pids.
93
Architectural Design - 9
4.1.3
Record/Metadata Management
Het Location type floor direction cabinet shelf 1
object wordt in verschillende requests en responses gebruikt en ziet er als volgt uit: String Het type van het stuk (origineel/microfilm e.d.). String Optioneel: De verdieping waar het stuk staat. String Optioneel: De richting waarin het stuk staat op een bepaalde verdieping (bijv. ZuidOost). String Optioneel: De kast waarin het stuk staat. String Optioneel: Het plank nummer waarop het stuk staat.
/record/[pid,pid,pid,. . . ]
Het element met metadata over een set records. 1.1 GET Opvraag van de metadata gegevens over een record. 1.1.1
Authenticatie
1.1.2
Request
Geen authenticatie vereist.
N/A
1.1.3 Response Gegevens over records in een HTML pagina of JSON. De JSON zal een lijst van objects met allen minimaal de volgende velden bevatten: pid name restriction status locations
String String String String ListhLocationi
De PID van het stuk. De naam van het stuk. “Open”, “Restricted” of “Closed”. “Available”, “Reserved” of “In Use”. De gespecificeerde locaties van dit stuk.
Als de geauthenticeerde gebruiker het recht “record:permissions” heeft en de restriction niet “Open” is wordt de volgende informatie ook toegevoegd: restriction desc first name preposition last name address postal code location country email phone number fax
String String String String String String String String String String String
De precieze restrictie op het stuk. Naam van de contactpersoon voor een toestemmingsaanvraag. ,, ,, Addres van de contactpersoon. ,, ,, ,, E-Mail van de contactpersoon. Telefoonnummer van de contactpersoon. Faxnummer van de contactpersoon.
1.2 PUT Verander de gegevens van een record of maak nieuwe records aan voor stukken. 1.2.1
Authenticatie
De ingelogde gebruiker moet recht “record:modify” hebben.
1.2.2 Request De request is een enkel JSON object met gegevens. Voor alle genoemde PIDs worden deze gegevens in de database opgeslagen. Als er nog geen record bestaat voor een opgegeven PID wordt deze aangemaakt. Het JSON object mag de volgende velden bevatten:
94
Architectural Design - 10
restriction locations
String ListhLocationi
“Open”, “Restricted” of “Closed”. De nieuwe locaties van dit stuk.
Als de geauthenticeerde gebruiker het recht “record:permissions” heeft en de restriction niet “Open” is kunnen de volgende velden ook worden ingevuld: restriction desc first name preposition last name address postal code location country email phone number fax 1.2.3
String String String String String String String String String String String
De precieze restrictie op het stuk. Naam van de contactpersoon voor een toestemmingsaanvraag. ,, ,, Addres van de contactpersoon. ,, ,, ,, E-Mail van de contactpersoon. Telefoonnummer van de contactpersoon. Faxnummer van de contactpersoon.
Response N/A
1.3 DELETE Verwijder de gegevens in de database van alle records met de opgegeven PIDs. Als er actieve aanvragen of orders zijn voor stukken in de lijst wordt er een error code geretourneerd. Aanvragen en orders in het verleden worden met het stuk verwijderd. 1.3.1
Authenticatie
1.3.2
Request
1.3.3
Response N/A
De ingelogde gebruiker moet recht “record:modify” hebben.
N/A
95
Architectural Design - 11
4.1.4 1
Reservering Management
/reservation/
De collectie van reserveringen die in het systeem zijn opgeslagen. 1.1 GET Vraag een lijst met reserveringen in de database op. 1.1.1
Authenticatie
1.1.2
Request
page page len sort sort dir from date to date search ...
De geauthenticeerde gebruiker moet het recht “reservation:view” hebben.
De query string kan de volgende parameters bevatten:
Het paginanummer om op te vragen. Default: 1 Het aantal records per pagina. Default: Implementatieafhankelijk. Optioneel attribuut om op te sorteren. Ten minste mogelijk: “status”, “visitor email”, “date”, “visitor name”. De volgorde van sorteren: “asc” of “desc”. Default: “asc”. Optioneel: Reserveringen vanaf deze datum (yyyy-mm-dd). Optioneel: Reserveringen tot en met deze datum (yyyy-mm-dd). Toon alle resultaten waar de meegegeven waarde in “‘visitor name”, “visitor email” of geassocieerd stuk titel voorkomt. Elk String,Boolean of Integer veld kan worden gefilterd met een parameter met dezelfde naam.
1.1.3 Response Een lijst van de opgevraagde reserveringen in een HTML pagina of JSON. De JSON zal bestaan uit een lijst van objects met ten minste de volgende velden: visitor name visitor email status date special
String String String String Boolean
items
ListhStringi
De naam van de bezoeker. Het e-mail adres van de bezoeker. “Pending”, “Active” of “Completed”. Gewenste datum: yyyy-mm-dd. Of dit een speciale reservering is. (Bijvoorbeeld voor de reproductie) De lijst van pids die zijn aangevraagd.
1.2 POST Maak een nieuwe reservering aan. 1.2.1
Authenticatie
Geen authenticatie vereist.
1.2.2 Request De request is een enkel JSON object met gegevens. Er wordt een nieuwe reservering aangemaakt met de opgegeven data. Tenminste de volgende informatie moet worden meegegeven: visitor name visitor email date items
String String String ListhStringi
De naam van de bezoeker. Het e-mail adres van de bezoeker. Gewenste datum: yyyy-mm-dd. De lijst van pids die zijn aangevraagd
1.2.3 Response Bij een succesvolle operatie wordt een 303 redirect teruggegeven. De redirect zal leiden naar de nieuwe reservering.
96
Architectural Design - 12
2
/reservation/[id]
Een enkele reservering. 2.1 GET Vraag informatie over de inhoud van deze reservering. 2.1.1
Authenticatie
2.1.2
Request
De geauthenticeerde gebruiker moet het recht “reservation:view” hebben.
N/A
2.1.3 Response Informatie over de reservering in HTML of JSON formaat. Ten minste de volgende velden zullen in de JSON aanwezig zijn: visitor name visitor email status date special
String String String String Boolean
items
ListhStringi
De naam van de bezoeker. Het e-mail adres van de bezoeker. “Pending”, “Active” of “Completed”. Gewenste datum: yyyy-mm-dd. Of dit een speciale reservering is. (Bijvoorbeeld voor de reproductie) De lijst van pids die zijn aangevraagd.
2.2 PUT Verander de gegevens van een reservering. 2.2.1
Authenticatie
De geauthenticeerde gebruiker moet het recht “reservation:modify” hebben.
2.2.2 Request De request is een enkel JSON object met gegevens; De gegevens van de gespecificeerde reservering worden aangepast naar de nieuwe gegevens. De volgende velden kunnen in de JSON aanwezig zijn: visitor name visitor email status date 2.2.3
String String String String
De naam van de bezoeker. Het e-mail adres van de bezoeker. “Pending”, “Active” of “Completed”. Gewenste datum: yyyy-mm-dd.
Response N/A
2.2.4 Postconditie Als de status van een reservering is veranderd is ook automatisch de status van de betreffende stukken aangepast. 2.3 DELETE Verwijder een reservering. 2.3.1
Authenticatie
2.3.2
Request
2.3.3
Response N/A
De geauthenticeerde gebruiker moet het recht “reservation:modify” hebben.
N/A
2.3.4 Postconditie Als het een actieve reservering betreft is de status van de in de reservering opgenomen stukken veranderd naar beschikbaar.
97
Architectural Design - 13
4.1.5 1
Order Management
/order/
De collectie van orders voor reproducties die in het systeem zijn opgeslagen. 1.1 GET Vraag een lijst met orders in de database op. 1.1.1
Authenticatie
1.1.2
Request
page page len sort sort dir ...
De geauthenticeerde gebruiker moet het recht “order:view” hebben.
De query string kan de volgende parameters bevatten:
Het paginanummer om op te vragen. Default: 1 Het aantal records per pagina. Default: Implementatieafhankelijk. Optioneel attribuut om op te sorteren. Ten minste mogelijk: “status” en “visitor name”. De volgorde van sorteren: “asc” of “desc”. Default: “asc”. Elk String,Boolean of Integer veld kan worden gefilterd met een parameter met dezelfde naam.
1.1.3 Response Een lijst van de opgevraagde reserveringen in een HTML pagina of JSON. De JSON zal bestaan uit een lijst van objects met ten minste de volgende velden: customer name customer email status items
String String String ListhListhStringii
De naam van de klant. Het e-mail adres van de klant. “Pending” of “Completed”. De lijst van hpid, filetypei pairs waarvan reproducties zijn aangevraagd.
1.2 POST Maak een nieuwe order aan. 1.2.1
Authenticatie
Geen authenticatie vereist.
1.2.2 Request De request is een enkel JSON object met gegevens. Er wordt een nieuwe order aangemaakt met de opgegeven data. Tenminste de volgende informatie moet worden meegegeven: customer name customer email items
String String ListhListhStringii
De naam van de klant. Het e-mail adres van de klant. De lijst van hpid, filetypei pairs waarvan reproducties zijn aangevraagd.
1.2.3 Response Bij een succesvolle operatie wordt een 303 redirect teruggegeven. De redirect zal leiden naar de nieuwe order.
98
Architectural Design - 14
2
/order/[id]
Een enkele order. 2.1 GET Vraag informatie over de inhoud van deze order. 2.1.1
Authenticatie
2.1.2
Request
De geauthenticeerde gebruiker moet het recht “order:view” hebben.
N/A
2.1.3 Response Informatie over de order in HTML of JSON formaat. Ten minste de volgende velden zullen in de JSON aanwezig zijn: customer name customer email status items
String String String ListhListhStringii
De naam van de klant. Het e-mail adres van de klant. “Pending” of “Completed”. De lijst van hpid, filetypei pairs waarvan reproducties zijn aangevraagd.
2.2 PUT Verander de gegevens van een order. 2.2.1
Authenticatie
De geauthenticeerde gebruiker moet het recht “order:modify” hebben.
2.2.2 Request De request is een enkel JSON object met gegevens; De gegevens van de gespecificeerde order worden aangepast naar de nieuwe gegevens. De volgende velden kunnen in de JSON aanwezig zijn: customer name customer email status 2.2.3
String String String
De naam van de klant. Het e-mail adres van de klant. “Pending” of “Completed”.
Response N/A
2.3 DELETE Verwijder een order. 2.3.1
Authenticatie
2.3.2
Request
2.3.3
Response N/A
De geauthenticeerde gebruiker moet het recht “order:modify” hebben.
N/A
99
Architectural Design - 15
4.1.6 1
Permission Management
/permission/
De collectie van verzoeken voor toestemming voor inzage. 1.1 GET Vraag een lijst met verzoeken in de database op. 1.1.1
Authenticatie
1.1.2
Request
page page len sort
sort dir search ...
De geauthenticeerde gebruiker moet het recht “permission:view” hebben.
De query string kan de volgende parameters bevatten:
Het paginanummer om op te vragen. Default: 1 Het aantal records per pagina. Default: Implementatieafhankelijk. Optioneel attribuut om op te sorteren. Ten minste mogelijk: “visitor name”, “visitor email”, “status”, “from date”, “to date”, “research organization”, “research subject”. De volgorde van sorteren: “asc” of “desc”. Default: “asc”. Zoek in alle velden behalve “status”. Elk String,Boolean of Integer veld kan worden gefilterd met een parameter met dezelfde naam.
1.1.3 Response Een lijst van de opgevraagde verzoeken in een HTML pagina of JSON. De JSON zal bestaan uit een lijst van objects met ten minste de volgende velden: visitor name visitor email address status from date
String String String String String
to date
String
research organization
String
research subject explanation item
String String ListhListhStringii
De naam van de bezoeker. Het e-mail adres van de bezoeker. Volledig post adres van de bezoeker. “Pending” of “HANDLED”. Start datum van de toestemming, formaat: yyyyMM-dd. Eind datum van de toestemming, formaat: yyyyMM-dd. Opdrachtgever van onderzoek waarvoor toegang nodig is tot stukken met restricties. Onderwerp van onderzoek. Onderbouwing toestemmingsaanvraag. De hpid, statusi paren van de stukken waarvoor toestemming is verzocht.
1.2 POST Maak een nieuw verzoek aan. 1.2.1
Authenticatie
Geen authenticatie vereist.
1.2.2 Request De request is een enkel JSON of form object met gegevens. Er wordt een nieuw verzoek met de opgegeven data. Tenminste de volgende informatie moet worden meegegeven:
100
Architectural Design - 16
visitor name visitor email address status from date
String String String String String
to date
String
research organization
String
research subject explanation item
String String ListhStringi
De naam van de bezoeker. Het e-mail adres van de bezoeker. Volledig post adres van de bezoeker. “Pending” of “HANDLED”. Start datum van de toestemming, formaat: yyyyMM-dd. Eind datum van de toestemming, formaat: yyyyMM-dd. Opdrachtgever van onderzoek waarvoor toegang nodig is tot stukken met restricties. Onderwerp van onderzoek. Onderbouwing toestemmingsaanvraag. De PIDs van de stukken waarvoor toestemming wordt verzocht.
1.2.3 Response Bij een succesvolle operatie wordt een 303 redirect teruggegeven. De redirect zal leiden naar het nieuwe verzoek.
101
Architectural Design - 17
2
/permission/[id]
Een enkel verzoek. 2.1 GET Vraag informatie over de inhoud van dit verzoek. 2.1.1
Authenticatie
2.1.2
Request
De geauthenticeerde gebruiker moet het recht “permission:view” hebben.
N/A
2.1.3 Response Informatie over het verzoek in HTML of JSON formaat. Ten minste de volgende velden zullen in de JSON aanwezig zijn: visitor name visitor email address status from date
String String String String String
to date
String
research organization
String
research subject explanation item
String String ListhListhStringii
De naam van de bezoeker. Het e-mail adres van de bezoeker. Volledig post adres van de bezoeker. “Pending” of “HANDLED”. Start datum van de toestemming, formaat: yyyyMM-dd. Eind datum van de toestemming, formaat: yyyyMM-dd. Opdrachtgever van onderzoek waarvoor toegang nodig is tot stukken met restricties. Onderwerp van onderzoek. Onderbouwing toestemmingsaanvraag. De hpid, statusi paren van de stukken waarvoor toestemming is verzocht.
2.2 PUT Verander de gegevens van een verzoek. 2.2.1
Authenticatie
De geauthenticeerde gebruiker moet het recht “permission:modify” hebben.
2.2.2 Request De request is een enkel JSON object met gegevens; De gegevens van het gespecificeerde verzoek worden aangepast naar de nieuwe gegevens. De volgende velden kunnen in de JSON aanwezig zijn: visitor name visitor email address status from date to date research organization
String String String String String String String
research subject explanation item
String String ListhListhStringii
2.2.3
De naam van de bezoeker. Het e-mail adres van de bezoeker. Volledig post adres van de bezoeker. “Pending” of “HANDLED”. Start datum van de toestemming, formaat: yyyy-MM-dd. Eind datum van de toestemming, formaat: yyyy-MM-dd. Opdrachtgever van onderzoek waarvoor toegang nodig is tot stukken met restricties. Onderwerp van onderzoek. Onderbouwing toestemmingsaanvraag. De hpid, statusi paren van de stukken waarvoor toestemming wordt verzocht.
Response N/A
2.3 DELETE Verwijder een verzoek. 102
Architectural Design - 18
2.3.1
Authenticatie
2.3.2
Request
2.3.3
Response N/A
De geauthenticeerde gebruiker moet het recht “permission:modify” hebben.
N/A
103
Architectural Design - 19
4.2
Externe Informatie API
Voor het ophalen van informatie over de opgevraagde stukken worden de PIDs (na afstrippen van de itemnummers) doorgegeven naar de externe API abstractielaag. Deze laag zal API calls maken naar de service waar de informatie over de stukken in opgeslagen staat. APIs voor informatie moeten ten minste een call ondersteunen met de PID als input en outputvelden voor de naam en description van een stuk. Meer informatie is niet vereist. Bij het IISG zal gebruik worden gemaakt van de bestaande OAI-PMH interface waarvanuit informatie over alle stukken te benaderen is.
4.3
Externe Reproductie API
Voor het downloaden van gedigitalizeerde stukken en het opvragen van de mogelijke filetypes worden de PIDs van aangevraagde reproducties doorgegeven naar een andere externe API abstractielaag. Deze laag maakt API calls naar repositories met digitale reproducties van stukken. De API moet ondersteuning bieden voor het aanmaken van credentials of een access key waarmee bestanden kunnen worden gedownload. Ook moet de API kunnen aangeven of er digitale reproducties beschikbaar zijn, en welke bestandstypen mogen worden besteld. Bij het IISG zal gebruik worden gemaakt van de Shared Object Repository waar reproducties van alle gedigitalizeerde stukken in zijn opgenomen.
104
Architectural Design - 20
Bijlage G
Deliverance: Technical Design Milestone 1 Lucas de Vries & Stefan van Wouw
105
Inhoudsopgave 1 Inleiding
2
2 Implementatie Specifieke Overwegingen 2.1 Programmeertaal . . . . . . . . . . . . . 2.2 Framework . . . . . . . . . . . . . . . . 2.3 Libraries . . . . . . . . . . . . . . . . . . 2.4 Software en Tools . . . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
3 Structureel Ontwerp 4 Control Flow 4.1 User Ophalen . . . . . . . . . . . . 4.2 Record Ophalen . . . . . . . . . . . 4.3 Specifieke Stukken Opvragen . . . 4.4 Stukken Aanmaken/Wijzigen . . . 4.5 Stukken Verwijderen . . . . . . . . 4.6 Nieuwe Reservering Aanmaken . . 4.7 Lijst van Reserveringen Opvragen .
3 3 3 4 4 5
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
7 7 8 9 10 11 12 13
A Implementatieplan 14 A.1 Iteratie 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 A.2 Iteratie 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 B Testplan B.1 Test Methodiek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.2 Test Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.3 Test Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
106
16 16 17 19
Technical Design - 1
Hoofdstuk 1
Inleiding In het Architectural Design is het globale ontwerp van het systeem gepresenteerd. Het systeem wordt niet meteen in zijn geheel ge¨ımplementeerd, maar in milestones. Per Milestone wordt er een gedetailleerd ontwerp gemaakt, waarna dit in een aantal iteraties wordt ge¨ımplementeerd. Dit document beschrijft de ontwerp en implementatiebeslissingen die zijn genomen voor de eerste milestone van het systeem. In bijlage A is weergegeven welke delen van het systeem in deze milestone zullen worden ge¨ımplementeerd en in bijlage B is hiervoor een testplan opgesteld. Er zijn een aantal implementatie specifieke beslissingen gemaakt, deze worden beschreven in hoofdstuk 2. Daarna wordt het structureel ontwerp gegeven in hoofdstuk 3 en wordt de interactie tussen klassen besproken in hoofdstuk 4.
107
Technical Design - 2
Hoofdstuk 2
Implementatie Specifieke Overwegingen In dit hoofdstuk worden belangrijke beslissingen wat betreft programmeertaal, framework, libraries en tools besproken. Bij het overwegen is vooral rekening gehouden met de praktische kant van het verhaal. Er kan namelijk wel voor een bepaald framework of programmeertaal worden gekozen, maar als niemand anders binnen het Internationaal Instituut voor Sociale Geschiedenis (IISG) daar bekend mee is, maakt dat het systeem minder makkelijk onderhoudbaar. Naast de praktische kant, hangt de keuze ook af van persoonlijk gestelde prioriteiten, er is geen goed of fout.
2.1
Programmeertaal
Het te ontwikkelen systeem dient via het web te bereiken te zijn. Een programmeertaal waarmee webapplicaties kunnen worden geschreven en een taal waarin bovendien standaardoplossingen (libraries/frameworks) aanwezig zijn is benodigd. PHP, Python en Java zijn programmeertalen die allen standaardoplossingen bieden voor web-applicaties. Omdat Python minder vaak gebruik wordt dan PHP en Java, en het systeem ook onderhoudbaar moet blijven zonder dat er speciale Python programmeurs moeten worden aangenomen, valt deze programmeertaal af. Java en PHP worden beiden veel gebruikt voor web-applicaties en worden ook beiden gebruikt bij het IISG. Een groot verschil tussen Java en PHP is het feit dat Java is ontwikkeld met het Object Geori¨enteerd paradigma in het achterhoofd en PHP niet. In Java zijn mede daarom meer Object Geori¨enteerde libraries beschikbaar, die makkelijk in te bouwen zijn. Ook zijn er voor Java tools als Maven en Ant beschikbaar die de afhankelijkheden van het project regelen. PHP heeft hier op dit moment geen volwassen tools voor. Java heeft een grotere standaard bibliotheek beschikbaar, PHP daarentegen, moet het hebben van de (deels besturingssysteem afhankelijke) extensies en de veel kleinere Standard PHP Library. De voorkeur gaat om deze redenen uit naar Java, welke als programmeertaal gebruikt zal gaan worden.
2.2
Framework
De architectuur van het te ontwikkelen systeem maakt gebruik van het Model-View-Controller (MVC) ontwerppatroon. Het is daarom handig om gebruik te maken van een MVC framework dat al een aantal standaard-oplossingen biedt. Er zijn verscheidene MVC frameworks beschikbaar voor Java. De keuze is gevallen op het Spring MVC framework, omdat dit framework standaard-oplossingen biedt voor web-applicaties, makkelijk integreerbaar is met tools en libraries van derden, goed gedocumenteerd is, en bovendien met tevredenheid is gebruikt bij andere projecten van het IISG. Het laatste weegt zwaar, aangezien dit niet alleen laat zien dat professionele ontwikkelaars het een goed framework vinden, maar ook dat zij er al in thuis zijn. Dit maakt het systeem makkelijker onderhoudbaar en uitbreidbaar voor hen.
108
Technical Design - 3
2.3
Libraries
De volgende libraries zullen worden gebruikt in het systeem: JUnit JUnit is de standaard waarmee unit tests kunnen worden geschreven voor Java. Hibernate Hibernate is een Object Relational Mapper (ORM) en wordt gebruikt om de Model klassen van het systeem met de database te verbinden. Deze integreert goed met Spring MVC.
2.4
Software en Tools
Er wordt gebruik gemaakt van de volgende software en tools: PostgreSQL Er kon gekozen worden tussen PostgreSQL en MySQL als database software. De voorkeur van het IISG gaat uit naar PostgreSQL, omdat alle nieuwere producten daar op draaien. Verder maakt het voor het systeem niet uit of het gebruik maakt van PostgreSQL of MySQL, want beiden bieden wat het systeem nodig heeft. Maven De afhankelijkheden van het project en het build-proces worden beheert door Maven. Voordeel van Maven boven bijvoorbeeld Ant, is dat de afhankelijkheden van het project ook automatisch worden gedownload als deze niet zijn ge¨ınstalleerd op de computer waarop het project wordt gecompileerd. Trac Trac wordt gebruikt om voor de projectleider inzichtelijk te maken waar op elk moment aan gewerkt wordt. Het geeft een overzicht van alle taken die moeten worden uigevoerd, en wie welke taak aan het vervullen is. Dit is een wens vanuit het IISG. SVN/Git Zoals besloten in het Plan van Aanpak document gebruiken we Git als versiebeheersoftware. Er was een wens van het IISG om ook een centrale opslagplaats voor code en documentatie te hebben, omdat daar backups van worden gemaakt. We zullen een centrale SVN repository gebruiken om de veranderingen van Git heen te sturen.
109
Technical Design - 4
Hoofdstuk 3
Structureel Ontwerp De implementatie van milestone 1 zal 4 hoofdonderdelen/packages bevatten (record, permission, user, reservation), elk met eigen services en views. Om de globale werking en structuur van elk van deze packages te illustreren volgt een gesimplificeerd klassendiagram van de Record package, waarin de stippellijnen de globale control flow aangeven.
$
$
$
$ !
" " " "
# #
" "
"
#
# #
# #
! "
#
"
#
Figuur 3.1: Klassenvoorbeeld Record Package. Elk package heeft een Controller klasse, welke de aanroepen van zowel externe systemen als van gebruikers afvangt. De controller roept vervolgens een Service klasse aan. Deze klasse vertegenwoordigt
110
Technical Design - 5
de service die een package biedt. De controller kan aanroepen doen naar de service laag van zijn eigen package, maar ook naar die van andere packages. De service laag kan op zijn beurt weer aanroepen doen naar de Data Access Object (DAO) laag, welke de objecten die data (stukken, locaties etc.) representeren beheert.
111
Technical Design - 6
Hoofdstuk 4
Control Flow In dit hoofdstuk worden de belangrijkste software control flows beschreven. Per control flow staat aangegeven welke API specificaties gerelateerd zijn. Alleen de dikgedrukte API specificaties zijn uitgewerkt in een sequence diagram, de anderen gaan op een soortgelijke manier. De User in elk sequence diagram kan worden gezien als een gebruiker (web-browser) of als extern systeem dat gebruik maakt van de API (bijv. VuFind). Het enige verschil tussen deze twee is het input en het output formaat.
4.1
User Ophalen
Sequence diagram gebruikt in de sequence diagrammen van sectie 4.4 en 4.5. Controller
UserService
UserDAO
EntityManager
getByToken(cookie_token) getByToken(cookie_token) getCriteriaBuilder() b : CriteriaBuilder c = b.createQuery(User.class) c.where(b.equals(...get(User_.token), cookie_token) u = c.getSingleResult() u : User u : User Controller
UserService
UserDAO
EntityManager
www.websequencediagrams.com
112
Technical Design - 7
4.2
Record Ophalen
Sequence diagram gebruikt in de sequence diagrammen van sectie 4.3 tot en met 4.5.
Controller
RecordService
RecordDAO
EntityManager
getByPId(pid) getByPId(pid) getCriteriaBuilder() b : CriteriaBuilder c = b.createQuery(Record.class) c.where(b.equals(...get(Record_.pid), pid) r = c.getSingleResult() r : Record r : Record Controller
RecordService
RecordDAO
EntityManager
www.websequencediagrams.com
113
Technical Design - 8
4.3 4.3.1
Specifieke Stukken Opvragen Gerelateerde API Specificaties
• GET /record/[pid,pid,pid,. . . ] • GET /reservation/[id] • GET /permission/[id]
4.3.2
Sequence Diagram
User
RecordController
GET /record/pid1,pid2,... loop
[for each pid in url] Executing 'Record Ophalen' returns r records.add(r)
alt
[records.isEmpty()] 404: page not found [otherwise] 200: list of records found
User
RecordController
www.websequencediagrams.com
114
Technical Design - 9
4.4
Stukken Aanmaken/Wijzigen
4.4.1
Gerelateerde API Specificaties
• PUT /record/[pid,pid,pid,. . . ] • PUT /reservation/[id] • PUT /permission/[id]
4.4.2
Sequence Diagram
User
RecordController
RecordLookupService
RecordService
ContactDAO
LocationDAO
PUT /record/pid1,pid2,... Executing Fetch User Sequence returns u alt
[u == null || !u.hasPermission("record:modify")] 403: Forbidden
alt
[!u.hasPermission("record:permissions") && Provided 'record:permissions' fields] 403: Forbidden
loop
[for each pid in url] On any DB error: Rollback and return 500: Internal Server Error Executing Fetch Record Sequence returns r
alt
[r == null] r = new Record() getName(pid) api.iisg.nl name : String Set record fields add(r)
[otherwise] Modify record/contact fields save(r)
opt Set contact and location information addContact/saveContact(r,contact) add/save(contact)
loop
[for each location] addLocation/saveLocation(r,location) add/save(location)
200: Ok User
RecordController
RecordLookupService
RecordService
ContactDAO
LocationDAO
www.websequencediagrams.com
115
Technical Design - 10
116
RecordController
200: Ok
[for each pr in r.permissionRequests]
loop
User
[for each reservation in r.reservations]
loop
remove(r)
[for each location in r.locations]
[r != null]
Executing 'Record Ophalen' returns r
On any DB error: Rollback and return 500: Internal Server Error
[for each pid in url]
403: Forbidden
[u == null || !u.hasPermission("record:modify")]
Executing 'User Ophalen' returns u
loop
alt
loop
alt
RecordController
RecordDAO
RecordService
RecordDAO
remove(pr)
remove(reservation)
remove(location)
remove(r.contact)
remove(r)
RecordService
ContactDAO
ContactDAO
LocationDAO
LocationDAO
ReservationService
ReservationService
www.websequencediagrams.com
PermissionService
PermissionService
4.5.2
DELETE /record/pid1,pid2,...
4.5.1
User
4.5 Stukken Verwijderen
Gerelateerde API Specificaties
• DELETE /record/[pid,pid,pid,. . . ] • DELETE /reservation/[id]
• DELETE /permission/[id]
Sequence Diagram
Technical Design - 11
4.6
Nieuwe Reservering Aanmaken
4.6.1
Gerelateerde API Specificaties
• POST /reservation/ • POST /permission/
4.6.2 User
Sequence Diagram ReservationController
ReservationService
ReservationDAO
EntityManager
ReservationMailer
POST /reservation/ r = new Reservation() Set reservation fields add(r) add(r) persist(r) On any DB error: Rollback and return 500: Internal Server Error
mail(r)
303: /reservation/
User
ReservationController
ReservationService
ReservationDAO
EntityManager
ReservationMailer
www.websequencediagrams.com
117
Technical Design - 12
4.7 4.7.1
Lijst van Reserveringen Opvragen Gerelateerde API Specificaties
• GET /reservation/ • GET /permission/
4.7.2
Sequence Diagram
User
ReservationController
ReservationService
ReservationDAO
EntityManager
GET /reservation/ getCriteriaBuilder() getCriteriaBuilder() getCriteriaBuilder() b : CriteriaBuilder b : CriteriaBuilder b : CriteriaBuilder c = b.createQuery(Reservation.class) c.where(b.like(...get(Reservation_.name), name) Add additional filters... list(c) list(c) reservations = c.getResultList() reservations : List reservations : List 200: reservation list view/empty list User
ReservationController
ReservationService
ReservationDAO
EntityManager
www.websequencediagrams.com
118
Technical Design - 13
Bijlage A
Implementatieplan De implementatie zal worden uitgevoerd in twee aparte iteraties. Bij de eerste iteratie zal het metadata systeem worden opgezet en begonnen worden aan het aanmaken van aanvragen/reserveringen. Bij de tweede iteratie wordt de reserveringsfunctionaliteit afgemaakt en zou het mogelijk moeten worden om aanvragen voor toestemming in te vullen en te bemiddelen. Het bestellen van reproducties wordt niet bij de eerste milestone ge¨ımplementeerd omdat het benodigde systeem (de Shared Object Repository (SOR)) nog niet in gebruik is genomen, en er daarom geen werkend product zou kunnen worden afgeleverd. Voor beide iteraties volgt het MoSCoW schema met de eisen die worden ge¨ımplementeerd en de prioriteiten die gesteld zijn voor deze eisen. M S C W
A.1
Must have Should have Could have Won’t have (but would like)
Iteratie 1
Prioriteit M M M S S S S C C C
Timespan Week 1 Week 1 Week 1 Week 2 Week 2 Week 2 Week 2 Week 2 Week 2 Week 2
Requirement [F:13] Bijhouden metadata over stukken [F:12] Bijhouden status van een stuk [F:6] Metadata invullen/bewerken [F:2] Stukken aanvragen [F:2a] Maximaal 3 stukken per aanvraag [F:2c] Reserveren huidige dag voor 16:00 [F:1] Uitleenstatus opvragen [F:7] Aanvragen bekijken [F:2b] Wachtnummer aanvragen huidige dag [F:14a] Informatie- en plaatsvervangingsvellen printen
119
Technical Design - 14
A.2
Iteratie 2
Prioriteit M M M M M M M M S S S S C C W
Timespan Week 3 Week 3 Week 3 Week 3 Week 3 Week 3 Week 3 Week 3 Week 4 Week 4 Week 4 Week 4 Week 4 Week 4 Week 4
Requirement [F:5] Inloggen medewerker [F:15] Geen registratie (account) voor bezoekers [F:7] Aanvragen bekijken [F:8] Status van een aanvraag aanpassen [F:1] Uitleenstatus opvragen [F:2] Stukken aanvragen [F:2a] Maximaal 3 stukken per aanvraag [F:2c] Reserveren huidige dag voor 16:00 [F:4] Toestemming verzoeken [F:2b] Wachtnummer aanvragen huidige dag [F:9] Toestemming voor inzage bemiddelen [F:14a] Informatie- en plaatsvervangingsvellen printen [F:14] Aanvragen automatisch uitprinten [F:4a] Bericht ter goedkeuring/afwijzing toestemming [F:9a] Toestemmingsverzoek direct naar contactpersoon
120
Technical Design - 15
Bijlage B
Testplan B.1
Test Methodiek
Om ervoor te zorgen dat het systeem naar behoren werkt, zal er op meerdere manieren worden getest. Voor elke iteratie zijn er verschillende test categorie¨en: 1. Unit Tests: Binnen een klasse op methode niveau testen van code. Dit zal worden gedaan bij alle niet-triviale methoden. Dit zorgt ervoor dat de werking van de methoden wordt gegarandeerd. Test specificaties worden ad-hoc gespecificeerd waar nodig. 2. Integration Tests: Dit type tests zorgt ervoor dat de samenwerking tussen klassen wordt getest. Voor zowel elk gespecificeerd sequence diagram uit hoofstuk 4, als voor alle soortgelijke control flows, zal er voor zover mogelijk een test worden geschreven. 3. System Tests: Dit type tests zorgt ervoor dat er aan de requirements wordt voldaan. Aan de hand van het test script in bijlage B.2 zal worden gekeken of het systeem aan de opgestelde functionele requirements voldoet. De niet-functionele requirements zullen worden beoordeeld in overleg met de projectleider. 4. Acceptance Tests: Dit type tests zorgt ervoor dat het systeem ook daadwerkelijk doet wat de gebruiker ervan verwacht. Aangezien er een prototype wordt opgeleverd, zullen er geen acceptance tests worden uitgevoerd.
121
Technical Design - 16
B.2
Test Script
Met dit test script wordt getest of het systeem aan de functionele requirements voldoet. Alvorens te beginnen met testen, dient de data uit bijlage B.3 aanwezig te zijn in de database. In de tabel kan worden aangegeven dat een test geslaagd is (P van Pass), dat een test gefaald is (F van Failed) of dat een test niet uit te voeren is omdat er bijvoorbeeld op knoppen gedrukt moeten worden die nog niet zijn ge¨ımplementeerd (I van incomplete).
1.
2.
3.
4.
5.
6.
7.
Stap - Begin op de login pagina voor medewerkers. - Vul de gebruikersnaam “Fout” en het wachtwoord “Fout” in. - Klik op “Login”. - Vul de gebruikersnaam “Peter” en het wachtwoord “Fout” in. - Klik op “Login”. - Vul de gebruikersnaam “Test” en het wachtwoord “Test” in. - Klik op “Login”. - Klik op “Bewerk Stukken”. - Vul in het ‘Zoek op titel’ veld de naam “Dora Russell” in. - Klik op “Zoek”. - Klik op het eerste archief in het resultaat. - Klik op de radiobutton “Beperkt” voor restrictie type. - Vul bij het tekstvak “Restrictie Details” de data “Test Restrictie” in. - Klik op “Opslaan”. - Vul onder “Locaties” het type “Microfilm”, verdieping “4” in, laat de overige velden leeg. - Klik op “Locatie Toevoegen”. - Selecteer bij Gebruik Type de locatie “Microfilm”. - Klik op “Opslaan”.
8.
- Klik op “Bewerk Stukken”. - Vul de PID “11051175 MARC” in. - Klik op “Toon”.
9.
- Klik op “Verwijder Metadata”.
10. 11. 12.
- Klik op “Bewerk Stukken”. - Vul de PID “11051175 MARC” in. - Klik op “Toon”. - Klik op “Reserveringsoverzicht”. - Selecteer de aanvraag en klik op “Print Locaties”.
Verwacht Resultaat
Getest
Foutmelding dat het wachtwoord niet klopt of de gebruiker niet bestaat.
[F:5]
Foutmelding dat het wachtwoord niet klopt of de gebruiker niet bestaat.
[F:5]
De startpagina voor ingelogde medewerkers.
[F:5]
- De PID en titel van het archief zijn zichtbaar. - Invulvelden voor metadata over het archief.
[F:6], [F:13]
Een melding dat de gegevens succesvol zijn opgeslagen.
[F:6], [F:13]
Een melding dat de locatie is toegevoegd.
[F:6], [F:13]
Een melding dat de gegevens succesvol zijn opgeslagen.
[F:6], [F:13]
- Invulvelden voor metadata over het archief. - Bestaande metadata van dit archief in de invulvelden. - De zojuist ingevulde restrictie voor het archief. - Een melding dat de record is verwijderd. - Invulvelden voor metadata over het archief. - Geen ingevulde data in de velden. De aanvraag in de database. 4 printjes: 2 voor elk stuk in de aanvraag.
122
[F:6], [F:13]
[F:6], [F:13] [F:6], [F:13] [F:7] [F:7], [F:14a]
Technical Design - 17
P/F/I
13.
14.
Stap - Klik op “Scan Items”. - Vul een item nummer uit de print in (staat onder de barcode) in en druk op Enter (scan indien mogelijk de print). - Herhaal deze stap voor het andere item uit de reservering. - Vul een item nummer uit de print in (staat onder de barcode) in en druk op Enter (scan indien mogelijk de print). - Herhaal deze stap voor het andere item uit de reservering.
15.
- Vul een item nummer uit de print in (staat onder de barcode) in en druk op Enter (scan indien mogelijk de print). - Herhaal deze stap voor het andere item uit de reservering.
16.
- Klik op “Toestemmingsaanvragen”.
17.
- Klik op de weergegeven toestemmingsaanvraag.
18.
19.
20.
21.
22.
23.
- Klik bij item 15 op “Toestemming Geven” en bij item 16 op “Toestemming Weigeren”. - Klik “Opslaan”. - Ga naar de interface voor bezoekers. - Ga naar de pagina om een aanvraag te maken voor item 13 en 14 in “Alexander Berkman Papers”. - Vul de naam “Test Test” en het email “[email protected]” in. - Vul de huidige datum in. - Klik op “Reserveer”. - Ga naar de interface voor bezoekers. - Ga naar de pagina om een aanvraag te maken voor item 14 in “Alexander Berkman Papers”. - Ga naar de interface voor bezoekers. - Ga naar de pagina om een aanvraag te maken voor item 15 in “Alexander Berkman Papers”. - Klik op “Vraag Toestemming Aan”. - Vul in naam “John Doe” en email “[email protected]”. Vul bij huidig onderzoek de waarde “Test Script” in. - Klik op “Aanvragen”.
Verwacht Resultaat
Getest
- De reservering is naar status “Actief” veranderd. - Het ingevoerde item is van status “Aangevraagd” naar status “Uitgeleend” veranderd.
[F:12], [F:8]
- Het ingevoerde item is van status “Uitgeleend” naar status “Teruggebracht” veranderd.
[F:12], [F:8]
- Het ingevoerde item is van status “Teruggebracht” naar status “Beschikbaar” veranderd. - Indien dit het laatste item uit de reservering was is de status van de reservering naar “Afgehandeld” veranderd. De toestemmingsaanvraag die in de database staat. De twee stukken die zijn aangevraagd: 15 en 16 van het archief “Alexander Berkman Papers”.
[F:12], [F:8]
[F:9] [F:9]
De toestemmingsaanvraag is gemarkeerd als afgehandeld.
[F:9]
Invulvelden voor naam, email en datum.
[F:2]
- Een bericht dat de aanvraag met succes is opgeslagen. - Een willekeurig wachtnummer voor de reservering. - Indien het automatisch printen is ge¨ımplementeerd, een uitdraai van de gereserveerde stukken.
[F:2], [F:14]
Melding dat het stuk niet beschikbaar is.
[F:2]
De melding dat het archief restricties heeft en de vraag of er een aanvraag voor toestemming moet worden gemaakt.
[F:4]
Een bericht dat de aanvraag voor toestemming met succes is opgeslagen en er een e-mail wordt verstuurd zodra deze is afgehandeld.
[F:4]
123
Technical Design - 18
P/F/I
B.3
Test Data
De test database moet bestaan uit de volgende data om het test script te kunnen voltooien:
B.3.1
Gebruikers
1. “Test” met wachtwoord “Test”. Volledige privileges. 2. “Fout” met wachtwoord “Test”. Geen privileges.
B.3.2
Archieven
1. Een archief met de naam “Alexander Berkman Papers” en PID “10729085 EAD”.
B.3.3
Records
1. Een record met inventarisnummer 13 voor het archief “Alexander Berkman Papers” met de restrictie Open, geen contactinformatie, geen embargo en de locatie velden volledig ingevuld (microfilm/origineel). Het gebruik type is gezet op “Microfilm” 2. Een record met inventarisnummer 14 voor het archief “Alexander Berkman Papers” met de restrictie Open, geen contactinformatie, geen embargo en de locatie van het origineel slechts “Verdieping 4”. 3. Een record met inventarisnummer 15 voor het archief “Alexander Berkman Papers” met de restrictie Beperkt, contactinformatie, geen embargo en de locatie slechts “Verdieping 5”. 4. Een record met inventarisnummer 16 voor het archief “Alexander Berkman Papers” met de restrictie Beperkt, contactinformatie, geen embargo en de locatie slechts “Verdieping 5”.
B.3.4
Aanvragen
1. Een aanvraag voor items 13 en 14 in “Alexander Berkman Papers” met naam “John Doe” en email “[email protected]”, status “Aangevraagd”.
B.3.5
Aanvragen voor Toestemming
1. Een aanvraag voor toestemming op naam “Test Test” en email “[email protected]” voor item 15 en 16 van het archief “Alexander Berkman Papers”.
124
Technical Design - 19