REWPERT-G2 En plugin for import av NewsML-G2 standarden til WordPress

Transkript

1 REWPERT-G2 En plugin for import av NewsML-G2 standarden til WordPress Diego Pasten Michael Pande Petter Lundberg Olsen Et bachelorprosjekt for Høgskolen i Oslo og Akershus av studenter på oppdrag fra Aptoma AS Vår 2015

2 PROSJEKT NR. Studieprogram: Informasjonsteknologi Postadresse: Postboks 4 St. Olavs plass, 0130 Oslo Besøksadresse: Holbergs plass, Oslo BACHELORPROSJEKT HOVEDPROSJEKTETS TITTEL Rewpert-G2 PROSJEKTDELTAKERE Diego Pasten (s188071) DATO ANTALL SIDER / BILAG TILGJENGELIGHET INTERN VEILEDER Geir Skjevling Telefon: Telefaks: Michael Pande (s188077) Petter Lundberg Olsen (s188115) OPPDRAGSGIVER Aptoma AS KONTAKTPERSON Stefan Grunert SAMMENDRAG Vår plugin gjør det mulig å bruke et Representational State Transfer (REST) API for importering av nyhetselementer over HTTP, for deretter å lagre og publisere nyhetselementene i WordPress når de mottas. Nyhetselementene følger standarden NewsML-G2 satt av International Press and Telecommunications Council (IPTC) og brukes i dag av blant annet Associated Press (AP), Norsk Telegrambyrå (NTB) og Reuters. NewsML-G2 formatet er implementert som XML. 3 STIKKORD WordPress REST API XML & PHP

3 Forord Forord Dette er vår sluttrapport til hovedprosjektet vi gjennomførte som avsluttende oppgave for bachelorstudiet vårt på Høgskolen i Oslo og Akershus, ingeniørfag data. Dette dokumentet inneholder all dokumentasjon i forhold til dette. Vi kom i kontakt med oppdragsgiver gjennom høgskolens liste over prosjektforslag. Hensikten med prosjektet var å avdekke hvorvidt det er mulig å importere et nyhetsdokument til en WordPress-basert side. Rekkefølgen på prosjektdeltageres navn i dokumentasjonen, nettsted eller annet materiale koblet opp til prosjektet, er enten alfabetisk på fornavn eller tilfeldig, og er ikke ment til å formidle noe ytterligere informasjon om bidrag eller rolle i prosjektet. Vi ønsker å takke vår oppdragsgiver Geir Berset fra Aptoma for å ha gitt oss muligheten til å ha et hovedprosjekt hos dem, og i en så generøs grad åpne sin bedrift for oss som han har gjort. Vi vil også takke Stefan Grunert fra Aptoma for et tett samarbeid, god veiledning og oppfølgning igjennom hele prosjektet. Gunnar Lium hos Aptoma fortjener også en stor takk for å ha gjennomgått kode og delt kunnskap med oss. Vi vil også takke øvrige ansatte hos Aptoma og vår veileder på Høgskolen i Oslo og Akershus, Geir Skjevling for samarbeidet. IPTC develops standards to cover real world requirements and the need for a rich and powerful multimedia news exchange format was raised in the early 2000-years. NewsML-G2 was created for this purpose and is used as delivery format by many news providers. But how to support an easy use of this format by companies or organizations running simple web CMSes? Building an interface to connect the NewsML-G2 world with the WordPress universe is a great idea and IPTC welcomes any tool which makes the use of NewsML-G2 simple and efficient. Thanks to Aptoma and the developer team of this WordPress plugin. Michael Steidl, IPTC Managing Director 1

4 Innholdsfortegnelse Forord... 1 Prosessdokumentasjon... 3 Kapittel 1: Innledning... 4 Prosjektgruppe... 4 Oppdragsgiver... 4 Problemstilling... 5 Mål... 5 Dagens Situasjon... 5 Vår oppgave... 6 Kravspesifikasjon... 8 Kapittel 2 Planlegging av prosjektet Teorier og forutsetninger Hvordan vi skulle arbeide med prosjektet Redskap og verktøy Kapittel 3 Utvikling Hvordan NewsML-G2 er oppbygd Utfordringer Kapittel 4: Starten på slutten av prosjektet Code review Enhetstester Overgang til en dedikert IDE PHPUnit Presentasjon for IPTC Dokumentasjon Markedsføring av produktet Kapittel 5 Konklusjon Læringsutbytte Prosessen Sluttresultatet Oppnåelse av kravspesifikasjon Hva sier oppdragsgiver om produktet?... 36

5 Forord Hva ville ha vært gjort annerledes? Videreutvikling Produktdokumentasjon... 1 Getting started... 1 Requirements... 1 Installation... 2 Multiple Author Support... 5 Uninstall... 6 Architectural structure & Flow... 7 Debug information NewsML-G2 Validation NewsML-G2 API (RESTApi.php) NewsItemParse.php The 'meta' array Unit testing Functions.php KnowledgeItemParse.php HTMLView.php DateParser.php httpheader.php QCodes.php SimpleStorage (API.php) Index.php (WordPress Interface) Admin_panel.php (WordPress Interface) Testing (Unit tests) Misc Image implementation Use of the WordPress database Supported ContentSet Name explanation Testrapport Innledning Enhetstester

6 Forord Blackbox testing Konklusjon Vedlegg Referanser Forprosjektrapport Prosjektskisse Prosjektdagbok

7 Prosessdokumentasjon Prosessdokumentasjon Leserveiledning Rapporten er skrevet for sensor, veileder, oppdragsgiver og øvrige interessenter. Dokumentet er bygget opp slik at den tar for seg prosjektet i kronologisk rekkefølge og bør leses fra start til slutt. Rapporten er delt opp i: innledning, planlegging, utvikling, starten på slutten av prosjektet og til slutt en konklusjon. For å supplere under lesning og for å øke forståelsen, kan hjemmesiden for pluginen med kildekode (GitHub) og eventuelt en live demo være til nytte: 3

8 Prosessdokumentasjon Kapittel 1: Innledning Kapittel 1: Innledning Prosjektgruppe Gruppen består av Michael Pande, Petter Lundberg Olsen, og Diego Pasten. Vi er alle fra ingeniørfag data og har hatt et tett samarbeid ved flere anledninger gjennom studietiden på høyskolen. Oppdragsgiver Vår oppdragsgiver Aptoma, bidrar til å løse utfordringer mediehus møter ved å levere produkter for forvaltning og produksjon av innhold til web. De fokuserer på intuitive og effektive verktøy, og deres produkter er mye brukt av større og mindre mediehus. Selskapet utvikler og oppdaterer egen programvare som kundene betaler fast for å bruke, også kjent som Software as a Service (SaaS). Geir Berset CEO og oppdragsgiver geir@aptoma.com Stefan Grunert Kontaktperson og veileder hos bedrift stefan@aptoma.com 4

9 Prosessdokumentasjon Kapittel 1: Innledning Problemstilling Hvordan importerer man standarden NewsML-G2 til WordPress? Mål For å besvare problemstillingen måtte vi vise at det var mulig å importere NewsML-G2 standarden til WordPress. Dette skulle da gjøres ved å lage en plugin som enkelt kan installeres. I denne sammenheng er plugin en form for tilleggsfunksjonalitet som enkelt kan legges til eller fjernes fra WordPress, noe separat. NewsML-G2 er nyhetsdata lagret i XML og er et forsøk på å standardisere måten mediehus, nyhetsbyråer og andre interessenter overfører artikler og nyhetsinformasjon. Noen eksempler på hva standarden dekker: Artikkel, bildeinformasjon, forfattere, bidragsytere og datoer. WordPress kan beskrives som et bloggverktøy som utviklet seg til å bli en av de mest brukte redskapene for publisering av innhold og for å lage nettsteder med enkel struktur. Dagens Situasjon Mediehus som blant annet Aftenposten, VG, Dagbladet og mange andre verden over, er midt inne i en stor omstillingsfase, som startet for ca. ti år siden. Aptoma selv omtaler det som en medierevolusjon. De møter mange utfordringer. Blant annet at kundene deres i økende grad mottar nyheter digitalt. Problemet er at inntektene per leser bare er en brøkdel der sammenlignet med papir, dette er en effekt som kommer av at kundene forventer at nyheter på nett skal være gratis. I tillegg møter de konkurranse om innhold fra bloggere og portaler som Flipboard. Denne konkurransen er vanskelig å gjøre noe med, fordi på internett kan alle lage sin egen avis. Dette innebærer at alle kan være redaktør og markedsføre seg selv via sosiale media som Facebook eller portaler som Flipboard. I tillegg til at hvem som helst kan skrive, har for eksempel Flipboard tilrettelagt det slik at leseren har gått fra å være en passiv forbruker til å bestemme selv hvilke type innhold som skal vises. At rollen og betydningen papiraviser har hatt vil endre seg dramatisk er nok allerede klart for de fleste. I følge Didrik Munch, konsernsjef i Schibsted var det daglige avisopplaget blitt redusert med ca. en halv million eksemplarer sammenlignet med tall fra Det tilsvarer 150 millioner færre solgte aviser i året. Bare i andre kvartal 2012 hadde norsk dagspresse 150 millioner kroner mindre i annonseinntekter sammenlignet med samme periode året før. I 2011 hadde Google 1 milliard kroner i annonseinntekter fra Norge. Som følge av dette har det skjedd store endringer i redaksjonene både i Norge og resten av 5

