Mobile friendly CakePHP application for registering and logging boat rental for field work
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Application
dbmigration
LICENSE
README.md
db.sql

README.md

Feltarbeidsappen

Feltarbeidsappen er en mobilvennlig webapplikasjon utviklet av Simen de Lange ved Havforskningsinstituttet i Norge. Den er skrevet i PHP-rammeverket CakePHP v2.9

Applikasjonen holder styr på hvilke båter som er tatt fra hvilke lokasjoner, hvem som er ansvarlig for båten, hvem andre som er i båten, når den ble tatt ut, og når den skal være tilbake. Den sender varslinger til diverse roller når båten er sen, når et utlån endres, og ved andre anledninger.

Applikasjonen er på norsk.

Ikke vær redd for å legge inn bugrapporter og annet!

Systemkrav

Følgende oppsett er testet. Andre konfigurasjoner kan fungere

  • OS: CentOS 6.7
  • PHP: 5.3.3
  • Webserver: Apache 2.2.15
  • Database: PostgreSQL 9.1.19
  • LDAP-server: Active Directory

CakePHP er agnostisk ovenfor hvilken databaseserver som brukes, men i koden og databasens initscript er det spørringer som sannsynligvis er PostgreSQL-spesifikke

Installasjon

Konfigurering av webserveren

Applikasjonen er skrevet i PHP-rammeverket CakePHP v2.9. Les denne guiden for info om hvordan du skal konfigurere webserveren. The CakePHP Cookbook er veldig nyttig om du sitter fast enten i installasjonen eller utvikling.

CakePHP-rammeverket finnes i mappen Application/ og dens undermapper og bør ikke røres. All egen kode ligger i Application/app/.

Applikasjonens webroot, som webserveren skal peke til, er Application/app/webroot

Alle filer i applikasjonen bør eies av samme bruker som webserveren kjører som

Konfigurering av applikasjonen

Før du prøver å kjøre applikasjonen, må du konfigurere den. I Application/app/Config/ finner du filene core.php og database.php. I core.php må du endre verdien til Security.salt til en lang, tilfeldig string, som f.eks. yJzQ8wcEaMwQEVSnKtTA, og verdien til Security.cipherSeed må endres til et langt tilfeldig heltall, som f.eks. 345802416427581592984995725259. debuglevel bør være 2 for testing, og 0 i produksjon

database.php må også konfigureres. Denne filen inneholder alt som trengs for å koble til en database. De viktige feltene er user, password og database

Initialisering av databasen

Det er på tide å fylle databasen. I repoets rotmappe finner du filen db.sql. Denne inneholder definisjoner for alle tabellene i databasen i tillegg til data for fem av dem: fylker, grupper, brukere_grupper, brukere, og innstillinger. grupper, fylker og brukere_grupper kan du la være som de er. innstillinger og brukere må endres.

Innstillinger

Åpn filen db.sql i din favoritteditor, og gå til nesten bunnen av filen. Der finner du innlegg nr. 11, ldapurl. Legg inn URL-en til din LDAP-server (vanligvis Active Directory, men andre skal også fungere). Du kan også endre andre innstillinger, men denne lar deg logge inn i applikasjonen og endre resten i et GUI.

Brukere

I tabellen brukere, bytt verdien adminusername til brukernavnet ditt. Det kan være flere administratorer, men de bør legges til gjennom GUI-et. Brukernavnet skal inkludere domenet, som f.eks. admin@eksempel.no. IKKE gjør noe med raden nobody. Denne er viktig for hvordan applikasjonen fungerer!

Faktisk initialisere databasen

Når du er ferdig med endringene over, må du kjøre db.sql på en tom database. Det er viktig at databasens eier er feltarbeid_owner med mindre du endrer det i db.sql.

For å initialisere databasen, kjør kommandoen

psql -h dbhost -U feltarbeid_owner -d db < sql.db

eller stapp innholdet i filen db.sql inn i PGAdmin, eller andre måter du kan kjøre SQL-spørringer manuelt.

Etter at du har gjort dette, vil applikasjonen kjøre, men den er ikke klar enda

Konfigurering av resten

Du skal nå kunne navigere i webapplikasjonen i nettleseren din. På bunnen av forsiden skal det være en rød knapp med teksten Adminside. Klikk på denne, og skriv inn logindetaljene til administratorbrukeren du definerte i db.sql. Applikasjonen skal være i stand til å logge deg inn via LDAP.

Alle røde knapper i applikasjonen krever innlogging og riktige rettigheter for å bruke.

