Brukerdokumentasjon Brukerdokumentasjon

Transkript

1 Brukerdokumentasjon Brukerdokumentasjon

2 2

3 Forord Produktdokumentasjonen er en teknisk beskrivelse av systemet som vi har utviklet i hovedprosjektet for UDP AS. Hovedprosjektet er avsluttende prosjekt for dataingeniørstudenter og informasjonsteknologistudenter ved Høgskolen i Oslo. Dette dokumentet er beregnet for den i UDP AS som skal videreutvikle systemet og for andre som er interessert i å se hvordan systemet er bygget opp. Bakgrunnen for hvorfor systemet fikk denne utformingen er nærmere belyst i prosessdokumentasjonen. 3

4 Innholdsfortegnelse Forord... 3 Innholdsfortegnelse... 3 Innledning... 6 Om bedriften... 6 Dagens situasjon... 6 Beskrivelse av systemet... 6 Teknologier... 8 Groovy... 8 Grails... 8 MVC... 8 Hibernate... 9 Log4j... 9 JUnit... 9 Gant... 9 OpenCSV... 9 JFreeChart... 9 Open Flash Chart Installasjonsveiledning Installasjon av applikasjonen for testing og utvikling Konfigurasjon av database Installasjon på applikasjonsservere Databasen Struktur Beskrivelse av tabellene Form - skjema Question - spørsmål Option - alternativ Result - utfall Reply - besvarelse Choice - valg User - bruker Authority - rolle Group - gruppe Controllere Views - Groovy Server Pages Layouts Templates Tagbiblioteker JavaScriptTagLib MenuTagLib Serviceklasser FormService QuestionService SurveyService GroupService UserService Autentisering

5 Tilgangskontroll i kontrollere Tilgangskontroll i views Registrering av brukere Innlogging og utlogging Oppretting og redigering av skjema Oppretting av skjema Kopiering av skjema Oppretting av spørsmål Oppdatering av spørsmål Sletting av spørsmål Utfylling av skjema Oppsett av besvarelse Henting av en side med spørsmål Innlevering av et skjema Henting av rapporter Henting av data til rapportene Rendring av rapporter Tester

6 Innledning Om bedriften UDP AS er en relativet liten konsulentbedrift. De ansatte jobber mest utplassert hos sine oppdragsgivere, i oppdrag knyttet til systemutvikling, prosjektledelse og drift. I tillegg utvikles egne produkter som UDP selger. Dagens situasjon UDP har en del produkter hvor datainnsamling via skjema kan være nyttig. Denne skjemageneratoren skal være en verktøyskasse som kan danne grunnlag for slik funksjonalitet i de forskjellige fagsystemene til UDP. Beskrivelse av systemet Systemet er en webapplikajon som gjør det mulig for brukere å opprette og svare på spørreskjema på nett. Brukere er av tre forskjellige typer, med tilsvarende nivåer av privilegier (bruker, gruppeadmin, Admin). For å styre tilgang til de forskjellige delene i systemet plasseres alle brukere i grupper. Grupper kan opprettes av en med hovedbrukerprivilegier (admin). Denne hovedbrukeren legger også brukere inn i gruppen. Dette kan være både vanlige brukere, som bare kan ta tester, og en groupadmin, som har lov til å administrere denne gruppen. Et skjema tilhører alltid en gruppe og en bruker med privelegier som GroupAdmin kan opprette og redigere skjema i grupper han administrerer. Alle brukere kan svare på skjema i grupper de hører til, og på skjema fra andre grupper som ikke har begrenset tilgang. Det er ikke nødvendig å være innlogget for å svare på skjema, men dette gjelder bare skjema med ubegrenset tilgang. Utfyllingen av et skjema er laget for å være fleksibel og den lar en innlogget bruker fortsette der han ga seg om han tar en pause. Siden for å avgi svar er også laget for å kunne brukes på mindre håndholdte enheter. Systemet kan generere rapporter over svarene som har blitt gitt på de forskjellige undersøkelesene. Systemet kan på det nåværende tidspunkt generer rapporter som html-side, som en CSV fil, Som bilde (graf) og som Flash (graf). Dette er noe som lett kan utvides med flere typer om det er ønskelig. Følgende funksjonalitet er implementert: Administrasjon av brukere. o Registrere brukere av flere typer. o Slette/endre brukere. Administrasjon av grupper. o Oppretting av grupper. o Sette administrator for grupper. 6

7 o Legge brukere inn i grupper. o Slette/endre grupper. Administrasjon av skjema(oppretting/endring). o Oppretting av skjema. o Sette tilgjengelighet for skjemaet. o Endring av skjema. o Kopiering av skjema. o Sletting av skjema. o Legge til/endre spørsmål av flere typer. o Fjerne spørsmål. Gjennomføring av tester. o Både med vanlig maskin og mobilt? o Ikke fullstendige tester kan gjenopptas. Generering av rapporter i flere formater. 7

8 Teknologier Groovy Groovy er et scriptspråk på linje med Python, Ruby eller Smalltalk, men laget for å samarbeide tett med Java. Syntaksen oppleves som en mer kompakt form av Java, og funksjonaliteten skal være like rik som andre scriptspråk. Det tette samarbeide med Java henger sammen med at Groovy har Java i bunnen, slik at det kan kjøres på Java Virtual Machine, og benytte alle Javas biblioteker. Av samme grunn kan Groovys klasser og rutiner benyttes i Java-applikasjoner. Grails Grails er et web-rammeverk for Javaplatformen med åpen kildekode. Det er laget for at mest mulig av rutinekoding og strukturering av en applikasjon automatiseres. Ved å følge enkelte fastsatte konvensjoner i for eksempel navngiving, kan mye kode og struktur for en applikasjon genereres ut fra enkle domenebeskrivelser. Forskjellige verktøy for webutvikling som Spring, Hibernate, Log4j, JUnit og Ant er integrert i Grails og bruken av disse er også automatisert, slik at brukeren slipper å forholde seg til disse. Grails er strukturert etter designmønsteret MVC (Model-View-Controller). MVC MVC er en designarkitektur beregnet på å skille forretningslogikk, brukergrensesnitt og datalagring mest mulig fra hverandre. Model Model beskriver oppbygging av datakilden til applikasjonen. Når forretningslogikken blir for komplisert til å ligge i controlleren, trekkes den ut i egne moduler som kalles "service". Dette blir så et lag mellom model og controller, og regnes for å høre til model i denne arkitekturen. 8