10 Prosessdokumentasjon Kapittel 1: Innledning verden. De har måttet nedbemanne, ofte i svært store mengder. Og det stiller krav til en effektiv produksjon og distribuering av nyheter. Avisene jobber derfor med å forenkle prosessen og har også i stor grad gått over til å motta nyheter via nyhetsbyråer. Umiddelbar distribusjon av nyhetssaker har blitt et krav, samtidig som man fortsatt har strenge krav til nyhetene. De må være nøyaktige, lovlige og ikke grovt krenke personer eller grupper. Så avisene trenger altså å spare og effektivisere hvor de kan. Slik det er nå, bruker mange nyhetsbedrifter mye tid på å skreddersy digitale løsninger helt fra bunn. Å skreddersy tjenester er ikke nødvendigvis negativt, men det er tungvint og kostbart når man må gjøre store endringer hver gang man skal sette i gang samarbeid med en ny partner. Som et mulig steg for å forenkle prosessen for overføring av nyheter mellom nyhetsbyråer og andre aktører, har International Press and Telecommunications (IPTC) laget standarden NewsML-G2. Dette som følge av manglende standard for overføring av nyheter og tilhørende metadata. IPTC er en sammenslutning av noen av de største nyhetsbyråene i verden og andre interessenter i samme bransje. Nyhetsbransjen har mange flere utfordringer enn de som nevnes over, og det kan skrives egne masteroppgaver om det. Vår oppgave IPTC og Aptoma ønsker at alle som driver med nyheter skal snakke samme språk. Med samme språk menes selvfølgelig NewsML-G2. Det vanskelige for Aptoma er at norske bedrifter i liten grad har tatt i bruk NewsML-G2 ennå. Aptoma håper at en slik plugin koblet med WordPress vil være med å skape interesse for NewsML-G2. Vår rolle er altså å lage en plugin til WordPress som direkte importerer nyhetselementer som følger standarden. Slik kan brukere verden over (inkludert store mediebedrifter) publisere nyheter rett fra kilde til nett med presis og korrekt metadata i høyt tempo. WordPress er spesielt interessant for dette formålet fordi blant de 10 millioner mest besøkte sidene i verden, brukes WordPress av hele 23% (W3Techs, 2015). NewsML G2 er en standard som er laget med XML som brukes til å pakke nyheter sammen med metadata på en strukturert måte. Nyheter kan være i form av tekst, bilder, video, grafikk/figurer eller en kombinasjon av disse (multimedia). Metadata er data om data, som vil si at man har data som brukes til å definere eller beskrive andre data. I daglig kommunikasjon kommer metadata naturlig av seg selv og 6

11 Prosessdokumentasjon Kapittel 1: Innledning mennesker forstår hva som er meta og hva som ikke er det. For maskiner og datasystemer må disse reglene settes eksplisitt. Det man ønsker med formater som NewsML G2 er å flytte innhold (data) sammen med de tilhørende metadata, men hvor metadataene likevel er adskilt innad i filen fra innholdet. Når man har klare regler for hva som er data og metadata kan man lett automatisere sortering, arkivering og eventuell uthenting av disse dataene. En annen ting som er svært viktig å vite om standarden er at den dekker en ekstrem mengde metadata-tagger, fordi den er laget for alle mulige tenkelige brukstilfeller. Ideelt langsiktig resultat IPTC er en internasjonal interessegruppe som ble opprettet av kooperativer som Newspaper Association of America, World Association of Newspapers and News Publishers, Associated Press og flere andre mediebedrifter. IPTC ønsker å fremme verdenspressen og hovedfokuset ligger på å forenkle distribusjon av informasjon, og de ønsker at flest mulig skal benytte seg av standarden deres NewsML-G2. Standarden er allerede tatt i bruk av noen av de største mediehusene og byråene i verden, blant annet Reuters, Associated Press, og Eurovision. Det positive resultatet som følger av at alle følger én standard er at tekst, bilder, video og metadata lett kan tas ut og behandles etter behov. Dersom man skal pushe innhold til WordPress trenger man ikke å lage nye verktøy for det, man bare kobler opp Aptoma har også programvare som enkelt kan koble seg opp til en tjeneste ved å bruke HTTP protokollen sin POST REQUEST. Aptoma vil derfor ha mulighet til å kunne sende artikler i NewsML-G2 fra sitt redigeringsverktøy Dr. Publish rett inn i WordPress. Aptoma kan nå flere med sitt verktøy for redigering av innhold, Dr. Publish. For nyhetsbyråene AP og NTB og Reuters er eksempler på nyhetsbyråer. Det finnes litt ulike varianter av disse, AP er et non profit kooperativ av mange aviser, journalister, fotografer osv. NTB og Reuters er byråer som har egne journalister og fotografer. Felles for både kooperative og selvstendige byråer er at nyheter, bilder og pressemeldinger lisensieres ut til andre nyhetsorganisasjoner som aviser, blogger og TV. Nyhetsbyråer som har begynt å benytte seg av NewsML-G2 har nå muligheten til å lisensiere nyheter og nyhetsartikler til vesentlig flere. For aviser, journalister, bloggere og andre nyhetsbedrifter Terskelen for å motta nyheter fra flere kilder er nå vesentlig mindre for de som benytter seg av WordPress. WordPress tar seg av veldig mye automatisk for eksempel er den god på visning/sortering av artikler basert på dato, forfatter og nøkkelord. Dette gir muligheter for enhver person å starte sin egen avis. Og svært mange store aviser kjører allerede WordPress. Eksempler på slike er TechCrunch, BBC America, Wired, Fortune, New York Times og The Wall Street Journal. Små aviser kan enklere ekspandere ved å importere nyheter direkte fra store mediehus. 7

12 Prosessdokumentasjon Kapittel 1: Innledning Kravspesifikasjon Prosjektbeskrivelse Develop an article import module for WordPress where the data import is NewsML-G2, the IPTC standard for news exchange Due to the large extent of work needed for designing and implementing a fully operating import plugin, the desired outcome is to be considered more as a "proof of concept" and not as a full working implementation (but of course... feel free! Seeing the import running would be great fun!) The students should in the first line focus on developing text and (a subset of) metadata import, while the import of pictures and other digital assets only needs to be conceptual outlined. Krav Oppgaven i seg selv var i stor grad åpen for tolkning, og hva som var realistisk å få til var noe ukjent, spesielt siden dette ikke er gjort før. Derfor ble kravspesifikasjonen for prosjektet gradvis utarbeidet i samarbeid med veilederen vår hos Aptoma, Stefan, men noen punkter ble definert tidlig. Punkter som vi ble enige om måtte ligge i det endelige produktet. Skal kunne importere tekstlig innhold som tittel, ingress, kroppstekst, forfatter, kategori, nøkkelord og datoer Må kun beskrive konseptuelt hvordan bilder og andre medier skal kunne implementeres. Koden skal legges ut, med en lisens for åpen kildekode, i stor grad uavhengig av hvor komplett det endelige produktet er. Plugin skal bruke WordPress sitt API for utvikling og tåle oppdatering av kjernen til WordPress. Koden skal lett kunne vedlikeholdes av andre. God feilhåndtering som gir meningsfulle tilbakemeldinger. Vi ønsker at det skal være enkelt å ta i bruk Tilfredsstillende god sikkerhet på APIet Plugin skal ha mulighet for manuell opplasting. Grunnet omfanget av standarden var det derfor ikke forventet at en helt komplett plugin skulle utvikles, men heller en plugin som konseptuelt kan vise hvordan det kan fungere. Det er ikke krav om å ha fungerende import av bilder, lyd og video, men en beskrivelse av hvordan dette kunne ha vært gjort i praksis, er ønsket. 8

13 Prosessdokumentasjon Kapittel 1: Innledning Det var også et krav fra arbeidsgiver at produktet skulle legges ut som open source. Slik at andre personer skal ha mulighet til å videreutvikle prosjektet. På grunn av dette er det også viktig at vi har godt dokumentert og leselig kode slik at andre i fremtiden skal kunne legge til funksjonalitet eller vedlikeholde koden. 9

14 Prosessdokumentasjon Kapittel 2 Planlegging av prosjektet Kapittel 2 Planlegging av prosjektet FIGUR 1: PLANLEGGING Teorier og forutsetninger Kunnskap fra HiOA. WordPress er skrevet i PHP, det var derfor naturlig å bruke språket til tross for manglende erfaring. Heldigvis var det en god del likheter mellom PHP, C# og Java, det var derfor mulig å bruke strukturelle og hierarkiske fremgangsmetoder som vi hadde lært tidligere. Vi hadde også gode forutsetninger for å jobbe mot databaser, på grunn av mye erfaring i fag som databaser, og webapplikasjoner fra høgskolen. Der førstnevnte fag gikk i dybden på MySQL-databaser som også WordPress benytter seg av. I samme fag ble vi også introdusert for XML og dets fordeler og ulemper. Vi hadde ingen erfaring med versjonshåndteringsverktøyet Git fra skolen, men hadde ved en anledning brukt et lignende versjonshåndteringsverktøy fra Microsoft kalt Team Foundation Server (TFS). Dette gjorde overgangen til et annet versjonshåndteringsverktøy enklere. Systemutvikling ga oss en god bakgrunn for prosjektstyring og lærte oss mye om fordelen med å ta i bruk smidig utvikling. Dette påvirket i stor grad tilnærmingen vi hadde til prosjektet, både i form av møter og utviklingsmetodikk. Det gav oss også god forståelse av løse koblinger, noe som har vært en grunnleggende tankegang igjennom hele prosjektet. Med løse koblinger menes det at programvaren i størst mulig grad internt har få koblinger med hverandre. Det vil si at koden vår er strukturert med hensyn på enkel utskifting av deler. Det lå også til grunn for valget med å bruke et REST API som kommunikasjonslag. Teorien bak 10