Hva knappene på adminsiden gjør, skal være selvforklarende. Det du nå må gjøre er å endre resten av innstillingene. Klikk på knappen Se alle innstillinger. Forhåpentligvis er også innstillingene selvforklarende. De vanskelige er callurl og smsurl. Disse blir forklart i seksjonen "E-poster, SMS og oppringinger".

Du bør også legge til minst én lokasjon. En lokasjon er en stasjon hvor båter kan bli lånt fra. ALLE lokasjoner får automatisk en båt ved navn Leiefartøy når de opprettes. Denne er spesiell, og forklares senere i denne README-filen.

Om du ikke ønsker IMR-bakgrunnen og logoen, kan du endre disse i CSS-filen Application/app/webroot/css/smabat.css.

Nå er det bare én ting igjen før applikasjonen fungerer.

Cronjobben

PHP er elendig til å gjøre sanntidsoppgaver. Det kan i utgangspunktet ikke gjøre noe med mindre det får en HTTP-forespørsel. Dette gjør det vanskelig å sende varsler basert på tid.

For å fikse dette, finnes det et script som skal kjøres hvert 5. minutt. Hvis du kjører applikasjonen på Linux eller lignende, er dette en oppgave for Cron. Hvis du kjører Windows, får du finne ut av hvordan du gjør det selv. Du må også skrive scriptet selv, men det er et meget enkelt skript, så det skal ikke være noe problem.

Scriptet ligger i Application/app/dostuff.bash. Cronjobbek skal se slik ut:

*/5 * * * *     /path/to/Application/app/dostuff.bash

Applikasjonen skal nå fungere!

E-post, SMS og oppringinger

Applikasjonen sender ut e-post og SMS, og ringer opp telefoner ved diverse anledninger. Det går blant annet ut meldinger til:

Båtføreren:

  • Utlånet registreres (SMS)
  • 15 minutter før forventet tilbakekomst (SMS)
  • Når båten skulle vært tilbake (SMS)
  • 10 minutter etter at båten skulle vært tilbake (SMS)
  • 30 minutter etter at båten skulle vært tilbake (SMS)
  • Utlånet redigeres

Kontaktpersonen:

  • Utlånet registreres (mail)
  • Utlånet redigeres (mail og SMS)
  • Når båten skulle vært tilbake (mail og SMS)
  • 10 minutter etter at båten skulle vært tilbake (mail, SMS og oppringing)
  • 30 minutter etter at båten skulle vært tilbake (mail og SMS)
  • Båten returnerer (mail)

Beredskapsvakt:

  • 30 minutter etter at båten skulle vært tilbake (mail, SMS og oppringing)
  • Når en båt som var mer enn 30 minutter forsinket returnerer (mail)

Beredskapsvakten mottar en link i SMSen/E-posten til filen Application/app/webroot/vaktinstruks.html, som inneholder en prosedyre som skal følges. Denne filen bør redigeres for å tilpasse deres behov.

Oppsett av e-post, SMS og oppringing

Filene som er ansvarlige for å sende e-post, SMS og oppringinger ligger i Application/app/Controller/Components/ og heter EmailComponent.php og SmsComponent.php (håndterer både SMS og oppringing). De kontrolleres av innstillinger med forklarende navn.

Hvis e-post er satt opp skikkelig på serveren, skal EmailComponent.php fungere uten modifikasjoner.

SmsComponent.php er laget for Havforskningsinstituttet, og bør omprogrammeres til å passe deres oppsett. Hvis du beholder metodenavnene og argumentrekkefølgen, skal det fungere. Metodene som begynner med _ er interne, og kan fjernes om du ønsker det.

I Application/app/ finner du to mapper ved navn Sms og Calls, sammen med scriptene packCalls.bash og packSms.bash. SmsComponent.php putter JSON-filer med info om SMS/oppringing i disse mappene, slik at en annen applikasjon senere kan hente de og faktisk sende SMS/ringe. Hvis du har en annen måte å gjøre dette på, kan du trygt fjerne disse mappene/scriptene.

Bruk av applikasjonen

Når alt over er gjort, er applikasjonen klar til bruk. Forhåpentligvis er den intuitiv nok til å ikke trenge forklaring.

På forsiden er det en liste med alle båtene i systemet. Den øverste listen viser båter som er for sent tilbake. Under denne er det en liste over alle andre båter som er ute.

Klikker du på båtnavnet i en av disse to listene får du informasjon om utlånet.

Den nederste listen viser alle båter som er inne, og har en knapp for hver av de for å registrere et utlån med båten, og et felt som viser om et fremtidig utlån er registrert.