9 View View er brukergrensesnittet: det som viser modellen til brukeren og tar imot brukerens interaksjon med systemet. Controller Controller er bindeleddet som mellom model og view. Controller kan ta imot beskjeder fra View og gjøre endringer i model. Controlleren kan også selv inneholde logikken som bearbeider data fra brukeren før disse lagres på datakilden. Fordeler med MVC Den største fordelen med å designe et system på denne måten er at man kan gjøre endringer i en av delene uten at det påvirker de andre. For eksempel kan databasen som systemet kjører på endres ved å modifisere model eller brukergrensesnittet kan redigeres i view. Hibernate Hibernate er et ORM (object-relational mapping) bibliotek for Java, som gir et rammeverk for å lagre domeneobjekter i en relasjonsdatabase. Hibernate støtter et stort antall databaser slik at applikasjonen ikke er databasespesifikk. Log4j Log4j er en løsning (med åpen kildekode) for logging i java, og er integrert i Grails. JUnit JUnit brukes til enhetstesting og integrasjonstesting i Grails. Gant Gant er et kommandolinjeverktøy som er en wrapper rundt Apache Ant. Den følger med i Grails og brukes til kompilering, kjøring og generering av elementer i et Grails-prosjekt. OpenCSV Et biblotek med åpen kildekode for å lage CSV filer til eksport av informasjon til andre applikasjoner. JFreeChart Et biblotek med åpen kildekode for å lage bilder av grafer og diagrammer. 9

10 Open Flash Chart Et biblotek med åpen kildekode for å lage flash bilder av grafer og diagrammer. 10

11 Installasjonsveiledning Installasjon av applikasjonen for testing og utvikling Før applikasjonen kan testes må Grails installeres. 1. Last ned en binærdistribusjon av Grails på 2. Følg installasjonsveiledningen som du finner på Når dette er gjort pakkes applikasjonen ut i en valgfri mappe. Åpne en terminal og bruk cd til å gå inn i mappen hvor applikasjonen er pakket ut. For at Grails skal kunne kompilere koden må grails upgrade kjøres. Det er viktig at du svarer 'y' på alle spørsmål: ~/ask$ grails upgrade Welcome to Grails Licensed under Apache Standard License 2.0 Grails home is set to: /home/mebi/grails Base Directory: /home/mebi/ask Running script /home/mebi/grails/scripts/upgrade.groovy Environment set to development WARNING: This target will upgrade an older Grails application to 1.1. However, tag libraries provided by earlier versions of Grails found in grails-app/taglib will be removed. The target will not, however, delete tag libraries developed by yourself. Are you sure you want to continue? (y, n) y... Installing plug-in hibernate-1.1 You currently already have a version of the plugin installed [hibernate- 1.1]. Do you want to upgrade this version? (y, n) y [delete] Deleting directory /home/mebi/ask/plugins/hibernate-1.1 [mkdir] Created dir: /home/mebi/ask/plugins/hibernate-1.1 [unzip] Expanding: /home/mebi/.grails/1.1/plugins/grails-hibernate- 1.1.zip into /home/mebi/ask/plugins/hibernate-1.1 Executing hibernate-1.1 plugin post-install script... Plugin hibernate-1.1 installed Please make sure you view the README for important information about changes to your source code.... Project upgraded Når dette er gjort kan applikasjonen kjøres ved hjelp av grails run-app: ~/ask$ grails run-app Welcome to Grails Licensed under Apache Standard License 2.0 Grails home is set to: /home/mebi/grails 11

12 Base Directory: /home/mebi/ask Running script /home/mebi/grails/scripts/runapp.groovy Environment set to development [groovyc] Compiling 2 source files to /home/mebi/.grails/1.1/projects/ask/classes Running Grails application :06:26,306 [main] INFO context.grailsconfigutils - [GrailsContextLoader] Grails application loaded :06:31,580 [main] INFO /prosjekt - Initializing Spring FrameworkServlet 'grails' Server running. Browse to For å kjøre de innebygde enhetstestene til applikasjonen brukes grails test-app: ~/ask$ grails test-app Welcome to Grails Licensed under Apache Standard License 2.0 Grails home is set to: /home/mebi/grails... [groovyc] Compiling 4 source files to /home/mebi/.grails/1.1/projects/ask/test-classes/integration Running 65 integration tests... Running test QuestionControllerTests...PASSED Running test AuthorityControllerTests...PASSED Running test ResultControllerTests...PASSED Running test FormControllerTests...PASSED Tests Completed in 20654ms Tests passed: 65 Tests failed: [junitreport] Processing /home/mebi/ask/test/reports/tests-testsuites.xml to /tmp/null [junitreport] Loading stylesheet jar:file:/home/mebi/grails/lib/ant-junit jar!/org/apache/tools/ant/taskdefs/optional/junit/xsl/junitframes.xsl [junitreport] Transform time: 925ms [junitreport] Deleting: /tmp/null Tests PASSED - view reports in /home/mebi/ask/test/reports. Konfigurasjon av database For å kunne bruke en annen database enn den innebygde minnedatabasen må config/datasource.groovy redigeres. Siden Grails bruker Hibernate som databasesystem er det støtte for mange forskjellige databaser, blant annet PostgreSQL og MySQL. For at Hibernate skal kunne benytte en database må JDBC-biblioteket til databasen legges i lib/. Eksempel på konfigurering av en kobling til en PostgreSQL-database som skal brukes i et produksjonsmiljø: 12