15 Prosessdokumentasjon Kapittel 2 Planlegging av prosjektet REST API er å bruke enkle veletablerte protokoller for kommunikasjon. Et REST API skal bruke HTTP POST Requests, og returnere HTTP headers, samt eventuell ekstra informasjon. Estimeringskunnskapen vi tilegnet oss i systemutvikling viste seg også å være nyttig, da vi ved flere anledninger måtte estimere, eksempelvis: daglig arbeidsmengde for prosjektet. Model View Controller (MVC) strukturen lå til grunn for valgene vi tok, i dette tilfellet var det ikke aktuelt med MVC, men tankegangen med å ha en kontroller som stod for kommunikasjonen mellom alle elementer var sentralt. En grunnleggende forståelse av nettverk var også helt nødvendig, da vi skulle bruke HTTP protokollen til å overføre informasjon fra flere kilder. Fagene vi hadde rundt web, tok for seg både HTML, CSS og JavaScript, noe som viste seg å være helt nødvendig. Begrensninger fra starten NewsML-G2 er en utrolig stor standard, som omfatter svært mange tilfeller av kommunikasjon mellom aktører i mediebransjen, og det er mange måter å vise informasjonen på. Det var derfor urealistisk å implementere hele standarden. Tid ble derfor en viktig begrensning. Aptoma var klar på at vi ikke kom til å klare implementere NewsML-G2 fullt ut i pluginen i prosjektperioden. Det må også nevnes at store deler av standarden er irrelevant å koble opp mot WordPress fordi NewsML-G2 dekker mye mer metadata enn WordPress gjør, og det er unødvendig å parse og lagre alt dette. Ønsket fra Aptoma var å bevise at det var mulig med overføring av data, og de ønsket en plattform som var lett å arbeide videre på. Oppgaven er laget for å sparke i gang en trend de mener er nødvendig for å effektivisere arbeidet rundt nyhetspublisering. Som nevnt litt lenger opp ble tiden en kjempeviktig begrensning som vi måtte ta hensyn til i alle deler av prosjektet. Under planlegging var det viktig å ikke ta vann over hodet, og sette opp mål som var realistiske og som samtidig ikke var helt uten ambisjoner. Manglende kunnskap om PHP og NewsML-G2 Da vi startet dette prosjektet var det bare et av gruppemedlemmene som hadde jobbet med å skrive velfungerende PHP. Dette førte til at deler av utviklingen har gått noe saktere fordi enkelte gruppemedlemmer måte lære seg språket mens utviklingen pågikk. Dette har også ført til at det ble tatt noen avgjørelser som man i ettertid ser at kunne ha vært gjort på andre måter. Hele gruppen måtte også lære seg XML-standarden NewsML-G2. Dette er en meget omfattende standard bestående av flere hundre tagger og attributter. Dette gjorde planleggingsfasen noe vanskeligere. 11

16 Prosessdokumentasjon Kapittel 2 Planlegging av prosjektet Hvordan vi skulle arbeide med prosjektet Prosjektet startet med et gruppemøte første mandag i januar (5. jan). Det første møtet gikk stort sett ut på å forstå omfanget av prosjektet og hvilke oppgaver som måtte gjøres. Det ble diskutert en del med Stefan. Straks forståelsen av omfanget og oppgaven var noenlunde på plass, begynte vi å snakke om tilnærming. Utviklingsmetodikk Vår kravspesifikasjon var ikke klar nok, og var definitivt åpen for endringer. Plandreven utvikling er derfor ikke optimalt for denne type prosjekt. Valg av utviklingsmetodikk er avhengig av mange faktorer blant annet, fleksibilitet, kommunikasjon og tillitt. Vi har som en gruppe tidligere jobbet på prosjekter, og har derfor god oversikt over hverandres styrker og svakheter. Vi kommuniserer godt og presterer godt i samarbeid. Det ble derfor naturlig å gå for en smidig metodikk. Valget stod for oss da mellom SCRUM, og Extreme Programming. Vi vurderte først SCRUM, og kom frem til at selv SCRUM krever mer planlegging enn det vi føler er nødvendig. Iterasjoner og sprinter ga ikke noen mening i dette prosjektet. Planning poker var lite interessant i dette tilfellet også. Det ble for mye dokumentasjon og planlegging. Extreme Programming var det nærmeste vi kom noe som passet for prosjektet, men selv ytterpunktet innen smidig utvikling var ikke riktig for oss. Vi kom med andre ord aldri frem til en utviklingsmetodikk som passet prosjektets omfang. Prosjektet ville kun vare i noen få måneder, og vi er et team på tre. Vi valgte derfor å ha noen faste rammer for utvikling, basert på kjente smidige utviklingsmetoder og prinsipper. Lean er prinsipper som brukes for å oppnå høy kvalitet, rask levering av et produkt som samsvarer med kundens ønsker. Toyota var pioner på denne typen produksjonsmetodikk. Vi har lånt mye fra disse idéene. Organizations that are truly lean have a strong competitive advantage because they respond very rapidly and in a highly disciplined manner to market demand, rather than try to predict the future. Mary Poppendieck 12

17 Prosessdokumentasjon Kapittel 2 Planlegging av prosjektet 1: Eliminate waste 2: Build quality in 3: Create knowledge 4: Defer commitment 5: Deliver fast 6: Respect people 7: Optimise the whole (Poppendieck & Poppendieck, 2003) Etter å ha lest prinsippene ser man at det handler om fjerne arbeid og prosesser som ikke skaper verdi for kunden. Dette kan for eksempel være unødvendige møter, oppgaver, irrelevant dokumentasjon eller for mye planlegging fremover. Mary og Tom Poppendieck skriver at punktene ikke må misforstås. Punkt 5: Deliver fast må ikke forveksles med at man skal levere slurvete kode. Punkt 7: Optimise the whole betyr ikke at man skal ignorere de små detaljene. Så man kan altså ikke bare gjøre helt som man vil, men man må finne rutinene som gir oss fleksibilitet men også muligheten til å måle eller i det minste bekrefte fremgang i arbeidet. Ut ifra oppgaven så vi ganske raskt at dette var prinsipper vi måtte bygge våre daglige rutiner rundt. Arbeidsmetoder og rammer Vi skal jobbe opptil 7 timer, 4 dager i uka. Dette gjør vi helst hos Aptoma. Denne avgjørelsen er tatt på grunnlag av fordelene man får ved faste rammer i arbeidslivet. Det vil si at vi jobber fra 09:00 til 16:00, mandag til torsdag. Vi får lunsj hos Aptoma mellom og Dokumentasjon under utviklingstiden skal hovedsakelig foregå ved bruk av personlig detaljerte og hyppig oppdaterte daglige oppføringer i dagbok. Valg og detaljer fra møter og utviklingsarbeid skal derfor føres i den personlige dagbok til utviklingsperioden er over. Vi skal ha daglig kommunikasjon og helst daglige møter. Dette for å holde oversikt og for eventuelt kunne legge planer for de nærmeste dagene. Dette er inspirert av daily standup fra utviklingsmetodikken SCRUM. Arbeidsdagene kan gjerne starte med gruppemøte, med mindre gruppen har helt klare arbeidsoppgaver. Dersom det dukker opp et problem som bør løses i flertall er det bare å samle gruppen til ett møte. Dårlig og manglende kommunikasjon er en av hovedgrunnene til at det går dårlig med prosjekter. Dette innebærer også at vi uten å nøle holder svært tett kommunikasjon med oppdragsgiver. 13

18 Prosessdokumentasjon Kapittel 2 Planlegging av prosjektet Alle skal alltid ha en arbeidsoppgave eller noe å gjøre. Vi må strebe etter å unngå dødtid, samtidig som det ikke er noen krav til tidsbruk på arbeidsoppgaven. Det krever tillit til hverandres kompetanse, og arbeidsmoral. Fleksibel håndtering av arbeidsoppgaver. Alle har ansvar for alles oppgaver, ingen sitter på ansvaret alene om oppgaven. Koden skal testes, i dette legger vi enhetstesting av en del kode, blackbox testing av programmet som en helhet, i tillegg til to automatiske blackbox testing av to klasser. Redskap og verktøy Programmeringsredskap og utviklingsmiljø Vi har brukt Notepad++, Atom.io og PHPStorm til programmering. Fordi vi utvikler programvare i PHP og bruker databaser, satte vi opp web-stacker på egne maskiner slik at vi kunne teste lokalt i stedet for laste opp kode til en server hele tiden. En web-stack er en samling med programvare som inneholder alt det en server trenger for å kunne drive koden vi skriver. Hvordan stackene ble installert varierte litt etter hvilket operativsystem vi kjørte. Prosjektstyring og deling av dokumenter Vi startet i det små med enkel Dropbox synkronisering. Dette var mest for enkel planlegging i startfasen. Utenom deling av testfiler gikk vi over til mer spesialiserte verktøy for ulike typer oppgaver. En prosjektside ble satt opp i slutten av november Vi brukte WordPress på denne og det ble derfor slik at siden hovedsakelig ble brukt som prosjektdagbok. 14

19 Prosessdokumentasjon Kapittel 3 Utvikling Kapittel 3 Utvikling Figur 2: Utvikling I de foregående kapitlene har vi forklart at det i vår oppgave ble vanskelig å planlegge alt fra start og vi har prøvd å beskrive avgjørelsene som ble tatt ved prosjektstart. Nå vil vi forklare mer i dybden om problemene som dukket opp underveis og hvilke løsninger vi valgte for disse utfordringene. Teksten under er blant annet basert på prosjektdagboken som ble skrevet underveis av alle gruppemedlemmene. Utvikling de første ukene Vi hadde prosjektstart tirsdag 6 januar. De første dagene ble det bestemt at vi skulle sette oss inn i hvordan NewsML og WordPress var satt opp. Mye av tiden gikk til googling og lesing av dokumentasjonen til standarden. Allerede på dag to, startet vi diskusjoner rundt hvordan pluginen skulle lages. Det første vi kom frem til var en løsning der vi lagde et objekt av XML dokumentet, for så å sende det til en PHP modul, som lagde et HTML dokument av det for WordPress. Tanken bak dette var å lage en svært enkel måte for utvikleren å endre visningen av det som blir importert. Vi kom også på et par andre ideer, blant annet en relasjonsdatabase til for mellomlagring. Vi kom til slutt frem til at å importere innholdet fra dokumentet til en array, og så rett inn i WordPress var en bedre løsning. Fordi dette var mye innhold som var felles for begge systemene og som er det mest relevante delene fra en artikkel. Blant annet: tittel, innhold, forfatter og dato. 15

