Projectteam 6 Faculteit Natuur en Techniek Hogeschool Utrecht Projectleider: Hans Allis, hans.allis@student.hu.nl Technisch ontwerp Project "Web Essentials" 05 juni 2009 Versie 3.8.0 Teamleden: Armin Ghassemi Gerben Strien Hans Allis Max Gramsma Peter Mols Wesley van Vliet
Pagina 1 i. Inhoudsopgave i. Inhoudsopgave... 1 ii. Versiebeheer... 2 Inleiding... 3 1. Software architectuur... 4 2. Use case realisatie... 6 1e cyclus...6 2e cyclus...6 3e cyclus...6 4e cyclus...7 5e cyclus...7 6e cyclus...7 3. Ontwerpbeslissingen... 8 Mapstructuur...8 Architectuur...8 MVC...8 Layout...8 Menu...8 Centrale gegevens...9 Meldingen...9 Aparte functionaliteit...9 Mail merge...9 Sugar gerelateerde functies...9 Inloggen...9 Relaties...9 Rollen per persoon...9 Helper functies... 10 autoload functie... 10 Belangrijke technologiën... 10 Ajax... 10 Active Directory en LDAP... 10 Workarounds... 10 Inloggen bij elke functie(tijdelijk)... 10 4. SugarCRM Modules...11 5. Klassendiagram...13 6. Sequencediagrammen...16 7.Code toelichting...28 Proxy object... 28
Pagina 2 ii. Versiebeheer Auteur Reden van verandering Datum Versienummer Gerben Strien Max Gramsma Start document H1, H2 toegevoegd Hoofdstuk ontwerpbeslissingen + ERD toegevoegd. Gerben Strien - H1 SugarCRM instellingen gewijzigd - H3 ontwerpbeslissingen gewijzigd - H2 hernoemt naar H5 - H2 Beschrijving realisatie toegevoegd - 2 e iteratie toegevoegd Gerben Strien - Inleiding toegevoegd - Alle hoofdstukken gedeeltelijk gewijzigd. - Use case van 2 e iteratie naar 3 e verplaatst - H5 klassendiagram toegevoegd Max Gramsma - Hoofdstuk 4 aangepast. - Kleine wijzigingen. Gerben Strien - Hoofdstuk 2, 3 & 6 aangepast. - Kleine wijzigingen. Hans Allis, Max Gramsma - Documentatie derde cyclus afgerond. Gerben Strien - Hoofdstuk 3 aangevuld. - Hoofdstuk 5 klassendiagram aangepast. 9 maart 2009 1.0.0 11 maart 2009 1.1.0 18 maart 2009 2.0.0 2 april 2009 2.1.0 15 april 2009 2.2.0 18 april 2009 2.3.0 20 april 2009 2.4.0 28 april 2009 2.5.0 Hans Allis - Documentatie vierde cyclus 30 april 2009 3.0.0 Max Gramsma - Hoofdstuk 4 bijgewerkt - Kleine toevoegingen 07 mei 2009 3.1.0 Max Gramsma - Documentatie Cyclus 5; H3 13 mei 2009 3.2.0 Max Gramsma - Aanpassingen/toevoegingen adhv beoordeling 2. 16 mei 2009 3.3.0 Gerben Strien - Overzichtsplaatje toegevoegd 29 mei 2009 3.4.0 Max Gramsma - Cyclus 5 afronding 02 juni 2009 3.5.0 Max Gramsma - Cyclus 6 toevoegingen 03 juni 2009 3.6.0 Max Gramsma - Cyclus 6 toevoegingen - Sequencediagrammen Gerben Strien - Klassendiagram aangepast - H1 aangepast Tabel 1: Gegevens over versies van dit document. 04 juni 2009 3.7.0 05 juni 2009 3.8.0
Pagina 3 Inleiding In dit verslag wordt de nodige technische informatie voor ons stage- en afstudeersysteem beschreven zodoende dat deze reproduceerbaar is door derden. Het stage- en afstudeersysteem bestaat uit twee delen namelijk de front-end die bestaat uit een PHP website en een back-end die bestaat uit SugarCRM. In dit verslag komen beide delen aan bod. In de volgende paragraaf is de inhoud van dit document per hoofdstuk kort beschreven. Als eerste wordt de Software architectuur beschreven waarin de gebruikte software en de daarbij horende versienummers staan. En ook de instellingen van SugarCRM de back-end worden hier beschreven. In het volgende hoofdstuk worden de use cases van het Functioneel Ontwerp versie 6.0.0 erbij gehaald. Hiervan wordt beschreven hoe deze worden gerealiseerd qua programmeren. In het hoofdstuk daarna worden de ontwerpbeslissingen beschreven die wij hebben genomen. In hoofdstuk vier worden de modules beschreven die wij hebben aangepast in SugarCRM. In hoofdstuk 5 volgt een klassendiagram van de door ons ontwikkelde front-end. In het laatste hoofdstuk worden belangrijke code segmenten beschreven.
Pagina 4 1. Software architectuur In dit hoofdstuk wordt de software architectuur beschreven. Onze applicatie zal bestaan uit twee delen. Als eerste de front-end. Deze bestaat uit een website waar de gebruiker via een netwerk aangesloten PC bij kan. Als tweede de back-end, SugarCRM, een open-source CRM software pakket. Koppeling De front-end wordt via SOAP gekoppeld aan de back-end. SOAP is de taal om webservices mee aan te spreken. SugarCRM heeft een scala aan functies beschikbaar gesteld via het WSDL bestand. Hierdoor is het erg gemakkelijk om de verschillende functies te gebruiken via de front-end. Nu-SOAP library De Nu-SOAP library bevat een aantal handige PHP klassen die ontwikkelaars kunnen gebruiken om web services aan te roepen die gebruik maken van SOAP 1.1, WSDL 1.1 en HTTP 1.0/1.1. Wij maken gebruik van deze library om de functies van SugarCRM aan te roepen in onze front-end. Wij gebruiken versie 0.7.2 voor de Nu-SOAP library. SugarCRM WSDL De verschillende SugarCRM functies zijn beschikbaar gemaakt via een WSDL bestand. Deze is te vinden via het volgende adres http://domeinnaam/sugarcrm/soap.php?wsdl. Een lijst van de functies en bijbehorende informatie is te vinden op http://domeinnaam/sugarcrm/soap.php. SugarCRM instellingen Gebruikerstype Bij het aanmaken van een nieuwe gebruiker dient er een type gebruiker opgegeven te worden. Hiervoor is een gebruikerstype tekstveld toegevoegd aan de al bestaande Users module in SugarCRM. Eigen package Er is een eigen package aangemaakt met de naam "Internship". Daarin is een tweetal modules aangemaakt, namelijk "Student" en "Internship". Er zijn Engelse namen gebruikt, omdat de namen van de eigen modules van SugarCRM ook Engelse namen dragen. De eigen modules worden gebruikt om respectievelijk de student- en de stagegegevens in op te slaan. De modules "Contacts" en "Accounts" worden gebruikt om gegevens van respectievelijk bedrijfsbegeleiders en bedrijven op te slaan. In de "Users"-module worden tenslotte de gegevens van docenten en HU-medewerkers opgeslagen. Relaties Er zijn relaties toegevoegd aan SugarCRM om de relaties op te kunnen slaan, die tussen de verschillende modules bestaan. Deze relaties zijn zowel tussen de eigen modules als de eigen modules van SugarCRM gelegd. Versienummers Doordat software constant in ontwikkeling is en er regelmatig nieuwe versies worden uitgegeven, is hieronder een overzicht te vinden van de versies van de gebruikte applicaties. Naam Versienummer CSS 2.1 MySQL 5.0.67 Nu-SOAP library 0.7.2 PHP 5.2.9 phpunit 3.3.10 Server OS FreeBSD 7.0-release-p11 SOAP 1.1 SugarCRM 5.2.0e WSDL 1.1 xhtml 1.1 Tabel 2: Gegevens over de versienummers.
Pagina 5 Overzicht Hieronder is een overzicht te vinden van alle componenten in ons systeem en hoe deze samenwerken. Test1.nl Dit is de server waar ons systeem op draait. Deze is via het internet te bereiken op het adres www.test1.nl De verschillende cyclussen zijn via subdomein te bereiken. Bijv. cyclus1.test1.nl Active Directory Wij gebruiken de Active Directory van de Hogeschool Utrecht om gebruikergegevens over studenten en medewerkers op te halen. Webmail De webmail servers van de Hogeschool Utrecht gebruiken we voor het authenticeren van gebruikers. NuSoap library Deze library is gebruikt in ons systeem om SOAP calls te maken naar SugarCRM. Fastmode Fastmode zorgt zoals de naam al doet vermoeden voor betere prestaties bij bv. het ophalen van gegevens. Deze omzeilt SugarCRM door direct de database aan te spreken. Fastmode is optioneel en kan uitgezet worden door een variable genaamd fastmode op false te zetten.
Pagina 6 2. Use case realisatie In het functioneel ontwerp zijn verschillende use cases beschreven per iteratie. Die worden er in dit hoofdstuk weer bijgehaald en vervolgens wordt toegelicht hoe deze zijn geïmplementeerd. Per use case is aangegeven welke modules(mapnaam) en klassen er worden gebruikt. Aangezien alle klassen een uitbreiding zijn op de klasse Model, zal de klasse Model altijd gebruikt worden. 1e cyclus Inloggen Als eerste zal gecontroleerd worden of de gegevens die de gebruiker in de gebruikersnaam en wachtwoord velden heeft ingevoerd overeenkomen met die uit de database van SugarCRM. Wanneer de gegevens volgens SugarCRM geen geldige combinatie vormen, dan wordt het webmailsysteem van de Hogeschool gebruikt om de inloggegevens te verifiëren. Als de gegevens volgens SugarCRM of het webmailsysteem correct zijn, dan wordt de gebruikersnaam in de sessie opgeslagen. Indien de logingegevens door SugarCRM goedgekeurd worden, dan wordt in de sessie ook het sessionid van SugarCRM opgegeven. Modules: Inloggen Klassen: Medewerker, Student Gebruikers toevoegen (1/2) Dit is stap één van het gebruikers toevoegen waarbij de bestaande SugarCRM users - of "contacts"-module of de zelfgemaakte "student"-module wordt gebruikt om de gegevens in op te slaan. In deze stap wordt enkel het gebruikerstype gekozen, waarna de gebruiker naar stap 2 gestuurd wordt waar de bijbehorende velden worden getoond. Modules: Medewerker, Student Klassen: Medewerker, Student 2e cyclus Gebruikers toevoegen (2/2) In deze cyclus wordt de tweede stap gerealiseerd voor het toevoegen van gebruikers. Hierbij wordt aan de hand van de gebruikerstype keuze uit stap één de velden getoond die bij die keuze horen. De verplichte velden zullen in ieder geval server-side worden gecontroleerd. Modules: Medewerker, Student Klassen: Medewerker, Student Stagebedrijven toevoegen Hier zal een apart module voor worden aangemaakt in SugarCRM, eventueel kan er een bestaande module worden aangepast. De verplichte velden zullen in ieder geval server-side worden gecontroleerd. Modules: Stage Klassen: Stage 3e cyclus Koppelen studenten / docent begeleiders / bedrijfsbegeleiders De stage module zal met relaties binnen SugarCRM gekoppeld worden aan de verschillende modules voor studenten en begeleiders. Vervolgens zal nadat de gebruiker de benodigde gegevens heeft gekozen de koppeling worden opgeslagen door de verschillende ID s van de bijbehorende records via SugarCRM op te slaan in de database. Module: Stage Klassen: Stage, Medewerker, Student Standaardiseren van Model- en Controllerlaag Om onderhoudbaarheid en uitbreidbaarheid te vereenvoudigen worden de klassen in de Model- en de Controllerlaag zoveel mogelijk gestandaardiseerd. Aangezien gebruik gemaakt wordt van een objectgeoriënteerde taal, zal met behulp van overerving de herbruikbare code uit beide lagen in twee basisklassen geplaatst worden. De specifieke klassen erven deze eigenschappen en methodes over van de basisklassen.
Pagina 7 Module: Allemaal Klassen: Allemaal 4e cyclus Bewerken studenten / docenten / bedrijfsbegeleiders en stages In de tweede iteratie is het mogelijk gemaakt om de verschillende soorten gegevens op te slaan. In de vierde cyclus wordt het mogelijk gemaakt om vanuit een lijst een specifiek record te selecteren en de gegevens daarvan te wijzigen en op te slaan. De verplichte velden zullen in ieder geval server-side worden gecontroleerd. Module: Stage, Medewerker, Student Klassen: Stage, Medewerker, Student, Bedrijfsbegeleider 5e cyclus Overzicht studenten per docentbegeleider De studenten zullen in een tabel worden weergeven. Deze tabel geeft de mogelijkheid om een student te selecteren en vervolgens te bewerken. Module: Student, Medewerker Klassen: Student, Medewerker Menu structuur per gebruikerstype Bij het inloggen zal er via sugarcrm gecontroleerd worden om wat voor type gebruiker het gaat. Het gebruikerstype zal worden opgeslagen in een sessie-variabele. Aan de hand hiervan worden alleen de menu s weergegeven die van toepassing zijn voor de gebruiker. Module: Rol Klassen: Rol 6e cyclus Notities koppelen aan stage Notities komen te staan in de SugarCRM module Notes. Deze module heeft een relatie met Internship zodat de notities gekoppeld zitten aan een stage. Het ophalen en opslaan van notities wordt op dezelfde manier gerealiseerd als het koppelen van modules in cyclus 3. Module: Stage, Notitie Klassen: Stage Contact opnemen met groepen Er zal een csv-bestand gegenereerd worden waarin alle studenten staan die de gebruiker heeft geselecteerd via de website. Het csv-bestand kan door de gebruiker in Microsoft Word worden gebruikt om de brieven te genereren. Module: Student Klassen: Student
Pagina 8 3. Ontwerpbeslissingen Er zijn verschillende ontwerpbeslissingen genomen voor en tijdens het ontwikkelen. Deze worden hier beschreven. Mapstructuur De mapstructuur zal er uiteindelijk als volgt uit komen te zien: sugar/ cache/ Modules/ Activedirectory/ View/ Bedrijf/ View/ Bedrijfsbegeleider/ View/ Homes/ View/ Inloggen/ View/ Medewerker/ View/ Stage/ View/ Student/ View/ / View/ Libs/ nusoap/ Klassen/ Functies/ Tests/ css/ images/ Op deze manier blijft alles duidelijk gescheiden van elkaar. Alle verschillende modules krijgen een eigen map waarin de controllerklasse staat met de naam Controller.php. Doordat het lastig is en heel veel bestanden oplevert wanneer een enkele klasse over verschillende bestanden wordt verdeeld is hiervoor gekozen. Per module is een map "View" aanwezig, waarin per methode van de controller een bestand staat dat de benodigde HTML weergeeft aan de gebruiker. Architectuur MVC Wij hebben er voor gekozen om het Model-View-Controller ontwerppatroon toe te passen. Dit zal de leesbaarheid en herbruikbaarheid van de code bevorderen. De view en controller bestanden zijn binnen de modules geplaatst in de gelijknamige mappen. De model bestanden zijn geschreven in de vorm van klassen en zijn in de Klassen map geplaatst. Layout Ook de opmaak is gescheiden deze is te vinden in het css mapje. De layout voor het geheel wordt in het bestand layout.php aangegeven. Menu Ook het menu is in een apart bestand opgenomen omdat deze op elke pagina zichtbaar is. Op deze manier hoeven we maar één bestand daarvoor te gebruiken en aan te passen indien nodig.
Pagina 9 Centrale gegevens Al de gebruiker gegevens en de daarbij horende informatie wordt opgeslagen in bestanden die gerelateerd zijn aan de klasse. Er kan bv. een student worden aangemaakt via onze appliatie hiervoor is dan ook een apart bestand te vinden genaamd student. Dit bestand bevat een array met alle informatie die daarbij hoort. Zo hebben we dus een centrale plek voor alle informatie mbt. één object voor de front-end. Wat inhoud dat we alleen hier wijzigingen hoeven aan te brengen die vervolgens voor de gehele front-end gelden. Meldingen Verschillende meldingen zoals foutmeldingen worden in een array gestopt zodat die later netjes één voor één getoond kunnen worden op het scherm. Foutmeldingen worden in een andere array gestopt dan de rest van de meldingen. Omdat er dan ook gecontroleerd kan worden of de foutmeldingen array leeg is. Als die leeg is dan zijn er dus geen fouten opgetreden. Aparte functionaliteit Mail merge Voor stagecoördinatoren moet het mogelijk zijn om een mail merge te kunnen uitvoeren. Dit is mogelijk met de Word Plugin voor SugarCRM, echter ondersteund deze plugin maar een beperkt aan modules waaronder niet de module die wij gebruiken voor studenten. Er zijn twee mogelijkheden waartussen een keuze gemaakt moet worden. Beide mogelijkheden gaan vooraf met de mogelijkheid om aan te geven welke studenten er moeten worden gebruikt. CSV/Handmatig Er wordt door middel van php een csv-bestand gegenereerd. De gebruiker kan dit bestand downloaden, en het vervolgens in Microsoft Word als gegevensbron gebruiken om het te koppelen aan een brief-template. Voordeel: Relatief makkelijk te maken. Nadeel: De gebruiker moet zelf het csv-bestand koppelen aan de brief-template. PDF Er wordt door middel van php pdf-bestanden gegenereerd. De brief-template staat vast in de code of er wordt een editor geplaatst op de website. Voordeel: De gebruiker hoeft zelf niets aan de brief te doen. Nadelen: Een eventuele template-editor maken kost meer tijd. De gegenereerde brieven kunnen niet worden aangepast. Sugar gerelateerde functies Inloggen Door via een formulier de inloggegevens op te vangen kunnen deze doorgestuurd worden naar SugarCRM. Dit wordt gedaan door de inlogfunctie aan te roepen via SOAP. SugarCRM handelt het inloggen verder af. Er wordt nog wel een inlogobject aangemaakt via onze eigen Inloggen klasse waar gebruikersnaam, wachtwoord en sessie ID worden opgeslagen. Dit object wordt gebruikt om de eerdergenoemde gegevens op te roepen indien deze nodig zijn voor een SugarCRM functie aanroep. Relaties Relaties leggen we vast in de SugarCRM back-end. Deze worden via de functie get_related_ids in onze front-end opgehaald. Rollen per persoon Om in het systeem onderscheid te kunnen maken tussen een begeleidend docent, een student of bv. een stagecoördinator, moeten per account een rol kunnen worden toegekend. In SugarCRM is een systeem aanwezig om rollen te beheren en aan gebruikers te koppelen. Met behulp van de SOAP-interface kunnen deze rollen in ons systeem gebruikt worden om ook daar het onderscheid te kunnen maken. In SugarCRM wordt een drietal rollen toegevoegd. Dat zijn de volgende: - Stagecoordinator - Docent - Administratie Bij het inloggen in het stagesysteem als HU-medewerker worden vanuit SugarCRM de rollen voor dat account opgehaald. Indien een gebruiker meerdere rollen heeft, wordt de eerste rol aangehouden. De rol wordt als sessie-
variabele opgeslagen onder de naam rol. Indien wordt ingelogd als student, dan wordt automatisch de rol student toegekend. Referentie: http://www.sugarcrm.com/forums/showthread.php?t=47787&highlight=roles+soap Technisch ontwerp Pagina 10 Helper functies autoload functie Door gebruik te maken van PHP s autoload functie worden de betreffende klassen geladen die nodig zijn zonder dat deze expliciet in de code worden aangeroepen. PHP regelt nu dus zelf dat de benodigde klassen worden ingeladen indien deze nodig zijn. Belangrijke technologiën Ajax Wij maken gebruik van Ajax functies voor bijvoorbeeld de autocomplete functie. Deze toont suggesties aan de hand van gebruikersinput om bv. studentennamen te tonen. Hierbij maken wij gebruik van de het JavaScript framework Prototype in combinatie met script.aculo.us. Active Directory en LDAP Met behulp van het Lightweight Directory Access Protocol (LDAP) kunnen we Active Directory aanspreken om zo gegevens zoals studentnamen en nummers op te halen en te gebruiken in onze applicatie. Workarounds Inloggen bij elke functie(tijdelijk) Update: Dit probleem is opgelost. Op dit moment wordt er bij elke functie in de code opnieuw het SOAP object aangemaakt. Dit is een tijdelijke oplossing, de bedoeling was om dit object in de sessie te bewaren, maar dit werkt niet goed. Hier zal nog een betere oplossing voor worden bedacht, maar om nu toch door te kunnen gaan maken we het object elke keer opnieuw aan.
Pagina 11 4. SugarCRM Modules De volgende modules zijn toegevoegd of gewijzigd binnen SugarCRM. Deze tabellen zouden gebruikt kunnen worden om SugarCRM opnieuw klaar te maken voor gebruik. Dit gebeurt via de Studio en Module builder in het admin menu. Wij hebben onze klassen gekoppeld aan sommige SugarCRM modules. Deze worden hieronder opgenoemd. Er is ook vermeld of er iets binnen SugarCRM is gewijzigd voor die module. Klasse Module Wijzigingen in Sugar? Afspraak Meeting nee Bedrijf Accounts nee Bedrijfsbegeleider Contacts nee Medewerker Users nee Notities Notes nee Rol ACLRoles nee Stage intrn_internship eigen module Student intrn_student eigen module Internship Naam startdate enddate stageopdracht type Type Date Date TextArea DropDown Relaties: Many-to-Many met Student Many-to-One met Contacts One-to-Many met Calls One-to-Many met Meetings One-to-Many met Notes One-to-Many met Tasks One-to-Many met Activity Student Uitbreiding op Person Naam parent_name username zkverzekeraar zkpolisnummer ongverzekeraar ongpolisnummer repverzekeraar reppolisnummer waverzekeraar wapolisnummer opleiding Type Textfield Textfield Textfield Textfield Textfield Textfield Textfield Textfield Textfield Textfield DropDown Relaties: Many-to-Many met Internship.
Pagina 12 Naast de modules wordt er ook gebruik van de rollen binnen SugarCRM. De rollen zijn Administratie, Docent en Stagecoordinator.
Pagina 13 5. Klassendiagram In dit hoofdstuk wordt het klassendiagram van de front-end getoond. Deze dient om de architectuur van de applicatie duidelijk te maken door de relatie tussen verschillende klassen/objecten te tonen en de daarbij horende attributen en functienamen te vermelden.
Pagina 14
Pagina 15
Pagina 16 6. Sequencediagrammen In dit hoofdstuk zijn alle sequencediagrammen te vinden. Het is onderverdeeld in de volgende delen Medewerkers, Studenten, Stages, Bedrijven en Inloggen. Dit komt overeen met de menu opties in het systeem. Medewerkers Lijst van Medewerkers
Medewerker toevoegen Technisch ontwerp Pagina 17
Pagina 18 Medewerker bewerken Studenten Lijst van Studenten
Pagina 19 Student toevoegen Student bewerken
Pagina 20 Stages Lijst van Stages
Stage toevoegen Technisch ontwerp Pagina 21
Stage bewerken opdracht Technisch ontwerp Pagina 22
Stage bewerken bedrijf Technisch ontwerp Pagina 23
Pagina 24 Stage bewerken studenten Stage bewerken notities
Pagina 25 Bedrijven Lijst van bedrijven Bedrijf toevoegen
Bedrijf bewerken Technisch ontwerp Pagina 26
Inloggen Technisch ontwerp Pagina 27
Pagina 28 7.Code toelichting In dit hoofdstuk worden belangrijke code segmenten beschreven die gebruikt kunnen worden om het product te reproduceren. Proxy object Om via PHP functies te gebruiken van de webservice kan een proxy object gebruikt worden. Hieronder de code die ik gebruikt heb om dit te realiseren. Als eerste wordt er een soap client object aangemaakt met de URL naar het WSDL bestand. Vervolgens wordt het proxy object aangemaakt door getproxy() aan te roepen. $soapclient = new soapclient($soap_url,true); $this->proxy = $soapclient->getproxy(); Een functie zoals bijvoorbeeld login kan zo worden aangeroepen. $this->proxy->login($params,'sugarcrm');