13 1 environments { datasource { 6 pooled = true 7 dbcreate = "update" 8 url = "jdbc:postgresql://<servernavn>:<port>/<database>" 9 driverclassname = "org.postgresql.driver" 10 dialect = org.hibernate.dialect.postgresqldialect 11 username = "<brukernavn>" 12 password = "<passord>" 13 } } Servernavn, port, database, brukernavn og passord som vises i deette eksemplet må byttes ut med de verdiene som passer for databasetilkoblingen som konfigureres. Installasjon på applikasjonsservere For å installere applikasjonsservere som for eksempel Tomcat, Jetty og JBoss må det lages en war-fil av applikasjonen. Dette gjøres med kommandoen grails war: ~/ask$ grails war Welcome to Grails Licensed under Apache Standard License 2.0 Grails home is set to: /home/mebi/grails Base Directory: /home/mebi/ask Running script /home/mebi/grails/scripts/war.groovy Environment set to production Warning, target causing name overwriting of name startlogging [groovyc] Compiling 2 source files to /home/mebi/.grails/1.1/projects/ask/classes [mkdir] Created dir: /home/mebi/.grails/1.1/projects/ask/staging [copy] Copying 114 files to /home/mebi/.grails/1.1/projects/ask/staging... [jar] Building jar: /home/mebi/ask/ask-0.1.war [delete] Deleting directory /home/mebi/.grails/1.1/projects/ask/staging Done creating WAR /home/mebi/ask/ask-0.1.war Når war-filen er laget, kopieres denne over i mappen applikasjonsserveren bruker til å kjøre applikasjonene. For mer informasjon om hvordan Grails virker med de forskjellige applikasjonsserverene se 13

14 Databasen Struktur Beskrivelse av tabellene Form - skjema Representerer et skjema, en spørreundersøkelse. Et skjema kan ha ingen eller mange spørsmål. Det er også bundet opp mot et valgfritt antall med utfall (Result). Skjemaet er alltid bundet opp mot en gruppe (Group). name String Navnet på skjemaet. Dette feltet er påkrevd. description String Beskrivelse av skjemaet. type Enum Skjematype, en av survey, test_complex og test_simple. questionsperpage int Hvor mange spørsmål som skal vises per side. Må være 1 eller høyere. published restricted boolean Hvis dette feltet er false, vil ikke skjemaet vises for brukerne. boolean Hvis dette feltet er true, vil skjemaet kun være tilgjengelig for medlemmer i gruppen skjemaet tilhører. validfrom Date Dato og tidspunkt skjemaet skal være tilgjengelig fra. Denne kan være null. Hvis published er false, vil ikke denne ha noen virkning. validto Date Dato og tidspunkt skjemaet skal være tilgjengelig til. Denne kan være null. Hvis published er false, vil ikke denne ha noen virkning. 14

15 Question - spørsmål Representerer et spørsmål på et skjema. Et spørsmål kan ha ingen eller flere alternativ (Option), avhengig av spørsmålstype. For eksempel vil et spørsmål av type "tekstfelt" ha ingen alternativer mens et spørsmål av type "avkrysningsbokser" vil ha ett eller flere alternativer. Et spørsmål vil alltid høre til et skjema. text String Teksten til spørsmålet. Dette feltet er påkrevd. type Enum Spørsmålstype, en av radio, checkbox, textfield, textarea og select. position int Spørsmålets posisjon i skjemaet. Dette feltet bør settes til returverdien til updatepositions() i QuestionService beskrevet nedenfor. Andre verdier vil gjøre at skjemaet ikke vises riktig. required boolean Om dette feltet er false, vil ikke spørsmålet være påkrevd for å kunne levere inn endelig besvarelse av skjemaet. Option - alternativ Representerer et svaralternativ. Et alternativ vil alltid høre til et spørsmål. text String Teksten som vises på alternativet. Dette feltet er påkrevd. points double Antall poeng dette alternativet gir. Brukes til å regne ut totalpoengsummen når resultatet skal vises. Dette feltet har ingen begrensning på hvilken verdi tallet kan ha. Result - utfall Representerer en mulig tilbakemelding til en som har besvart et skjema. Et utfall kan vise en melding til brukeren etter at besvarelsen er levert. Denne beskjeden kan være basert på hvor mange poeng brukeren oppnådde, regnet ut fra points-feltet i de valgte alternativene, eller det kan være en enkel melding. Hvilken form utfallet tar avgjøres av skjematype. Et utfall vil alltid høre til et skjema. name String Navnet til utfallet. Dette vil vises som tittelen på resultatsiden. Dette feltet er påkrevd. description String Beskjeden som vises til brukeren når utfallet vises. minpoints double Minimumspoengsummen som må oppnås for at dette utfallet skal vises. Det er ingen begrensning på hvilken verdi tallet kan ha. maxpoints double Maksimumspoengsummen som må oppnås for at dette utfallet skal vises. Det er ingen begrensning på hvilken verdi tallet kan ha. 15