20 Prosessdokumentasjon Kapittel 3 Utvikling Så vi tegnet opp et enkelt grensesnitt fra et top-down utviklingsstandpunkt: FIGUR 3: GRENSESNITTS ILLUSTRASJON FRA TIDLIG I PROSJEKTET Fordi Michael hadde noe erfaring med PHP og hadde sett på WordPress sitt oppsett for databaser, var han og Petter ansvarlig for å starte med prototyping etter tegningen vi hadde laget. Petter var ansvarlig for å lage en array fra XML dokumentet som Michael kunne jobbe med. For å opprette arrayen brukte Petter XPath som er et query-språk for XML. PHP har et bibliotek kalt DOMXpath som ble brukt for å parse XML dokumentet. Det ble her laget et kontrollpanel i WordPress hvor vi manuelt kunne laste opp NewsML-G2-filer. Den første prototypen klarte å lese overskrift og innlegg for så å legge det inn i et WordPress-innlegg. Dette gjorde at gruppen fikk et stort løft i og økte produktiviteten, da vi allerede hadde fått til noe. Uke 2 startet med planlegging, og det ble brukt en del tid på å planlegge videre arbeid på kontrollpanelet som skulle vises i WordPress. Noe som viste seg å være delvis bortkastet arbeid. Vi fikk beskjed om at pluginen helst burde være RESTful, vi skulle ikke trenge et kontrollpanel for manuell opplasting. 16

21 Prosessdokumentasjon Kapittel 3 Utvikling Et RESTfult API vil si at all kommunikasjon foregår over HTTP protokollen og at interaksjoner skjer ved bruk av POST og GET spørringer, responsen skal også inneholde en HTTP status kode (404, 400, 201, 200 m.m). Dette innebærer at brukeren skal kunne sende NewsML-G2 fra hvor som helst i verden, fra hvilken som helst enhet, enkelt og kjapt. En bruker skal ha muligheten til å redigere en nyhetsartikkel i et vilkårlig publiseringsverktøy som kan eksportere artikkelen til NewsML-G2. Verktøyet til Aptoma, Dr. Publish kan dette, verktøyet kan også eksportere det rett ut over HTTP protokollen til et API. Det vil si at man kan bruke Dr. Publish eller andre verktøy til å lagre og redigere nyhetselementer i WordPress, via vår plugin. FIGUR 4: ABSTRAKT OG TEKNISK BESKRIVELSE AV HVOR VI UTVIKLER 17

22 Prosessdokumentasjon Kapittel 3 Utvikling Skiftet til et REST API påvirket ikke stort på fremgangen, da det vi lærte om NewsML-G2 som format hadde vært det mest tidkrevende arbeidet. FIGUR 5: GJENSKAPING AV ILLUSTRASJON FRA PLANLEGGINGSFASE ETTER AT VI KOM FREM TIL EN LØSNING MED REST API 18

23 Prosessdokumentasjon Kapittel 3 Utvikling Hvordan NewsML-G2 er oppbygd FIGUR 6: NEWSML-G2 XML SYNTAX Som nevnt før så er NewsML-G2 en massiv standard og det er flere hundre tagger og attributter bare for newsitems. NewsML-G2 er XML-basert så de følger derfor samme enkle måte å strukturere data på. En NewsML-G2- fil inneholder en News Message, som er den overordnede taggen som pakker inn de andre taggene under seg. Inne i News Message følger to hovedtagger, Header og Item Set. Media som bilder, video, lyd er lagret som lenker. De ligger ikke i selve nyhetsmeldingen. Som nevnt ønsker vi å nevne de viktigste momentene rundt NewsML-G2 i sidene under, men dersom du skulle være interessert i å fordype deg i emnene så anbefaler vi lenkene under:

24 Prosessdokumentasjon Kapittel 3 Utvikling FIGUR 7: OPPBYGNING AV EN NEWS MESSAGE MED NEWSITEMS NewsML inneholder to tagger som beskriver personene som har vært med på å skape innholdet i en newsitem. Creator er personen som opprettet dokumentet og contributor er personen som har vært med på å utforme innholdet. En newsitem kan bare en creator, men flere contributors. Både creator og contributor kan inneholde informasjon som epost, navn og hvilken rolle de har i forbindelse med artikkelen. 20

25 Prosessdokumentasjon Kapittel 3 Utvikling En newsitem inneholder alltid en guid (global unique identifier) og et versjonsnummer. Vi bruker denne informasjonen til å opprette nye revisjoner av en artikkel. Om man sender inn en artikkel som allerede ligger i databasen, blir det sjekket om det nye versjonsnummeret er høyere enn det som allerede finnes, og oppdaterer den eksisterende artikkelen som en ny revisjon Utfordringer Versjonshåndtering For å opprettholde kontroll og backup på den noe mer komplekse koden vi etterhvert begynte å få, tok vi i bruk Git. Vi brukte også Sourcetree som er grafisk grensesnitt for å forenkle versjonshåndteringen. Vi fikk på den måten en svært effektiv og oversiktlig håndtering av kode. De forskjellige versjonene av koden lå først på BitBucket før GitHub, som er en tjeneste for lagring av kode ved bruk av versjonshåndteringssystemet, Git. Det å bruke Git har vært en styrke gjennom prosjektet, og har redusert risikoen for overskriving og sletting av hverandres kode. Det har også gjort det enklere å kombinere hverandres kode. Vi har også brukt Git til å publisere nettstedet for pluginen. Dette ved bruk av OpenShift sine servere som er satt opp til sende kode rett fra Git til nettstedet ved bruk av verktøyet SourceTree. XML / XPATH / XSD Vi fikk tidlig vite at NewsML er en XML standard, så det første vi gjorde var å finne ut hvordan vi skulle hentet ut informasjon fra XML-dokumentet. Veilederen vår hos Aptoma anbefalte oss å bruke klassen DOMXpath klassen i PHP. Vi brukte et par dager på å lære oss hvordan man bruker denne klassen, og fant fort ut at dette var det vi var ute etter. Det dukket opp et par problemer, som for eksempel registrering av namespace, og hvordan gjøre en query på resultatet av en tidligere query, som ikke var like godt dokumentert i PHP manualen. Vi klarte allikevel å løse alle problemer og et av gruppens medlemmer ble etter hvert ganske drevne på finne data i et XML dokument. Vi brukte også XSD dokumenter skrevet av IPTC for å validere NewsML. XSD filene brukes i en NewsML validator laget av vår veileder hos Aptoma Stefan Grunert. 21

26 Prosessdokumentasjon Kapittel 3 Utvikling NewsML-G2: ContentSet Første gang vi prøvde å importere NewsML vi hadde mottatt fra DPA og Reuters dukket det opp en uventet utfordring. Det viste seg at det ikke finnes en standard for hvordan innholdet i <ContentSet> skal struktureres, som er den delen av et NewsML dokument hvor selve innholdet i en nyhetsartikkel ligger. Når vi begynte å se på forskjellige eksempler, fant vi fire forskjellige måter andre aktører hadde strukturert innholdet. Siden vi hadde lyst til å lage en plugin som støttet alle NewsML dokumenter på det daværende tidspunkt følte vi oss litt hjelpeløse med tanke på at det kunne være dokumenter vi ikke kunne kan importere uten spesiell tilrettelegging. Ved flere samtaler med veilederen vår hos Aptoma, fant vi ut at det er en pågående diskusjon mellom IPTC og andre NewsML interessenter om hvordan <ContentSet> skal behandles. Vi bestemte oss til slutt for å bruke de fire måtene vi hadde implementert støtte for, og at eventuelle andre former for strukturering av innhold i <ContentSet> ikke ville bli parset. Grunnet til at vi falt på denne avgjørelsen var at XHTML 4, XHTML5 var standarden de fleste andre NewsML aktørene bruker, og NITF er IPTCs standard, og de ser på dette som en offisiell del av NewsML. Dette innebærer at om noen velger en annen måte å strukturere denne informasjonen vil ikke pluginen vår ta med innholdet i artikkelen. En annen konsekvens at de har overskriften i <ContentSet>, i tillegg til <headline>, vil få overskriften som en del artikkel innholdet. PHP som programmeringsspråk Vi møtte en rekke utfordringer i møte med PHP. En av disse var grunnleggende forskjeller som at PHP er weakly typed, og at det derfor ikke var mulig å overloade funksjoner. Utfordringer med overloading opplevde vi når vi skulle lage nye klasser og funksjoner der vi ikke kunne ha samme funksjonsnavn med forskjellige innsendte variable. En annen var at alle funksjonsnavnene er annerledes enn det vi er vant til. Det medførte også noen rare særtilfeller, eksempelvis at en tom streng er det samme som null. En annen konsekvens av at vi valgte PHP var at vi kanskje ikke fikk brukt språket på den mest optimale måten. Vi valgte å overføre informasjonen fra newsitemparse via en array, men vi fant senere ut at vi kunne ha brukt objektorientering for gjøre lesing av informasjonen lettere. I PHP kan man bytte mellom returverdier og variable -typer. Dette gir muligheter, men skaper også mange feller man kan gå i om man ikke trår forsiktig. PHP behandler også arrayer på en litt annen måte enn tradisjonelle språk vi har brukt tidligere. Alle arrayer kan være assosiative, og man trenger ikke å deklarere en fast størrelse. Dette gjør at du kan bruke funksjonen arraypush til å legge til flere numeriske indekser. Vi fikk også erfare at sammenlikning er noe mer forskjellig enn det vi har vært borti tidligere. I PHP er det to typer sammenlikning: == og ===. == sjekker som en type er lik en annen, for eksempel == null eller 0 == null, mens === sjekker om de to verdiene er identiske, for eksempel null === null mens 0!== null. 22