Listene kan filtreres etter lokasjon.

Registrering av utlån

Hvis du klikker på knappen Ny tur på toppen av siden, eller Registrér utlån i listen over båter som er inne, blir du tatt til en side med et registreringsskjema. Alle obligatoriske felt er markert med en rød *, og skjemaet vil klage om disse ikke er fylt ut.

Når man lagrer utlånet, vil mesteparten av feltene være ferdigutfylt ved neste utlån, så man trenger bare å fylle inn deltakere, destinasjon og forventet tilbakekomst. Denne informasjonen lagres i en cookie.

Merknad til Leiefartøy: Alle lokasjoner har en båt ved navn Leiefartøy. Denne håndteres spesielt av applikasjonen. Båten kan registreres et ubegrenset antall ganger uten å forsvinne fra listen. I listen over båter som er ute, vil leiefartøy stå oppført med navnet man skrev inn i skjemaet og teksten "(leie)" etter.

Avslutte et utlån

Når en båt har returnert, skal båtfører markere utlånet som avsluttet. For å gjøre dette, gå inn på utlånet og trykk på knappen Jeg har returnert helt på bunnen. Dette vil spørre om returtidspunkt, med akkurat nå ferdig utfylt.

Infoskjermvisning

Det er en spesialvisning designet for å vises på infoskjermer. Det finnes ingen link til dette, men det kan aksesseres hvis du kjenner URL-en. Stien er /utlan/wide/<location ID>, hvor <location ID> er valgfri, og kan være en lokasjons numeriske ID, f.eks. 1

PLB-er

Personal Locator Beacons (PLBs) er del av sikkerhetsutstyret hos IMR. Noen båter har permanente PLB-er, og vi har også portable PLB-er man kan ta med seg. Når man registrerer et utlån velger man hvilken PLB man har med seg, eller ingen. Om dere ikke bruker PLB-er, kan denne delen av applikasjonen ignoreres.

Sikkerhet

Applikasjonen er designet for å være lett å bruke. Det er derfor ikke nødvendig å logge inn for å bruke den. Når man registrerer et utlån, må man oppgi en PIN-kode på 4 siffer. Denne sendes på SMS til båtfører, og på mail til kontaktpersonen. For å endre eller avslutte utlånet, må denne PIN-koden oppgis. Når man har skrevet inn en PIN, vil denne lagres i en cookie, så man trenger ikke oppgi den igjen om man ikke skal endre et utlån med en annen PIN. Administratorer trenger ikke oppgi PIN.

Registrering av nye båter, PLB-er, brukeradministrasjon og endring av innstillinger krever at man er logget på som administrator.

Oppgradering

Om du har klonet dette repositoriet og kjører applikasjonen fra klonen, vil en oppgradering være så enkelt som git pull, pluss å kjøre et eventuelt migrasjonsskript dersom det er endringer i databasen. Husk å merge filer du selv har endret skikkelig, som f.eks. app/Config/core.php og app/webroot/vaktinstruks.html

Om du ikke kjører applikasjonen fra en klone av repoet, må du finne ut hvilke filer som har endret seg. I Linux kan dette gjøres med kommandoen diff -qr fieldwork/Application/ /path/to/installation/. Dette gir en liste over hvilke filer som eksisterer bare i den ene eller andre mappen, og om en fil er forskjellig i de to mappene. F.eks:

Bare i fieldwork/Application/: someFile.txt
Bare i /path/to/installation/: otherFile.txt
Filene /path/to/installation/app/Config/core.php og fieldwork/Application/app/Config/core.php er ulike

Kopier nye/endrede filene fra den nye versjonen til den gamle, og slett filer som bare ligger i den gamle. Husk at enkelte filer, som f.eks. konfigurasjonsfilene core.php og database.php SKAL være forskjellige, så ikke overskriv de.

Migrasjonsskript

I mappen dbmigration ligger det noen SQL-script. Disse er navngitt etter hvilken versjon de migrerer fra og til, f.eks. 1.0.0 - 1.1.0.sql, som migrerer fra v1.0.0 til v1.1.0. Det kan være lurt å sjekke disse scriptene før du kjører de, for å være sikker på at de ikke overskriver eller endrer noe du selv har endret i systemet.

Hvis du har hoppet over noen versjoner, kjør scriptene i riktig rekkefølge.

Hvis det ikke er et script som migrerer til din versjon, har det ikke vært noen databaseendringer. Migrer da til nærmeste lavere versjon enn den du kjører