16 Reply - besvarelse Representerer en besvarelse på et skjema. En besvarelse inneholder ett eller flere valg. En besvarelse vil alltid høre til et skjema. En besvarelse kan også høre til en bruker (User), men dette er ikke påkrevd i og med at anonyme brukere skal kunne svare på skjemaer. completed boolean Angir om besvarelsen er levert. Om den ikke er levert, kan brukeren fortsette på skjemaet en annen gang. Choice - valg Representerer svaret en bruker gir til et spørsmål. Et valg vil alltid være bundet til et spørsmål. Om spørsmålstypen er radioknapp, checkbox eller selectbox, vil også valget være bundet til alternativet som ble valgt. value String Verdien til valget. Brukes kun om spørsmålstypen er en tekstboks, og da vil dette feltet inneholde det som ble skrevet. User - bruker Representerer en bruker i systemet. En bruker kan ha en eller flere roller (Authority). En bruker kan være medlem i ingen, en eller flere grupper. Brukeren kan også være knyttet opp til besvarelser, slik at det er mulig å fortsette på uferdige besvarelser. Denne datatypen er basert på en mal fra Spring Security. username String Brukernavnet til brukeren. Dette feltet er påkrevd. userrealname String Det virkelige navnet til brukeren. passwd String Et hash av passordet til brukeren. For tiden er dette MD5, men det kan endres til noe mer sikkert om ønskelig i Spring Security. enabled boolean Angir om brukeren kan logge inn. Dette feltet blir satt av en administrator. String E-postadressen til brukeren. show String Angir om e-postadressen skal være tilgjengelig for andre brukere enn administratorer. Dette feltet er for tiden ikke i bruk. description String Beskrivelse av brukeren. Dette kan brukes av administratorer til å lagre merknader på brukeren. pass String Standardpassordet som brukes om brukeren angir et tomt passord under registrering. Dette feltet er for tiden ikke i bruk. 16

17 Authority - rolle Representerer en rolle i systemet. En rolle kan ha ingen eller flere brukere. En rolle kan være administrator (ROLE_ADMIN), gruppeadministrator (ROLE_GROUPADMIN) eller bruker (ROLE_USER). Disse tre rollene må være tilgjengelig i systemet for at det skal virke. Selv om det er støtte for å legge til nye roller, vil ikke disse ha noen effekt på tilgangskontrollen. Denne datatypen er basert på en mal fra Spring Security. authority String Navn på rollen. Dette feltet er påkrevd. description String Beskrivelse av rollen. Group - gruppe Representerer en gruppe med brukere. Grupper blir brukt til å styre tilgang til skjemaer. Det er mulig å gi brukere rettigheter som gruppeadministratorer (ROLE_GROUPADMIN) slik at de kan gis tilgang til å opprette skjemaer i en gruppe. Det er også mulig å legge til brukere som medlemmer i gruppen slik at de har tilgang til skjemaer med begrenset tilgang (restricted). En gruppe kan ha ingen eller flere skjemaer. name String Navn på gruppen. Dette feltet er påkrevd. description String Beskrivelse av gruppen. 17

18 Controllere AuthorityController Tar seg av oppretting og administrasjon av roller. CaptchaController Brukt til å generere captcha bilder. ChartController Brukt til å generere chart bilder til rapporter. CsvContoller Brukt til å eksportere rapporter av skjema til CSV format. FlashChartControllere Brukt til å generere flash charts til rapporter. FormController Tar seg av oppretting og administrasjon av skjema. GroupController Tar seg av oppretting og administrasjon av grupper. LoginController Lar en bruker logge inn i systemet. LogoutController Lar en bruker logge ut av systemet. QuestionController Tar seg av oppretting og administrasjon av spørsmål på skjema. RegisterController Brukes når brukere skal registrere seg selv på siden. ReportController Brukes til å vise rapporter av svar til eiere. ResultController Tar seg av oppretting og administrasjon av resultat for skjema. SurveyController Tar seg av gjennomføringen av undersøkelser. UserController Lar administratorer registrere brukere. 18

19 Views - Groovy Server Pages Layouts Layouts ligger i layouts/ i view-mappen. De to layoutene systemet definerer er main og admin, der admin brukes for sider i administrasjonsdelen og main brukes på alle andre sider. Templates Templates er deler av sider som kan inkluderes i andre views. De kan også brukes direkte i kontrolleren. Templates er lagret i templates/ i view-mappen. Liste over templates: adminmenu chartreport flashreport htmlreport Inneholder administratormenyen og inkluderes på sider som bruker adminoppsettet. Brukt til å inkludere grafer på sidene ReportController genererer. Brukt til å inkludere Flashgrafer på sidene ReportController genererer. Brukt til å inkludere HTML-rapporter på sidene ReportController genererer. Tagbiblioteker Det er ett innegygget tagbibliotek i Grails. Dette bygger på GSP (Groovy Server Pages), men er kraftig bearbeidet til å stemme bedre overens med resten av Grails. Utover dette biblioteket har vi opprettet to egne tagbibliotek. JavaScriptTagLib JavaScriptTagLib brukes til å generere Javascript dynamisk. Det er definert én tag i dette biblioteket: <g:questionjavascript formtype="${question.form.type}"/> Denne taggen brukes til å opprette Javascriptet som deretter brukes til dynamisk oppretting av alternativer i skjemaene for oppretting og endring av spørsmål. formtype må være gitt og må være satt til skjematypen for skjemaet spørsmålet opprettes i. MenuTagLib MenuTagLib brukes til å generere dynamiske menyer. Det er definert én tag i dette biblioteket: <g:mainmenu id="menu_main" admin="${true}"/> Denne taggen vil sjekke etter innloggede brukere og generere menyen etter det. id angir hvilken menytype som skal brukes i CSS. admin skal være true om taggen kalles fra adminlayouten. 19