27 Prosessdokumentasjon Kapittel 3 Utvikling Produktet er en plugin til WordPress som gjør det mulig å importere IPTC standarden NewsML- G2 (XML) til WordPress. Straks pluginen er installert kan brukeren importere nyhetselementer igjennom et API. APIet er RESTfult, det vil si at all kommunikasjon foregår over HTTP protokollen og at interaksjoner skjer ved bruk av POST og GET spørringer, responsen skal også inneholde en HTTP status kode (404, 400, 201, 200 m.m). I dette tilfellet bruker vi kun POST, da det kun går en vei. Dette innebærer at brukeren kan sende NewsML-G2 fra hvor som helst i verden, fra hvilken som helst enhet, enkelt og kjapt. En bruker får da muligheten til å redigere en nyhetsartikkel i et vilkårlig publiseringsverktøy som kan eksportere artikkelen til NewsML-G2. Verktøyet til Aptoma, Dr. Publish kan dette, verktøyet kan også eksportere det rett ut over HTTP protokollen til et API. Det vil si at man kan bruke Dr. Publish eller andre verktøy til å lagre og redigere nyhetselementer i WordPress. Håndtering av kategorier og nøkkelord Nøkkelord var enkelt å håndtere, men utfordringen og kompleksiteten ble større enn antatt når vi skulle implementere kategorier. Kategorier også kjent som subjects og/eller mediatopics i NewsML-G2, er definert ved en QCode. Disse XML taggene trenger ikke nødvendigvis inneholde en skriftlig beskrivelse, navnet til kategorien kan kun være beskrevet med en QCode. En QCode er en unik forkortelse for en ressurs, f.eks. en URL. QCode: medtop: er bedre enn å referere til adressen Det gir også en enkel arkitektur å koble konsepter som subjects / mediatopics opp mot en ID, som ikke bare er unik for det ene dokumentet. Dersom kategorien kun er beskrevet med en QCode, må den skriftlige beskrivelsen av kategorien, for eksempel: Kultur, hentes fra et annet sted. For dette har IPTC laget en database over subjects og mediatopics til diverse språk, det gjør at man kan koble tittelen/navnet til subjects ved bruk av QCodes og språk. Det man da får av IPTC er et NewsML-G2 knowledgeitem. Et stort problem som måtte håndteres her var at IPTC hadde satt begrensning på 10 spørringer i døgnet. Vi kunne derfor ikke gjøre spørringer hver gang man ville pushe NewsML til WordPress. For å løse denne utfordringen bestemte vi at innholdet i IPTC-databasen måtte kunne lagres lokalt til hver installasjon av Rewpert, og det helst ikke bør gjøres i WordPress sine databaser for å unngå komplikasjoner ved avinstallering. Vi tilføyde en mulighet for å parse alle subjects og mediatopics fra NewsML-G2 knowledgeitems og setter de i en lokal plugin database vi opprettet for dette formålet, slik at dersom vi mottar et subject uten navn eller tittel kan vi hente ut navn eller tittel basert på språk og QCode fra databasen. 23

28 Prosessdokumentasjon Kapittel 3 Utvikling Selve mellomlagringen av databasen medførte også en rekke utfordringer, blant annet med ytelse. Det å gjøre mange tusen spørringer mot en SQLite database kan ende opp å ta så mye som sekunder. Vi klarte å få ned tiden til under et sekund ved å kombinere spørringene opp i bolker på et par hundre inserts / updates per spørring. Da vi jobbet med å tilnærme oss informasjon om QCodes la vi merket til at det var forskjell på om navene hadde store eller små forbokstav avhengig om ordene var på engelsk, tysk eller fransk. Vi var ikke helt sikre på hvorfor det var forskjell på forbokstavene så vi bestemte oss å spørre på den offisielle IPTC gruppen på Yahoo. Vi fikk da svar av Michael Steidl, som fortalte oss at substantiv skal a stor forbokstav på tysk og fransk. Støtte for flere forfattere Det å implementere støtte for en forfatter var støttet av WordPress og gikk fort. Utfordringen kom når vi måtte utvide funksjonaliteten internt i WordPress, og ikke bare i vår plugin. Hvordan skal vi gi WordPress ytterligere funksjonalitet uten å påvirke andre plugins eller ødelegge for brukeren? Det var også viktig for oss at produktet vårt skulle være selvstendig og ikke ha avhengighet til andre plugins. Vi så nærmere på en plugin laget av selskapet bak WordPress (Automattic) som kunne tilby tilsvarende funksjonalitet. Det viste seg at de ikke hadde klart å lage en plugin som helt sømløst uten manuell endring av filer kunne tilby denne funksjonaliteten. Dette medførte at vi tok valget å implementere en tilsvarende løsning skreddersydd for vårt behov. Løsningen vår krevde bare at brukeren måtte erstatte en metode og lime inn en kodesnutt. Statuskoder og debuginformasjon Fra det tidspunktet vi fant ut at pluginen skulle bruke et REST API var det viktig å avgjøre hvordan man skal gi god tilbakemelding til brukeren. Vi kom frem til at en god løsning var å sende et enkelt html dokument tilbake med informasjonen. I utgangspunktet sendte vi bare enkel informasjon tilbake i et HTML dokument ettersom koden kjørte, men senere erstattet vi dette med et mer omfattende feilhåndteringssystem. Mange særtilfeller og bugs Vi opplevde en rekke bugs og potensielle bugs underveis i utviklingsprosessen. En av disse var forskjeller på UNIX og Windows baserte systemer. Problemet vi støttet på var at UNIX og Windows behandler filbaner på forskjellig måte. 24

29 Prosessdokumentasjon Kapittel 3 Utvikling Det var et problem angående versjoner av PHP. Et av gruppens medlemmer hadde ikke oppdatert den lokale WAMP serveren siden han installerte den for to år siden. Dette gjorde at han hadde en eldre versjon av PHP. Uforutsette hendelser og fravær Vi beste oss ganske tidlig i prosjektet for at vi skulle behandle dette prosjektet som en vanlig jobb. Dette innebærer å ha fri på helligdager (1. mai, påske og liknende), pluss at vi hadde også fri i vinterferien fordi et av gruppemedlemmene skulle ta en eksamen i den perioden. Det var også to tilfeller av lengre perioder med sykdom. En periode i starten av januar det et gruppemedlem ikke kom på jobb i et par dager og en periode i mars hvor et annet gruppemedlem var redusert i en lengre periode. Vi hadde skrevet om sykdom i risikoanalysen, men det viste seg at både risiko for sykdom og dets konsekvenser var noe undervurdert. 25

30 Prosessdokumentasjon Kapittel 4: Starten på slutten av prosjektet Kapittel 4: Starten på slutten av prosjektet Fordi produktet er Open Source var det også nødvendig å lage ett nettsted som samler informasjon og kode for videre utvikling. Det har derfor også vært høy prioritet å gjøre koden mer forståelig, tilby god dokumentasjon. Fra og med ca. 20 mars sluttet i legge til helt ny funksjonalitet, men det betyr ikke at det ble lite å gjøre, tvert imot ble mye arbeid lagt ned. FIGUR 8: AVSLUTNING Code review Et forslag som ganske tidlig kom fra oppdragsgiver var att en av deres ansatte kunne hjelpe som med å gå gjennom koden for å forbedre den, altså en code review. En ansatt fra Aptoma og et gruppemedlem gikk gjennom hele koden og gjorde en god del endringer i tillegg til at det ble notert en del anbefalinger som måtte gjøres. Gjennomgangen av REST APIet medførte en rekke endringer, blant annet ble guard code brukt enda mer. En guard er et boolsk uttrykk som ved bruk av en IF test stopper videre kjøring av kode. Et typisk eksempel på dette er if($var == null) { return; }. Flere funksjon-, klasse- og variabelnavn ble gjort mer selvbeskrivende. En del strukturelle endringer ble utført. Eksempelvis ble feilhåndtering og debuginformasjon endret drastisk. Det ble også tydelig at vi burde bytte til et Integrated Development Environment (IDE). Code review av klassen newsitemparse.php ble gjort internt i gruppa. Dette var fordi Michael hadde vært gjennom et code review og viste hvordan prosessen fungerte samtidig som vi hadde sett gjennom newsitemparse klassen på forhånd, og vi regnet med at den ikke trengte så mye arbeid som mange andre klasser gjorde. Resultatet av gjennomgang var at noen variabel-navn ble endret, et par if strukturer ble skrevet om slik at de ble lettere å forstå og det ble lagt på noe mer forklarende kommentarer. 26

31 Prosessdokumentasjon Kapittel 4: Starten på slutten av prosjektet Enhetstester Vi har bare ved en anledning tidligere skrevet enhetstester og fordelene var ikke åpenbare for oss på det tidspunktet. Likevel mente oppdragsgiver at vi skrive automatiske tester for å unngå at endringer skaper nye feil. Vi lagde derfor et svært enkelt test rammeverk, for å teste koden vår. Overgang til en dedikert IDE Da prosjektet startet ble vi anbefalt av oppdragsgiver å bruke PHPStorm som redigeringsverktøy for PHP. Vi valgte å ikke bruke PHPStorm grunnet at programmet ikke var tilgjengelig uten kjøp av lisens. Vi fant senere ut at man kunne motta en ettårig studentlisens som gjorde at vi kunne fullføre prosjektet i en Integrated Development Environment (IDE). Dette gjorde omstrukturering og refaktorering av koden raskere og enklere. Som en følge av dette fikk vi økt kvaliteten på koden betraktelig. PHPUnit Da vi skiftet til PHPStorm skiftet vi til testrammeverket PHPUnit og vi valgte da å skrive om testene våre til det nye rammeverket. Grunnen til at vi ikke hadde brukt rammeverk PHPUnit tidligere var at vi ikke fant en enkel måte å inkludere det i prosjektet. Vi tok derfor beslutningen å skrive våre egne tester som ble kjørt via REST APIet. Da vi tok i bruk PHPStorm viste det seg å være lettere sagt enn gjort å inkludere PHPUnit, men vi fikk det til etter noen dager og det var absolutt verdt strevet. Dette førte til at vi kunne skrive om testene til et mer profesjonelt og standardisert rammeverk. Testrapporten vår er lagt ved. Presentasjon for IPTC Vi ble i Mars spurt av vår veileder hos Aptoma om vi kunne lage en presentasjon for en IPTC konferanse som skulle avholdes, med frist på under 24 timer. Han tydeliggjorde at dette var helt frivillig, og bare hvis vi hadde tid, men vi tok utfordringen. Presentasjonen skulle være av prosjektet vårt og inneholde et forslag til hvordan ContentSet kan håndteres i NewsML standarden, med andre ord hvordan teksten skal formateres og struktureres. Vi skulle også ta opp eventuelle utfordringer vi hadde møtt underveis. Enten skulle han avholde presentasjonen, eller så skulle vi gjøre det over nettet. Å lage en god presentasjon for vårt prosjekt tok tid, men det som var utfordrende var å komme på et forslag til en løsning på et problem vi mener IPTC ikke har adressert nok. 27

32 Prosessdokumentasjon Kapittel 4: Starten på slutten av prosjektet Vi måtte først tenke oss frem til en løsning vi syntes fungerte godt til å strukturere tekst og innhold. For oss er det en selvfølge å bruke webteknologier som XHTML/HTML5 for å strukturere tekst og annet innhold. Det er teknologi som hele nettet bruker, og som gir større fleksibelt enn News Industry Text Format (NITF), uten at det blir vanskeligere å behandle informasjonen for mottaker. Det var også tatt i bruk av alle de mediehusene vi fikk NewsML-G2 nyhetssaker fra. Vi så også at flere av aktørene hadde redundant data i NewsML dokumentet. Eksempelvis var forfatter og overskrift nevnt både i metadataen til dokumentet og i ContentSet. Allikevel var ikke problemet for oss å komme på en løsning, men hvordan formidle den. Vår posisjon i hierarkiet som studenter, gjorde dette utfordrende diplomatisk sett. Hvordan formidle vår mening uten å bli oversett som følge av vår manglende erfaring som utviklere i nyhetsbransjen? IPTC hadde brukt NITF i NewsML-G2 eksemplene sine, og dette skulle diskuteres på en IPTC konferanse. Veilederen vår mente også at XHTML/HTML5 er veien fremover, ikke NITF, og det var en god mulighet for at han som skulle avholde presentasjonen, ikke oss. Vi skulle altså formidle hva vi hadde fått til, og hva vi mener burde være bedre med standarden NewsML-G2 igjennom en annen person, samtidig som vi helst bør unngå å tråkke på for mange tær. Det var svært utfordrende. Presentasjonen ble dessverre ikke avholdt, men ble sammen med produktet vist på tomannshånd til flere aktører, og sendt på epost til daglig leder i IPTC, som var misfornøyd med det han antok var et angrep på NITF standarden. Det var et resultat av manglende kommunikasjon fordi han kun fikk se PowerPoint dokumentet uten kontekst. Rett før dette dokumentet går til trykkeriet, har vi fått beskjed om at vi skal holde presentasjon via Skype for en ny IPTC-konferanse 1-3 juni. Siden det er på tampen før levering blir resultatet av det derfor dessverre utelatt. Dokumentasjon Det har vært krevende å skrive dokumentasjon på grunn av manglende erfaring med denne typen arbeid. Vi har jobbet med dokumentasjon ved to tidligere prosjekter, men ingen av disse forberedte oss nok på hvordan man strukturerer og effektivt jobber med dokumentasjon. Det vanskeligste med 28

33 Prosessdokumentasjon Kapittel 4: Starten på slutten av prosjektet dokumentasjonsarbeidet var å finne ut hva vi faktisk skulle ha med og hvordan vi skulle strukturere informasjonen på riktig måte. Vi tok utgangspunkt i dokumentasjonsmalen vi fant på hjemmesiden til HIOA, allikevel var det mye å sette seg inn i når vi prøvde å finne den beste måte vi kunne strukturere dokumentet vårt. Det ble konstatert tidlig at vi trengte god tid til å skrive, noe som gjorde at skrivearbeidet startet allerede i mars. Dette viste seg å være en god ide, fordi arbeidet med dokumentasjonen tok mye tid. Markedsføring av produktet Siden produktet vi laget skulle være open source, bestemte vi oss for å lage en side for å markedsføre produktet. Denne siden skal inneholde all dokumentasjon du trenger for å begynne å bruke, vedlikeholde eller videreutvikle pluginen. Siden er satt opp som en landing page og har da som formål å gjøre det enkelt for brukeren, derfor har vi også lagt ved en interaktiv demonstrasjonsside som viser pluginen i aksjon, sammen med skjermbilder og lenker til GitHub repositoriet og en zip-fil av prosjektet. Demonstrasjonsside har vi satt opp med pluginen installert, slik at personer kan se resultatet av et importert NewsML dokument og forsøke å sende inn dokumenter selv. Pluginen har også vært nevnt for daglig leder i IPTC og andre personer som samarbeider om NewsML standarden, Den skal også vises på en IPTC konferanse 2. juni, hvor vi skal holde presentasjon over Skype. Fra BitBucket til GitHub Da produktet var ferdigstilt valgte vi å flytte filene fra BitBucket til GitHub. Vi har brukt BitBucket og SourceTree som versjonshåndteringsverktøy gjennom hele prosjektet fordi vi kunne ha et privat prosjekt uten å måtte betale, noe som ikke var mulig på GitHub. Men siden det ferdige produktet skal være open source valgte vi å flytte prosjektet over til GitHub samtidig som vi gjøre det offentlig. GitHub er en av de mest etablerte leverandørene av tjenester for versjonshåndtering av programmeringskode, og er svært utbredt. Vi anså det derfor som gunstig for prosjektet å bytte fra den noe mer ukjente BitBucket til GitHub. 29

34 Prosessdokumentasjon Kapittel 5 Konklusjon Kapittel 5 Konklusjon Læringsutbytte Sosialt Vi har lært om samarbeid og bekreftet det vi lærte i systemutvikling om hvor viktig god kommunikasjon er for et prosjekt. Også i dette tilfellet var kommunikasjon med oppdragsgiver sentralt; i starten av prosjektet var det ikke god nok kommunikasjon, som førte til usikkerhet om hvordan pluginen skulle implementeres. Vi så først for oss et system med manuell opplasting av flere filer, som vi brukte et par dager på å planlegge. Senere kom beskjeden om at oppdragsgiver ønsket en API løsning i stedet for manuell opplastning. Dette gjorde at den tiden vi hadde brukt på å designe systemet gikk tapt. Det ble også gjort andre oppklaringer gjennom møter med veileder, som for eksempel hvor mye av NewsML standarden vi skulle implementere. Selv om vi trodde vi var klar over hvor viktig kommunikasjon egentlig er, har vi lært hvor viktig det er å ha god forståelse av oppgaven som skal løses. Neste gang så har vi litt mer kommunikasjon med oppdragsgiver tidlig i prosjektet, selv om det skulle virke unødvendig. Versjonshåndtering, prosjektstyring og dokumentasjonsarbeid Det å ha de rette verktøyene er helt essensielt for en effektiv fremdrift. Vi merket tegn på stagnering tidlig grunnet bruken av Dropbox, og frykten for å overskrive hverandres arbeid gjorde at vi måtte stoppe hverandre ofte. Derfor lærte vi hvor viktig versjonshåndtering er for en effektiv workflow, og for å redusere risikoer. Vi lærte oss også å bruke Google Docs for å håndtere dokumentasjonen vår, noe som gjorde at vi alle kunne redigere samtidig på samme dokument og komme med kjapp effektiv tilbakemelding på hverandres tekst. Det å bruke Google Docs har vist seg å være en effektiv måte å samarbeide på omfattende dokumentasjon. Risikoanalyse Når vi ser tilbake på risikoanalysen vi satte ned ved starten av prosjektet ser vi at denne er ganske underestimert. Det var ingen punkter som hadde høy risiko, noe som viste seg å være en grov feilberegning. Sjansen for en forkjølelse i januar/februar er ganske stor, spesielt i et land som Norge. Når vi ser tilbake på risikoanalysen kunne den har blir utarbeidet med mer realistiske risikoer. Denne lærdommen kommer godt med til fremtidige prosjekter. 30

35 Prosessdokumentasjon Kapittel 5 Konklusjon Standarder Vi jobbet hovedsakelig med standarden NewsML-G2 som vi måtte lære oss fra grunnen av. Dette er en ganske omfattende XML standard med flere hundre tagger og attributter. VI lærte etterhvert at hvert at NewsML prøvde å ta høyde for alle mulige situasjoner når det kom til overføring av informasjon. I starten syntes vi at det var mye redundant informasjon i standarden, men innså at dette var nødvendig for at standarden skal være fleksibel. Under arbeidet med datoer måte vi sette oss inn i en annen standard. Dette var tid og dato-standarden ISO Dette var måten datoer og tidspunkter var oppgitt i NewsML, mens WordPress databasen bruker MySQL DateTime. Vi måtte lage en klasse som konverterte mellom de to tidsformatene. PHP Med svært lite tidligere erfaring med PHP har vi fått et stort læringsutbytte av å bruke dette programmeringsspråket. VI har fått erfaring med et språk som ikke er like strengt som for eksempel Java. Arbeidslivet Det å være i et kontorlandskap med medarbeidere fra Aptoma har gitt oss et godt bilde av hvordan det er å jobbe i praksis. Hva slags krav som stilles, hvordan man bør samarbeide, hva slags verktøy som bør tas i bruk med mer. Vi har også fått være med på å bidra til standarden igjennom diskusjonen rundt ContentSet, og vi har fått en større forståelse av hvordan standarder blir utviklet og tatt i bruk. 31

36 Prosessdokumentasjon Kapittel 5 Konklusjon Mestring av GIT Under dette prosjektet har vi blitt gode på å bruke versjonshåndteringsprogrammet Git. Vi kan nå jobbe på et felles prosjekt, og har lært oss Git workflow. Alle har sin egen versjon av prosjektet, som de sender sine endringer til, og når deres endringer er ferdige, blir de da sendt til hovedprosjektet. Dersom endringene ikke kræsjer med en annen persons endringer, trenger man ikke foreta seg noe. I tillegg til dette har vi har lært å bidra til andres prosjekter, og fått vårt arbeid inkludert i andres arbeid. Samt lært å bruke Git til å sette nettsteder ut i verden på rekordfart. Vi har med andre ord lært oss alt vi trenger å vite for prosjektstyring og samarbeid ved bruk av Git. FIGUR 9: VÅR WORKFLOW I GIT PHP Unit / Enhetstesting Vi har lært mye om fordelene med enhetstesting, og hvordan enhetstesting kan brukes til å styrke kvaliteten på koden, redusere feil, og potensielt sett spare tid. Ved automatiske tester kan man få vite om ny funksjonalitet og endringer i koden gir uforutsette konsekvenser. Ved utvidelse av tidligere moduler, eller dersom noen rapporterer et særtilfelle kan man enkelt teste for dette, og gjøre endringer i metoden med vesentlig redusert risiko for at disse endringene påvirker tidligere funksjonalitet. Under utvikling av DateParser klassen ble testene skrevet først. Dette gjorde at når det senere ble oppdaget et tilfelle der klassen ikke fungerte, tok det under fem minutter å fikse problemet. Det var bare å tilføye særtilfellet til testene, gjøre noen små endringer og så kjøre alle testene. Enhetstesting senker terskelen for å forbedre egen og andres kode, og dermed gjør samarbeid enklere. Samtidig som det gjør at utvikleren kan stole på at metoden som ble skrevet fungerer. 32