20 Serviceklasser En serviceklasse inneholder funksjonalitet som må være tilgjengelig utenfor en kontroller. Det er to hovedgrunner til at funksjonalitet trekkes ut fra en controller. For det første kan logikken være for komplisert til å skrives direkte inn i en kontroller. For det andre kan l være metoder som brukes ofte. Eksempler kan være tilgangskontroll eller kompliserte forespørsler til databasen. Grails vil automatisk opprette en referanse til en instans av en service om det deklareres en klassevariabel med samme navn som servicen: 1 class FormController 2 { 3 def formservice 4 } Vanligvis er services singletons og det kan derfor ikke lagres noe tilstand i disse. Det er mulig å gjøre om dette slik at det opprettes en instans av servicen på for eksempel hver forespørsel, men vi har valgt å la alle våre services forbli singletons. Under følger en beskrivelse av metodene i servicene vi har definert. FormService public boolean checkformadminaccess(form form) Sjekker om brukeren som er innlogget har tilgang til skjemaet form som administrator. Returnerer false om dette ikke er tilfelle. public boolean checkformuseraccess(form form) Sjekker om brukeren som er innlogget har tilgang til skjemaet form som bruker. Returnerer false om dette ikke er tilfelle. public void clonetoform(form from, Form to) Kopierer skjemaet gitt i from til et nytt skjema to. Dette vil kopiere alle spørsmål, alternativer og resultat til det andre skjemaet. public void deletereplies(form form) Sletter alle svar i skjemaet form. 20

21 QuestionService public boolean savequestion(question question, GrailsParameterMap options, List optionlist, boolean insert = true) Lagrer spørsmålet question med alternativene gitt i options hvis det ikke er valideringsfeil. Hvis valideringen ikke går bra, vil optionlist bli fylt med de alterativene som var gyldige. Om insert er true, vil metoden utføre en insert-forespørsel. Om den er false vil en update-forespørsel bli sendt. Returnerer true om alt gikk bra. private boolean createoptionlist(list optionlist, Question question, GrailsParameterMap options) Oppretter en liste med gyldige alternativer for question, basert på input-parameterne i options. De gyldige alternativene blir fylt inn i optionlist. Om alle alternativene var gyldige, returneres true. Denne metoden blir kalt av savequestion(). private void saveoptions(list options, Question question) Lagrer alle alternativene i options for spørsmålet question. Denne metoden blir kalt av savequestion(). Et unntak blir kastet om lagringen feilet. public int updatepositions(form form = null, int start, boolean insert) Oppdaterer alle posisjoner for spørsmålene i skjemaet form fra posisjonen start. Om insert er true, vil posisjonene økes med en. Om den er false vil posisjonene minkes med en. Returnerer posisjonen spørsmålet burde lagres på om insert er true. SurveyService public List getavailablesurveys() Henter ut alle skjemaer som en innlogget bruker har tilgang til. public List getsurveysinprogress() Henter ut alle påbegynte skjemaer som hører til brukeren som er innlogget. public Reply setupreply(string form_id, String reply_id) Setter opp en ny besvarelse til et skjema eller initialiserer en allerede påbegynt besvarelse. Dette avhenger av om form_id eller reply_id er gitt. Om begge er gitt, vil en ny besvarelse bli satt opp. public Map setuppage(reply reply, int page, Map params) Henter siden med sidenummer page i besvarelsen reply. params inneholder returnerte parametere fra forrige side og kan være tom. Denne metoden vil lagre svarene på spørsmålene på forrige side om de eksisterer. Returnerer en ny model som sendes direkte til viewet. 21

22 private List getquestions(form form, int page) Henter alle spørsmål på sidenummer page i skjemaet form. Denne metoden blir kalt fra setuppage(). 1 private void savechoices(map inputs, String question, Reply reply) 2 private void savechoices(map inputs, String[] questions, Reply reply) Lagrer svarene til spørsmålene der ID-en er i questions og svaret er i inputs for besvarelsen reply. Denne metoden blir kalt fra setuppage(). 1 private List createchoices(string input, Question question, Reply reply) 2 private List createchoices(string[] input, Question question, Reply reply) Oppretter Choice-objekter for ID-ene eller verdiene til valg for spørsmålet question i besvarelsen reply. Denne metoden blir kalt fra savechoices(). Returnerer en liste med Choice-objekter. private void savechoicestodatabase(reply reply, Map choices) Lagrer alle valg gitt i choices for besvarelsen reply. Denne metoden blir kalt fra savechoices(). Kaster et unntak om lagringen ikke ble fullført. public Map completereply(reply reply, Map params) Denne metoden fungerer på samme måten som setuppage(), men vil i tillegg validere hele skjemaet og lukke besvarelsen om valideringen gikk bra. Hvis feil oppdages i valideringen, vil den returnere en model til siden feilen var på slik at kontrolleren enkelt kan vise siden med feil. Om besvarelsen gikk bra, vil den returnere et tomt map. public int gettotalpages(form form) Returnerer hvor mange sider det er i skjemaet form. public Map getchoicesforpage(reply reply, int page) Henter alle valg som er lagret for sidenummeret page i besvarelsen reply. public boolean ispagecomplete(reply reply, int page, List errors) Sjekker om siden med sidenummer page i besvarelsen reply er gyldig. errors er en tom liste som sendes fra kallende metode til denne metoden. Om feil oppdages vil errors bli fylt inn med ID-en til de spørsmålene hvor feil ble oppdaget. Om valideringen gikk bra vil true bli returnert. public Result getresult(reply reply) Henter utfallet knyttet til en gitt besvarelse. 22

23 GroupService public boolean checkgroupadminaccess(group group) Sjekker om brukeren som er innlogget har tilgang til gruppen group som administrator. Returnerer false om dette ikke er tilfelle. public boolean checkgroupuseraccess(group group) Sjekker om brukeren som er innlogget har tilgang til gruppen group som bruker. Returnerer false om dette ikke er tilfelle. public List getavailablegroups() Henter en liste over alle grupper brukeren som er innlogget har tilgang til. public List getavailablegroupadmins(group group) Henter en liste over alle tilgjengelige brukere som er gruppeadministratorer og som ikke allerede er medlem i gruppen group. public List getavailablegroupmembers(group group) Henter en liste over alle tilgjengelige brukere som ikke allerede er medlem i gruppen group. UserService public User getloggedinuser() Returnerer brukeren som er logget inn eller null om det ikke er en innlogget bruker. 23

24 Autentisering Autentiseringssystemet er basert på en innpluggingsmodul til Grails for Spring Security. Dette gjør at mange av de kritiske funksjonene i et slikt system allerede er implementert for oss, og dette fører igjen til bedre sikkerhet. Spring Security gjør at det også blir enklere å legge til flere former for autentisering på et senere tidspunkt, som for eksempel OpenID og LDAP. Systemet slik det er nå støtter kun vanlig HTTP-autentisering. Diagram over hvilke kontrollere og services som er inkludert i autentiseringssystemet og hvordan de henger sammen: Tilgangskontroll i kontrollere I systemet finnes det to måter å sikre tilgangen til delsystemer på. Den ene er å bruke en 'annotation' på klasser eller metoder der tilgangen blir begrenset til en eller flere roller (Authorities). I eksempelet under vil kun brukere som har rollen ROLE_ADMIN ha tilgang til metodene i kontrolleren: 1 import org.codehaus.groovy.grails.plugins.springsecurity.secured 2 4 class FormController 5 { 6 tar en liste med navn på roller som argument, så det er mulig å spesifisere flere roller enkelt ved å liste dem opp. Denne måten å autentisere på er brukt som den overordnede tilgangskontrollen i systemet og gjør det enkelt å låse hele kontrollere. 24

25 Den andre måten å begrense tilgang på er å bruke metodene i formservice, userservice og groupservice. Dette gir mer fleksibel kontroll enn med annotations og brukes i kontrollere som skal være tilgjengelig for flere brukergrupper. I eksempelet under sjekker vi om brukeren har adminstratortilgang til skjemaet kontrolleren har hentet ut: 1 def show = { 2 def form = Form.get(params.id) 3 4 if(!formservice.checkformadminaccess(form)) 5 { 6 /* Ingen tilgang. */ 7 response.senderror(403) 8 return 9 } 10 return [form:form] 11 } Tilgangskontroll i views Til tilgangskontroll i views brukes spesielle GSP-tagger som følger med i Spring Security. Disse taggene kan også brukes til å hente ut informasjon om den brukeren som er innlogget. Innloggingsinformasjonen som vises på forsiden er implementert ved hjelp av disse taggene: <div id="login_menu"> 4 <g:isloggedin> 5 Logged in as <g:link controller="register"><g:loggedinuserinfo field="username"/></g:link>. 6 <g:link controller="logout">logout</g:link> 7 </g:isloggedin> 8 <g:isnotloggedin> 9 Not logged in. <g:link controller="login">login</g:link> or <g:link controller="register">register</g:link> 10 </g:isnotloggedin> 11 </div> Det er også mulig å begrense hvilke roller som kan se hva ved hjelp av tagger: <g:ifanygranted role="role_admin,role_groupadmin"> 4 <h3>survey administration</h3> 5 <ul> 6 <li><g:link controller="form" action="create"><g:message code="form.create"/></g:link></li> 7 <li><g:link controller="form"><g:message code="form.list"/></g:link></li> 8 <li><g:link controller="report"><g:message code="report.get"/></g:link></li> 9 </ul> 10 </g:ifanygranted> 11 25

26 12 <g:ifanygranted role="role_admin"> 13 <h3>user administration</h3> </g:ifanygranted> Registrering av brukere Registrering av brukere fra brukersiden blir utført av RegisterController. RegisterController vil vise et skjema for registrering av en ny bruker om det ikke er en gyldig bruker allerede logget inn. Om det er en gyldig bruker logget inn, vil den vise en oversikt over den brukerinformasjonen som er registrert. Det vil også være muligheter for brukeren å endre noe av denne informasjonen, som passord og ekte navn. UserController tillater mer avansert brukerhåndtering, som å liste opp alle brukere som er registrert og tildele dem roller. Denne kontrolleren er kun tilgjengelig for administratorer og er ment til brukeradministrering. Administratorer kan også registrere og slette brukere ved hjelp av denne kontrolleren. Innlogging og utlogging Innlogging og utlogging blir utført av autentiseringsfiltre til Spring Security. Dette gjør at utlogging for eksempel kan skrives så enkelt som: 1 def index = { 2 redirect(uri:'/j_spring_security_logout') 3 } Dette er den eneste metoden i LogoutController. For innlogging er det et eget skjema som tar brukernavn og passord som parametere og sender dem til innloggingsfilteret til Spring Security. Innlogging blir utført av LoginController. 26

27 Oppretting og redigering av skjema Spørreskjemaer blir opprettet av brukere med ROLE_ADMIN eller ROLE_GROUPADMIN som rolle. Dette betyr at kontrollerne som brukes er låst med annotation til disse to rollene. Nedenfor er en oversikt over kontrollere og services som brukes til skjemaopprettingen: Oppretting av skjema Oppretting av selve skjemaet blir håndtert av FormController. Siden et skjema ikke trenger å ha spørsmål når dette opprettes, blir det opprettet et tomt skjema som administratoren kan legge til spørsmål i senere. Et skjema som blir opprettet har published satt til false. Det må opprettes spørsmål i skjemaet før det kan publiseres. FormController følger standard CRUD-oppsett. Skjemaer kan være av forskjellige typer, som resulterer i forskjellig utseende på bildet for oppretting av spørsmål: survey test_simple test_complex Felt for poeng vises ikke i alternativer. Felt for poeng er byttet ut med en radioknapp for å velge om svaret er riktig eller ikke. Felt for poeng er en normal tekstboks som tar en double som verdi. 27

28 Kopiering av skjema Det finnes støtte i systemet for å kopiere innholdet i et skjema (Spørsmål, Alternativer og Resultater) til et nytt skjema. Først oppretter brukeren det nye skjemaet gjennom et eget kopieringsview. Når dette nye skjemaet er opprettet blir alle spørsmål, alternativer og resultater fra det opprinnelige skjemaet kopiert over til det nye skjemaet. Denne funksjonen er hovedsakelig ment for å kunne endre et skjema uten å miste svar, eller for å flytte et skjema til en annen gruppe. Oppretting av spørsmål Oppretting av spørsmål blir håndtert av QuestionController. Denne kontrolleren blir kalt av viewene til FormController og krever ID-en til et gyldig skjema som inputparameter til alle metoder. QuestionController inneholder bare metoder for oppretting, redigering og sletting av spørsmål. Metodene i QuestionController for oppretting og redigering håndterer ikke bare spørsmål, men også alternativer knyttet til et spørsmål, så det finnes ingen spesiell kontroller for alternativer. Det meste av logikken bak lagring av spørsmål ligger i QuestionService. Den ene grunnen til dette er at QuestionController håndterer både spørsmål og alternativer. Dette gjør at logikken blir for komplisert til å skrives rett i kontrolleren. En annen grunn er at det meste av koden deles av både oppretting og lagring. For å unngå at data blir lagret om noe går galt, kjøres logikken innenfor en transaksjon. Transaksjonen bygges opp av savequestion() i QuestionController. Beskrivelse av flyten i denne metoden: 1. Valider de generelle feltene i spørsmålet. Om valideringen går galt, settes returverdien til false. 2. Valider alternativer og bygg opp en liste over alle gyldige alternativer med createoptions(). Om valideringen avslører feil i en eller flere av alternativene, settes returverdien til false. 3. Om returverdien nå er true, utfør lagringsoperasjonene under. 1. Kall updatepositions() for å oppdatere posisjonen til alle spørsmål fra og med posisjonen hvor dette spørsmålet skal settes inn. Om dette går galt, kastes et unntak og transaksjonen avbrytes. 2. Prøv å lagre selve spørsmålet. Om dette går galt, kastes et unntak og transaksjonen avbrytes. 3. Prøv å lagre alternativene ved å sende med listen createoptions() returnerte til saveoptions(). Om dette går galt, kastes et unntak og transaksjonen avbrytes. 4. Returner returverdien. Returverdien vil nå angi om lagringen gikk bra. Hvis returverdien er false, vil kontrolleren vise skjemaet på nytt og bruke listen med alternativer returnert fra savequestion() til å markere hvilke felter som ble fylt inn feil. 28

29 Oppdatering av spørsmål Oppdatering av spørsmål følger samme flyt som oppretting, men før selve lagringen begynner slettes alle alternativer som allerede er bundet til spørsmålet. Dette er for å gjøre lagringsprosessen mindre komplisert. Et problem med dette er at det ikke må være bundet noen valg til alternativene. Dette løses ved å slette alle besvarelser som er gjort til skjemaet før endringer utføres. Sletting av spørsmål Når et spørsmål slettes, vil updatepositions() i QuestionService kalles for å oppdatere posisjonene til spørsmålene som eventuelt er etter spørsmålet som slettes i rekkefølgen. Dette må gjøres fordi den resterende logikken for spørsmål krever at posisjonene til spørsmålene er i rekkefølge. Oppdatering av posisjonene og sletting av spørsmålet må kalles i samme transaksjon. 29

30 Utfylling av skjema Utfylling av skjemaer blir håndtert av SurveyController, men det meste av logikken ligger i SurveyService. Nedenfor er et diagram som viser kontrollere og services som blir brukt til utfylling av skjemaer. Oppsett av besvarelse Når en spørreundersøkelse startes, vil init i SurveyController kalles. Denne metoden vil videre kalle setupreply() i SurveyService, som tar enten reply_id eller form_id som argument. Hvis reply_id er gitt, vil metoden hente ut besvarelsen som tilhører denne ID-en og sette opp systemet for fortsettelse av en uferdig besvarelse. Om form_id er satt, vil den hente ut det skjemaet som er knyttet til ID-en i form_id og sette opp en ny besvarelse knyttet til dette skjemaet. Om en bruker er logget inn, vil også besvarelsen bindes til denne brukeren. setupreply() returnerer null om det ikke kunne settes opp en besvarelse på grunn av mangel på tilgang eller andre feil. Henting av en side med spørsmål I systemet blir alle spørsmål hentet som sider. En side med spørsmål kan inneholde et eller flere spørsmål. Metodene next og prev i SurveyController brukes til å navigere mellom sider i skjemaet. Disse kaller igjen setuppage() i SurveyService som igjen henter ut den riktige siden og returnerer det som skal til for å sette opp viewet som kontrolleren skal vise. 30

31 Flyten i setuppage() er som følger: 1. Alle valg som ble gjort på forrige side blir lagret. Det utføres ingen validering her. 2. Antall sider hentes ut ved å kalle gettotalpages(). 3. Om sidenummeret som er skal hentes er høyere enn antall sider blir sidenummeret satt til 1. Om det er mindre enn 1 blir sidenummeret satt til det høyeste sidetallet (antall sider). Dette gjør at kontrolleren ikke trenger å sjekke om sidenummeret er riktig. 4. Listen med spørsmål til det sidenummeret som er satt blir hentet med et kall til getquestions(). 5. Svarene som eventuelt er lagret for denne siden hentes med getchoicesforpage(). Oppbygningen av denne metoden er så fleksibel at det gir brukeren full frihet når det gjelder rekkefølgen svarene blir fylt inn på. Grunnen til at validering ikke utføres her er for å unngå at fleksibiliteten ødelegges ved at brukeren blir tvunget til å svare på et spørsmål for å gå videre. Innlevering av et skjema Når et skjema skal leveres, kalles submit i SurveyController. Dette gjøres via et kall til completereply() i SurveyService. completereply() vil utføre validering på skjemaet for å sjekke om alle påkrevde spørsmål er besvart. Flyten i completereply() er som følger: 1. Alle valg som ble gjort på forrige side blir lagret. Det utføres ingen validering her. 2. Antall sider hentes ut ved å kalle gettotalpages(). 3. Itererer over alle sider: 1. Sjekk om siden er riktig fylt ut ved å kalle ispagecomplete(). 2. Om den ikke er fylt inn riktig, returneres en model for å vise den uriktige siden. Dette gjør at den første siden som ikke er ferdig utfylt enkelt kan vises til brukeren. 4. Om alle sider var riktig fylt ut, settes completed til true i besvarelsen og den lagres. 31

32 Henting av rapporter Henting av rapporter håndteres av ReportController. Det meste av logikken for henting av data til rapportene ligger i ReportService. CsvController, FlashChartController og ChartController håndterer de forskjellige formatene på rapportene. Nedenfor er et diagram som viser kontrollere og services som blir brukt til henting av rapporter. CsvController bruker Javabiblioteket OpenCSV til genering av CSV-filer. FlashChartController bruker Grails-modulen til Open Flash Chart og ChartController bruker Javabiblioteket JFreeChart til generering av grafer. Henting av data til rapportene Data til rapportene blir hentet av makereportlist() i ReportService. Denne metoden vil returnere en liste av alternativene og hvor mange svar som ble gitt for disse for spørsmålet som blir sendt inn. Dette er den eneste formen for statistikk som kan hentes ut av rapportsystemet. Listen som _makereportlist returnerer følger dette formatet: [ ] [Question, Option, <antall valg>, <prosent av totalt antall valg>], [Question, Option, <antall valg>, <prosent av totalt antall valg>],... [Question, Option, <antall valg>, <prosent av totalt antall valg>] På alle spørsmålstyper som bruker alternativer, bortsett fra checkbox, vil det være med et siste valg i listen som representerer hvor mange som ikke svarte på spørsmålet. Om 32

33 spørsmålstypen er textarea eller textfield, vil det returneres en liste med ett element som angir hvor mange som svarte på spørsmålet. Rendring av rapporter Metoden get i ReportController håndterer henting av rapporter. Denne metoden vil kalle makereportlist(), som er beskrevet ovenfor, for hvert spørsmål brukeren har valgt å hente rapporter for. Ut fra rapportformatet som brukeren har valgt vil den da sende resultatet fra makereportlist() til riktig kontroller. HTML-rapporter er den enkleste formen for rapport og koden for å generere denne ligger rett i get: 1 def get = { switch(params.type) 5 { 6 case "html": 7 params.question.each() 8 { 9 def question = Question.get(it) 10 def reportlist = reportservice.makereportlist(question, false, false) 11 results += g.render(template:"/templates/htmlreport", model:[reportlist:reportlist]) 12 } 13 break; } En template vil rendres med dataene som ble returnert fra makereportlist() og resultatet legges i variabelen results. Denne variabelen vil videre bli sendt til viewet og bli printet ut der: 1 <div class="body"> 2 <h1>results</h1> 3 ${results} 4 </div> Dette krever at HTML-encoding av variabler i views er slått av for dette viewet. For de rapporttypene som har egne kontrollere for generering av grafene, vil denne kontrolleren kalles ved hjelp av parametere satt i en template. I kontrolleren vil templaten rendres og returneres til viewet på samme måte som ovenfor. 1 def get = { case "chart": 5 params.question.each() 6 { 33

34 7 results += g.render(template:"/templates/chartreport", model:[id:it, type:params.chart_type]) 8 } 9 break; } Templaten som rendres ser slik ut: 1 <div class="list"> 2 <img src="/prosjekt/chart/${type}/${id}"/> 3 </div> Om rapporttypen er HTML, vil det for spørsmål med textfield eller textarea som type vises en knapp som linker til et eget view som viser alle svarene som er gitt til disse spørsmålene. 34

35 Tester Testene er integrasjonstester og sjekker utfall av alle handlinger som en controllere kan utføre. Det kontrolleres om de riktige dataene returneres. Dersom feil oppstår sjekkes om de rikige feilkodene returneres. Siden det ikke er innlogget noen bruker i testene, mockes metodekallene som normalt skal teste om en bruker har tilgang. Det å mocke en klasse består i å bytte den ut med en annen som returner forhåndsdefinererte verdier på metodekall som brukes: 1 def mockgroupservice = mockfor(groupservice) 2 mockgroupservice.demand.checkgroupadminaccess(group) { group -> return true } 3 mockgroupservice.demand.getavailablegroups() { return Group.list() } 4 controller.groupservice = mockgroupservice.createmock() Her opprettes først et mock-instans for GroupService. Deretter definereres at det første kallet som mottas skal være checkgroupadminaccess(), og dette skal returnere true. Senere vil bli utført et kall på getavailablegroups(), og dette returnerer en liste over alle grupper. Til slutt opprettes mocken, og klassen som skal mockes byttes ut med mock-objektet. Her er et lite utsnitt av ResultControllerTests: 1 void testcreate() 2 { 3 def controller = new ResultController() 4 5 def mockformservice = mockfor(formservice) 6 mockformservice.demand.checkformadminaccess(form) {form -> return true } 7 controller.formservice = mockformservice.createmock() 8 9 def model = controller.create() 10 assertequals 200, controller.response.getstatus() assert model 13 assert model.result 14 } Siden sikkerheten mockes, er det lett å teste samme view uten tilgang: 1 void testillegalusercreate() 2 { 3 def controller = new ResultController() 4 5 def mockformservice = mockfor(formservice) 6 mockformservice.demand.checkformadminaccess(form) {form -> return false } 7 controller.formservice = mockformservice.createmock() 8 35

36 9 def model = controller.create() 10 assertequals 403, controller.response.getstatus() assert!model 13 } 36

37 Vedlegg A -- Klassediagram 37

38 Vedlegg B -- ER-diagram 38