37 Prosessdokumentasjon Kapittel 5 Konklusjon API / HTTP REST API, bruken av http protokollen (statuskoder m.m) Vi har lært best praksis for APIer, og hvordan REST APIer fungerer. Vi har lært om HTTP protokollen, statuskoder, $_GET og $_POST variable, og sikkerhet rundt dette. WordPress Vi har blitt godt kjent med et av de mest utbredte content management system igjennom prosjektperioden, og vi har lært oss å utvikle plugins til denne plattformen. Annet Vi har fått utforsket SQLite som database, og brukt dette til demonstrasjonssiden vår slik at vi kan ha en identisk versjon av databasen på vår lokale maskin imens vi jobber. Fordelen med SQLite er ytelse og portabilitet. Med SQLite kan vi lagre data som i en vanlig SQL database, der databasen kun er en enkel fil samtidig som vi får en ytelse som er svært god og kan bruke vanlig SQL syntax. I forhold til blackbox/whitebox testing gjort underveis i prosjektet kunne vi ha vært flinkere på å dokumentere de små testene vi gjorde for å ha de til testrapporten. Prosessen Dette er det prosjektet vi har hatt som har hatt lengst tidsspenn, og det har på mange måter vært svært lærerikt. Vi har blitt utfordret ordentlig av oppdragsgiver, og fått en smakebit på arbeidslivet. Det at vi hadde arbeidsplass hos oppdragsgiver gjorde at vi hadde tilgang kan til fagfolk som kunne hjelpe oss om vi hadde tekniske spørsmål. Vi har også fått mulighet til å bli kjent med de ansatte hos Aptoma. Gruppens samarbeid Gjennom hele prosjektet har gruppen hatt et tett samarbeid. Siden hadde en smidig arbeidsmåte var det et mål at alle hadde noe å gjøre til enhver tid. Det har også vært viktig at alle vet hva de andre holder på med, noe som ble gjennomført på de daglige møtene. Om et av gruppemedlemmene hadde et større problem som kunne stoppe hele prosjektet var det vanlig at et annet gruppemedlem tok en pause fra sitt arbeid og hjalp til med problemet. 33

38 Prosessdokumentasjon Kapittel 5 Konklusjon Alle de største utfordringene som for eksempel behandling av subject, forfattere og bilde ble alltid diskutert i felleskap. Valg av verktøy Da vi starte prosjektet ble vi anbefalt av veileder hos Aptoma å bruke PHPStorm under prosjektet. Vi satte oss dermed ned for å se hav dette verktøyet kunne tilby, og fant ganske fort ut at PHPStorm krevde lisens for å bruke i mer enn 30 dager. Vi bestemte oss dermed for å falle tilbake på Notepad++ for Windows og Atom.io for OS X. Vi syntes dette var trist fordi vi hadde blitt veldige glade i IDEer i løpet av de siste semestrene. Senere fant vi ut at PHPStorm har studentlisens som vi kunne bruke. Sluttresultatet Vi er fornøyde med hva vi har fått til, og hvordan vi har håndtert utfordringene. End resultatet ble en godt testet, robust WordPress plugin, som vi tror utviklere og administratorer vil syntes det er enkelt å integrere i sine prosjekter, produkter og tjenester. Vi har klart å oppfylle alle kravene satt av oppdragsgiver, og mer til. Vi har faktisk implementert støtte for bilder. Produktet kommer med enhetstester for videre utvikling, og med en validator som validerer alt som blir sendt inn, slik at brukeren vet om problemet er med dokumentet eller med programvaren vår. Vi har også en demonstrasjonssiden på nett som gjør produktet tilgjengelig, og lar utviklere enkelt prøve programvaren før de velger å installere det på sitt eget system. Læringsutbyttet fra prosjektperioden har vårt godt og vi vil med stor sikkerhet dra nytte av erfaringene vi fikk senere i arbeidslivet. Vi er fornøyde med prosessen og arbeidsfordelingen, og vi har hatt god progresjon selv svært tidlig i prosjektet. Det har vært utfordrende, men vi er fornøyde. 34

39 Prosessdokumentasjon Kapittel 5 Konklusjon Oppnåelse av kravspesifikasjon Krav Skal kunne importere tekstlig innhold som tittel, ingress, kroppstekst, forfatter, kategori, nøkkelord og datoer Må kun beskrive konseptuelt hvordan bilder og andre medier skal kunne implementeres. Koden skal legges ut, med en lisens for åpen kildekode, i stor grad uavhengig av hvor komplett det endelige produktet er. Plugin skal bruke WordPress sitt API for utvikling og tåle oppdatering av kjernen til WordPress. Status Oppnådd Oppnådd, og implementert bilder fullt ut Oppnådd Oppnådd Koden skal lett kunne vedlikeholdes av andre. Oppnådd God feilhåndtering som gir meningsfulle tilbakemeldinger. Oppnådd Vi ønsker at det skal være enkelt å ta i bruk Oppnådd Tilfredsstillende god sikkerhet på APIet Oppnådd Vi ønsker at plugin skal ha mulighet for manuell opplasting. Oppnådd FIGUR 10: OPPNÅELSE AV KRAVSPESIFIKASJON 35

40 Prosessdokumentasjon Kapittel 5 Konklusjon Hva sier oppdragsgiver om produktet? Årets studentoppgave var krevende. Å lage en open source import plugin for NewsML-G2 formatet til WordPress er ikke bare teknisk utfordrende, men forutsetter også en omfattende forståelse av hvordan nyhetsproduksjon og distribusjon i stor skala fungerer. Dette medførte at gruppa måtte sette seg inn i et fagfelt som for dem var komplett ukjent. Der de måtte forstå meget komplekse datamodeller og prosesser. Men dette klarte de helt suverent! Med stort engasjement, i en strukturert og ryddig prosess kom gruppa fram til en løsning som overgår alle forventninger vi hadde til prosjektet. Vi ville vært fornøyd med å få levert et proof of concept, et bevis på at det går an å importere artikler ved hjelp NewsML-G2 til WordPress. Derimot klarte studentene å implementere en fungerende artikkelimport fra A til Å, inkludert bildehåndtering. Til og med tilknytning av importerte metadata til offentlige kataloger (controlled vocabularies) kom på plass, en verdifull funksjon som knapt ett av de kommersielle og etablerte nyhetsproduksjonssystemene tilbyr. WordPress pluginen har allerede vekket stor oppmerksomhet hos utgiveren av standarden NewsML-G2, IPTC som et konsortium av de største nyhetsagenturer i verden, blant annet: Reuters, AP, DPA, AFP og The New York Times. Organisasjonen ønsker å gå videre med utviklingen og har etterspurt en omfattende presentasjon og teknisk gjennomgang. Vi er optimistisk til at resultatet av studentprosjektet vil øke akseptansen og bruken av standarden NewML-G2 i mediebransjen og åpne for helt nye brukergrupper. Tusen takk til Diego, Michael og Petter for en strålende innsats og mange gode diskusjoner! Hva ville ha vært gjort annerledes? Stefan Grunert Head of Product Development Aptoma AS Skulle vi ha startet på nytt ville testdreven utvikling blitt tatt i bruk fra start. Enhetstesting og whitebox testing av importeringsfunksjonalitet ville ha sørget for at vi fjernet tidssluk som manuell testing, og gjort det enklere for andre å videreutvikle koden vår. Vi ville ha brukt PHPStorm fra starten av, og startet med versjonshåndteringsverktøy enda tidligere. Kommunikasjon med oppdragsgiver ville vært enda mer sentralt i starten av prosjektet enn det var og vi ville ha spurt mer om implementasjon og endbrukere til produktet. Vi ville ha satt opp en dokumentasjonsmal og startet å skrive tidligere på dokumentasjonen enn det vi gjorde nå, og heller skrevet litt hele prosjekttiden, istedenfor de siste månedene. Videreutvikling Da produktet i utgangspunktet er laget som en konseptuell versjon av en fungerende plugin er det mulig at det kan bli brukt som utgangspunkt for en annen utvikler, om ikke bare de grunnleggende tankene og løsningene vi kom frem til. Produktet vil forhåpentligvis fungere som en plattform for videre utvikling, og vil øke interessen for NewsML-G2 standarden blant mediehus som bruker NewsML-G2. I hvor stor grad produktet kommer til å bli brukt er vanskelig å si noe om. Det er allerede tilgjengelig for bruk, og den 2. juni skal det avholdes en IPTC konferanse i Warszawa, som kommer til å skape mer blest rundt produktet. 36

41

42 Produktdokumentasjon Getting started Produktdokumentasjon Da produktet er rettet mot brukere over hele verden, og produktet skal gjøres tilgjengelig på nett, har vi valgt å ha produktdokumentasjonen på engelsk. Dette medfører at bruksanvisning, implementasjon og beskrivelse av egenskaper er tilgjengelig for brukere og utviklere. Getting started What the plugin does The plugin allows administrators to send NewsML-G2 documents directly to WordPress with a HTTP POST Request. It supports NewsItems and KnowledgeItems. The plugin also validates NewsItems by default. How the plugin interacts with WordPress All requests are made with WordPress functions. No new tables are created in the WordPress database. When you delete an article (WordPress post), it will also delete all the metadata Rewpert stored in the database. Requirements PHP Version 5.4 or higher WordPress Version Works for and up. (20. November 2014) Should work for older versions as well, but untested. php.ini extension=php_pdo_sqlite.dll extension=php_sqlite3.dll file_uploads = On (Not required for use of REST API, just for manual upload) 1

43 Produktdokumentasjon Getting started Installation 1. Download the zip file from the Rewpert-G2 website (Rewpert.net) FIGUR 11: BILDE AV NETTSTEDET REWPERT.NET 2. Unzip the downloaded folder and place it in the WordPress plugin folder, found under WordPress\wp-content\plugins. FIGUR 12: BILDE AV PLUGIN MAPPEN TIL WORDPRESS 2

44 Produktdokumentasjon Getting started 3. Activate the plugin in the WordPress control panel FIGUR 13: BILDE AV PLUGIN PANELET TIL WORDPRESS KONTROLLPANELET 4. Get the URL found under Post->Rewpert-G2 on the left-hand side of the WordPress control panel FIGUR 14: PLUGIN ADMINISTRATION PANEL 3

45 Produktdokumentasjon Getting started 5. Post your NewsML-G2 to the URL found above. We use Advanced Rest Client, an extension in Google Chrome for the example. NewsItem -> creates a new WordPress post with your NewsItem KnowledgeItem -> update the plugin database of QCodes (subjects and mediatopics). FIGUR 15: ADVANCED REST CLIENT EXTENSION FOR CHROME 4

46 Produktdokumentasjon Getting started 6. If the NewsML is valid and correct the article should appear on you WordPress site FIGUR 16: WORDPRESS FORSIDE ETTER IMPORT Importing Knowledge Item If you want to import a KnowledgeItem xml file it is important that you uncheck to box labeled "Validate NewsML-G2" before you post the KnowledgeItem. Unless this is done the importing of categories from IPTCs controlled vocabulary will not complete successfully. Multiple Author Support WordPress does not support multiple authors out of the box, and some modifications have to be made to your theme. There may be some differences between themes, but these methods should take care of most. The file names and structure mentioned here is based on the default Twenty-Fifteen theme. 1. Find your theme in the wp_contents folder 2. Paste this right over (have_posts() in Archive.php) 5

47 Produktdokumentasjon Uninstall FIGUR 17: PROGRAMMERINGSKODE FOR Å INTEGRERE FLERE FORFATTERE 3. Replace get_the_author() in Template_tags.php FIGUR 18: PROGRAMMERINGSKODE FOR Å INTEGRERE FLERE FORFATTERE 2 Uninstall Important notes 6

48 Produktdokumentasjon Architectural structure & Flow The inline-images on the NewsML-G2 posts will be removed when removing the plugin. To avoid this you should leave the 'Image' folder in the plugin folder intact, and delete everything else. Deactivating the plugin should not prevent the images from being shown correctly. All text from WordPress posts (NewsItems) and meta-data will be intact. Architectural structure & Flow FIGUR 19: STRUKTUREN PÅ HELE PLUGINEN 7

49 Produktdokumentasjon 8

50 Produktdokumentasjon FIGUR 20: ILLUSTRASJON AV HELE FLYTEN AV EN POST TIL ET ENDRESULTAT 9

51 Produktdokumentasjon Debug information Debug information If something went wrong, you can add the &debug=true parameter to the URL when sending a HTTP Post request. The debug information will point you in the right direction if something went wrong. NewsML-G2 Validation Written by Stefan Grunert (MIT License) Validation is enabled by default, and happens right before the NewsItem is parsed. If validation is enabled and the document fails validation, the entire import will be stopped. To disable validation add &validate=false at the end of the query, or use the WordPress Admin Page for the plugin to create it for you. NewsML-G2 API (RESTApi.php) Most important purposes Handles POST Requests (Authenticate and delegate) Handles all communication with WordPress, except the admin panel Handles communication with NewsItem Handles almost all communication This file handles communication between most modules, and the communication with the WordPress core/database. Pattern Authenticate (ALWAYS) Simple HTTP REQUEST validation Delegate POST data to the QCodes class. (KnowledgeItems) Validate NewsML-G2 (NewsItem) Delegate POST data to the NewsItemParser (Returns array) Process returned array, by first fixing date. Process QCodes (Subjects and mediatopics) 10

52 Produktdokumentasjon NewsItemParse.php Insert / update from the WordPress database Return header (ALWAYS) NewsItemParse.php NewsItemParse converts the NewsML-G2 document into a multidimensional array that the REST API needs to import the document to the WordPress database. It uses DOMXPath to find specific information such as headline, author and images of the news article. See the start of NewsItemParse.php to find the full array returned from the parser. FIGUR 21: EN FORENKLING AV STRUKTUREN PÅ ARRAYEN SENDT FRA NEWSITEMPARSE TIL REST APIET The 'meta' array Each index under $returnarray contains an array called 'meta'. The information not related to article content, images, users or categories is stored in the meta array. Adding additional metadata to the WordPress database is simple. All indexes and values in the 'meta' array is stored in the WordPress database. (See below) 11

53 Produktdokumentasjon NewsItemParse.php Adding more information to $returnarray To add more information to $returnarray you can for example add another index in the meta array and create a new function to find the information you need: FIGUR 22: PROGRAMMERINGSKODE SOM ILLUSTRERER HVORDAN MAN UTVIDER PARSE FUNKSJONALITETEN The status code The 'status_code' index in the return array is set to 200 by default (HTTP code for OK). It is changed to 400 (HTTP code for Bad request) in the function setstatuscode if: The post payload is empty No newsitems were found, If the body text, the headline, the guid or the version number is missing. The payload sent is not valid xml (validator is off) Structure of ContentSet This plugin supports three ways of structuring the ContentSet. The first two is to use inlinexml with either NITF (namespace: or XHTML (namespace: You can also use a tag called inlinedata. Things to be aware of If the information is not written correctly the parser is not able to find the body text associated with a specific image. If for some reason there is one or more whitespaces at the start of the XML file, the parser will remove them. The parser will perform all queries regardless of what namespace is present in 12

54 Produktdokumentasjon or if there is a namespace in the outermost tag of the XML file at all. If the NewsML document contains a newsitem with a quote or other text that is supposed to be supplementary to the main article, this text will be stored as its own article. The plugin has no way of handling this type of text correctly and we advise that you exclude it from the xml sent you are importing. Unit testing Unit test is performed with PHPUnit. All tests can be found in the testing folder located in the root plugin folder Functions.php This file contains important functions required by the REST API. KnowledgeItemParse.php Retrieves a set of QCodes and corresponding values and language from a NewsMl-G2 XML document with a KnowledgeItem. Supports: Subjects and mediatopics. It is only used and called through the QCodes.php file. HTMLView.php Creates a styled HTML document based on the input. The HTML document is styled by the OutputCSS file in the same folder. DateParser.php Converts date from the ISO 8601 standard to the WordPress Standard (MySQL DateTime) httpheader.php Sets the HTTP statuscode in the HTTP Response sent from the REST API. 13

55 Produktdokumentasjon QCodes.php Controls and updates a database with QCodes. The database contains different QCodes and their corresponding values and language, the main role is to be a controller for KnowledgeItemParse and the SimpleStorage (API.php) file. The API.php mentioned below stores the values, and the KnowledgeItemParser is told to parse documents by the QCodes class. SimpleStorage (API.php) A simple database storage, for storing parameters quickly and easy. By using the prepare(true) statement and executing afterwards, you should make sure you only do one group of queries at the time, as the stacked queries are executed this order all insert, all update, all delete. Index.php (WordPress Interface) The plugin description shown in WordPress Admin -> Plugins is retrieved from here, and it is also a part of the interface. Admin_panel.php (WordPress Interface) The interface shown in WordPress Admin -> Plugins Testing (Unit tests) Rewpert comes with several PHPUnit tests under root/testing/ Misc. Image implementation When inline images are found, they are stored in the Rewpert-G2 plugin folder under /images/, and the inline link is replaced with a new one 14

56 Produktdokumentasjon Misc. Use of the WordPress database No new tables are created in the WordPress SQL database. All information stored in the WordPress database are stored by the WordPress function library / their API. This is important because: This ensures compatibility with newer versions of WordPress. When you remove a post and metadata created by Rewpert, it will also remove the metadata (for that post) from the WordPress database. Uninstalling the plugin should be a breeze. Supported ContentSet XHTML NITF <inlinedata> (NewsMl-G2 - Plaintext) Name explanation Rewpert-G2 REST NewsMl- G2 to WordPress 15

57 Testrapport Misc. Testrapport Innledning Denne rapporten beskriver alle de større testene vi har gjort i forbindelse med dette prosjektet. Dette innebærer enhetstesting, automatiserte blackbox-tester, og manuelle tester vi har gjort. Det har også blitt gjort mange mindre tester underveis for å se at enkelte funksjoner gjør det de skal. Mange av disse testene har i ettertid blitt erstattet av enhetstester. Alle tester nevnt i denne rapporten er kjørt både på Windows og Unix-basert operativsystem. Vi gjorde dette fordi det viste seg at måten Unix- baserte operativsystemer og Windows behandler feilplasseringer på forskjellige måter. Enhetstester Vi ønsket å ha automatiserte tester av koden slik at vi kunne se om alt fungerte etter at vi hadde endret koden. Vi kom fram til at vi ikke hadde tid til å skrive tester for alle klassene på grunn av at vi trengte tid til å skrive dokumentasjon. Testene er skrevet med rammeverket PHPUnit, å selve testklassene ligger i mappen root/testing. Resultatet når vi kjører alle enhetstestene: FIGUR 23: RESULTAT ETTER KJØRING AV ALLE 80 ENHETSTESTER Av de filene vi tester dekker vi til sammen 96% av alle linjer med kode. 16

58 Testrapport Misc. FIGUR 24: ILLUSTRASJON FRA PROGRAMMET PHPSTORM SOM VISER ANDEL DEKKET AV ENHETSTESTER Valg av enhetstester Vi testet filene etter tid og behov, vi testet derfor kritisk funksjonalitet som parsing, og selv om behovet for testing av APIet er kritisk er det ikke noe vi kan skrive en enhetstest for, og derfor må lage en omfattende blackbox / whitebox test for. Det ble derfor bestemt at det viktigste var å teste newsitemparse.php. Det ble valgt å ikke teste REST APIet fordi returinformasjonen bare er HTTP statuscodes, noe som gjør det vanskelig å finne ut hva som faktisk skjedde i koden. Blackbox testing QCodes og/eller KnowledgeItem har en blackbox-test som kan kjøres. Disse følger dessverre det gamle test systemet vi hadde for testing å kjøres direkte fra koden. Det ble også gjennomført en fysisk blackbox test den 30. april som dekket alle varianter av NewsML dokumenter vi har. 17