Dokumentasjon

OBS denne noden inneholder info om en utgave av kortsys som ikke lenger er i bruk, kortsys2 brukes istedet.

Kortsys - backend

Innholdsfortegnelse

1. Hva er kortsys?
2. Hvordan virker det?
2.1 Beskrivelse av inndata
2.2 Beskrivelse av utdata
3. Implementasjon
4. Feilsøk
5. Løpende info
6. Bulk-script

Kortsys er navnet på systemet som tar seg av konverteringen av aktive gjengmedlemmer fra medlemskortdatabasen til RITA nøkkelkortsystem. RITA (innkjøpt programvare, win32-plattform) baserer seg på en btrieve 6.15 databasemotor som datakilde. Dette er en proprietær databasemotor som det ikke har lyktes å skaffe odbc el.lign. driver til. Som en følge av dette, må man benytte seg av en egen modul levert av produsenten for å få til importering og eksportering av data. Denne modulen heter "Data INN/UT".

Våre data kommer fra den sentrale medlemsdatabasen til Samfundet. I denne databasen ligger primært alle registrerte medlemmer på huset, og i tillegg informasjon og historikk om gjengmedlemsskap / verv.

2. Hvordan virker det?

Systemet kan beskrives med følgende tegning.

MedlemsDB er basisen til hele systemet. Systemets behandlingsdel er ment å gå periodisk. Denne jobben henter ut endringer, behandler dem og genererer en utkø. Denne ukøen blir så behandlet av utdata-modulen, som genererer tekstfilene som RITA kan importere.

2.1 Beskrivelse av inndata

Inndata hentes fra tabellene i medlemsdatabasen.

Ett view, med navn 'gjengmedlemskap' er basisen til hele systemet. Dette viewet viser en liste over alle medlemmer (medlemsnr) som er medlem av en gjeng. Viewet er basert på tabellene historikk, kort og medlem.

2.2 Beskrivelse av utdata

Utdata fra systemet er basert på RITA's data inn/ut -modul krav. For at automatisk importering skal fungere i RITA trengs det to filer. En som beskriver egenskaper til kort, rettigheter og operasjoner mot disse. Den andre beskriver personer som skal importeres i systemet.

Vi tror kort.csv og person.csv er representative og kanskje kan brukes. Dataformatet er kommaseparert.

person.csv

medlemsnr: medlemsnummer på kortholder. "personid" i RITA.
avdeling: "medlem" brukes
etternavn:
fornavn:
ansattnummer: Satt til medlemsnummer.
telefonnummer: ikke oppgitt
fri1: epostadresse på medlem
fri2: Brukes ikke.
fri3: Brukes ikke.
fri4: Brukes ikke.
bildefil: Brukes ikke.
kommentar: "vidar er sexy" funker

kort.csv

medlemsnr: medlemsnummer på kortholder. Dette brukes som "personid" i RITA.
gruppe i rita: Gruppe i RITA. Gjeng + Verv må mappes til et gruppenavn.
fradato: Datofelt på formen dd.mm.yyyy
tildato: – "" –
klokkeslett, fra: klokkeslett. Satt til 00:00
klokkeslett, til: –""–
statuskode: Kode som beskriver typen forespørsel.
kortnummer: Nummer på gjengkortet, eller medlemsnr hvis medlemskort brukes som økkelkort. (UKA + ISFiT)
pinkode: Pinkode på kortet
kortversjon: Satt til 0.
systemkort: Satt til 0.
lokalt kort: Satt til 1.
sperret: Satt til 0.

3. Implementasjon

Systemet er implementert i scriptspråket PHP. Selv om dette språket i utgangspunktet ikke akkurat er egnet til dette, ble valget tatt pga. portabilitet og kontinuitet. Det er bedre å skrive kode i ett enkelt scriptspråk som blir vedlikeholdt, enn vanskelig kode som ingen klarer å sette seg inn i.

Vi har lagd disse tabellene i databasen 'medlemsdb' i postgresql-serveren på cirkus.samfundet.no.

RITA_PERSON = (medlemsnr + tidspunkt + endret)
RITA_GRUPPE = (medlemsnr + gruppe + tidspunkt + endret)
RITA_DO = (medlemsnr + gjeng + fradato + tildato + kortnr + pin + status + queue + fornavn + etternavn + epost)
RITA_LOGG = (innlegg + tidspunkt + enhet + notis + statuskode)

I tillegg har man view'en RITA_UTDATA som kobler data i RITA_DO med data fra gjengkort og medlem. (supplemerende data)

RITA_UTDATA = (fornavn + etternavn + epost + medlemsnr + gjeng + fradato + tildato + status + queue + kortnr + pin)

Person-modul

Hvis noen går inn og oppdaterer navnet sitt, eposten sin eller pinkoden sin på medlemssidene fører en trigger i postgresql til at personen blir satt som endret i rita_person -tabellen. Modulen fører til at alle grupper som denne personen (medlemsnummeret faktisk) er medlem av og notert eksisterende i rita, blir satt som endret. Samtidig blir det lagt en beskjed i rita_do at brukeren skal slettes med alle kort fra Rita. Med ett hakk høyere kø-nummer blir han/hun/det så lagt inn igjen.

Denne modulen bruker rita_person, rita_gruppe, gjengmedlemskap og rita_do tabellene, og gjør endringer på alle unntatt gjengmedlemskap.

Prejob-gruppe-modulen

Utfører vedlikeholdsarbeid på rita_gruppe -tabellen. Går gjennom gjengmedlemskap (autorativ kilde på Viktige Ting[tm]) og legger til eventuelle manglende grupper på hvert medlem. Endret -bit settes til sann på disse. Samtidig blir eventuelle overflødige grupper (gruppe i HAR som ikke er i SKAL, med andre ord) satt som endret for behørig behandling senere.

Denne modulen utfører kun endringer på rita_gruppe -tabellen, og krever at gjengmedlemskap eksisterer for å kunne kjøre.

Mainjob-gruppe-modulen

Gjør selve jobben med gruppene i rita. Tar for seg alle poster i rita_person som har endret satt, og sjekker dem opp mot gjengmedlemskap. Alle grupper blir først bedt slettet. Hvis så gruppen er legitim, dvs den fantes i gjengmedlemskap, så legges den til igjen. Hvis gjengmedlemskapet f.eks. er gått ut, legges den ikke til igjen. I tillegg slettes da også posten fra rita_gruppe for å spare prejob-modulen for litt overflødig arbeid. Til slutt settes endret-bit tilbake til false.

Denne modulen utfører endringer på rita_gruppe. Den krever at rita_do og gjengmedlemskap eksisterer.

Utdata-modul

Denne modulen er etter den tenkte arkitekturen ment å gå på selve nøkkelkortmaskinen. Dette fører til en litt renere og uavhengig operasjon. Dette er dog ikke tilfellet for tiden, så det får vi se etterhvert. Det denne modulen gjør er å danne filene kort.csv og person.csv ut fra tabellen rita_do (egentlig en view, men det spiller ingen rolle) i postgresql. Modulen vil avbryte hvis den finner ut at en tidligere kjøring var ufullstendig. Man vil da måtte gå manuelt inn og kontrollere at alt er på plass og slette lockfilen i /tmp/. Mulige grunner til at dette kan skje er omstart av maskiner / feil i kode / avbrudd av andre grunner. Den vil også avbryte hvis kort.csv og person.csv finnes fra før. Ettersom man ønsker å begrense antall feilmeldinger systemet produserer, vil det ikke bli lagd feilmeldinger før kort.csv eller person.csv er 6 timer gamle. Hvis importprogrammet hos rita ikke har gått på seks timer, er det sjense for at det kanskje må fikses manuelt.

Denne modulen krever at gjengmedlemskap, rita_mapping, rita_logg, rita_utdata og rita_do eksisterer. Den utfører endringer på rita_logg, rita_utdata og rita_do.

4. Feilsøk

Hvis ting ikke fungerer.

1. Lokaliser problemet.

Er det problem med behandleren eller utdata-modulen?

Blir tabellen rita_do gjort noe med? Hvis denne ikke blir tømt, er det utdata-modulen som ikke går.
løsning: kontroller nøkkelkort pc-en. Blir utdatafilene behandlet hvert kvarter? Er maskinen i orden? Kjører alle programmene? Går utdata.php i crontab som rita-brukeren?

Ved feil på behandleren, kjør hver bit manuelt og se etter feilmeldinger. Rekkefølgen er som følger.

./personer.php
./prejob-gruppe.php
./mainjob-gruppe.php

Utføres alle uten feil? Eksisterer det gamle lockfiler på disk?

2. Fiks problemet

Feilsjekk ut fra egen vilje / kunnskap og punktene under 1.

3. Legg ut en feilrapport

Dette for at andre slipper å gjøre samme feilsøkingen senere.

Følgende punkter kan være med;

hva slags feilmelding / feilsituasjon du opplevde
hva den åpenbare grunnen så ut til å være
hva den reelle grunnen til problemet var
hva du gjorde for å finne ut hva den reelle grunnen var
hvordan du løste problemet når du hadde funnet feilen

Dette kan gjøres så enkelt som å sende en epost til egnet forum, (kort@samfundet, itk@samfundet.no e.l.) eller å kanskje skrive en litt mer utført sak i html og legge ut på webben. Web er helt klart å foretrekke, pga det er enklere å indeksere / søke i for ettertiden.

5. Datakatalog

RITA_PERSON = (medlemsnr + tidspunkt + endret)
medlemsnr = char(6)
tidspunkt = timestamp default now()
endret = boolean default false

RITA_GRUPPE = (medlemsnr + gruppe + tidspunkt + endret)
medlemsnr = char(6)
gruppe = char(6)
tidspunkt = timestamp default now()
endret = boolean default false

RITA_DO = (medlemsnr + gjeng + fradato + tildato + kortnr + pin + status + queue + fornavn + etternavn + epost)
medlemsnr = char(6)
gjeng = char(2)
fradato = timestamp default now()
tildato = timestamp default now()
kortnr = char(6)
pin = char(4)
status = char(1)
queue = integer default 0
fornavn = text
etternavn = text
epost = text

RITA_LOGG = (innlegg + tidspunkt + enhet + notis + statuskode)
innlegg = teller primærnøkkel
tidspunkt = timestamp default now()
enhet = text
notis = text
statuskode = integer

Utdatamodulen til kortsys

Består av

~rita/kortsys/utdata.php samt lockfiler i /tmp/, se kildekoden.

Gjør

Henter ut de endringer som er fremst i endringskøen, og skriver disse til to tekstfiler på disken.

Kjøres:

På cirkus, fra crontab som bruker "rita".

Resultat

~rita/kortsys/utdata/kort.csv og
~rita/kortsys/utdata/person.csv

Kommentarer

Hvis køen er tom, legges det til en dummy-post i kort.csv for at rita ikke skal stoppe opp med "inndatafilene er tomme!" -melding. Denne legger til "bare bakdør" -gruppen på et ikkeksisterende kort, og blir forkastet av importprogrammet.

Endre passord på medlem (av lkarsten)

Det forekommer fra tid til annen, først og fremst like før fristene på gamle oblater / medlemskort m.v, at vi får mail fra ett stakkars desperat medlem som har glemt passordet sitt. (eller brukernavnet, for den saks skyld.) Dette skyldes som oftest at det ble registrert i fylla, og at folk er elendige til å huske. (tror jeg da)

Uansett. Framgangsmåte;

koble til postgresql. psql -U <brukernavn> medlemsdb
Hvis medlemmet har oppgitt medlemsnummeret sitt, søk medlemmet fram. select * from medlem where medlemsnr = '<medlemsnr>';
Hvis medlemmet har oppgitt idkortnummer, må du gå litt annerledes fram. select * from gjengkort where kortnr = '<idkortnr>'; Da får du opp hvilket medlemsnummer personen har. Slå dermed opp medlemmet med linjen gitt for å søke på medlemsnr.
Hvis medlemmet har mistet medlemskortet sitt, vil hun få utstedt ett nytt medlemskort. (for a decent fee, at least). Dette har ett nytt kortnummer, men medlemmet vil fremdeles ha sitt gamle medlemsnummer. Hvis de to forrige feiler stygt, kan du prøve å søke på aktivt kortnummer i stedet. select * from medlem where kortnummer = '<kortnr>';
Hvis alt annet feiler, kan du forsøke å slå opp medlemmet på fornavn / etternavn. Dette kan gjøres f.eks. slik: select * from medlem where fornavn like '%sse' and etternavn like '_arstensen'; Som du sikkert forstår matcher _ ett vilkårlig tegn, og % fra null til mange vilkårlige tegn. (den vil f.eks. matche Lasse Karstensen, som forhåpentligvis meningen var). Det er et poeng å erstatte forbokstaver med wildcards som nevnt, ettersom søket er case-sensitivt.
Når du så har funnet medlemmet via en av de overstående operasjonene, er det først og fremst på tide å kontrollere at den som spør har oppgitt rett medlemsnummer. Kanskje husker man litt feil, og vips blir det totalt gærnt. Svært lett å forglemme, og litt irriterende når noen blingser og resetter feil medlem.
Så til passordskifte. Vi benytter oss av krypterte passord. Av historiske årsaker eksisterer dog også klartekstpassord. Dette skal vi benytte. Hvis man setter det krypterte passordet til en tom streng, brukes klartekstpassordet. Dette gjøres slik: update medlem set passord = '<passord>' and password_md5 = '' where medlemsnr = '<medlemsnr>'; Hvor <passord> er det nye passordet. Legg spesielt merke til at man setter md5-passord til en tom streng, ellers vil det ikke virke.
Det du nå gjør, er å svare på henvendelsen du fikk. Ett poeng her kan være å nevne både brukernavnet og passordet til medlemmet. Samtidig har du lyst til å gjøre oppmerksom på at hun bør skifte passordet sitt til noe hun husker snarest. Hvis det er en epost, kan det være greit å cc'e til kort@samfundet.no og kanskje itk@samfundet.no, slik at de andre ser at forespørselen er besvart.

Boote kortoggodt (igjen av lkarsten)

Ting som kan være greie å vite hvis du skal boote kortoggodt.

Vær forsiktig når du kjører ned programmene. Lopcom0x klarer du sjelden å bli kvitt uansett, men prøve kan du jo alltids. Ta databasen til slutt, er også ett stalltips. Ergo, trykk "avslutt" på dialogboksen du får opp når du vil avslutte ritaprogrammene.
start på nytt, dette kan kanskje ta sin tid.
Når maskinen kommer opp, vil den be om innlogging. Slik saken er nå er maskinen medlem av "samfundet"-domenet. Der har man en bruker ved navn "rita" og ett gitt passord. Logg inn som denne.
Sjekk at "Regional settings" på kontrollpanelet er satt til norsk, ellers vil datoformatet på importen bli feil. Dette kan du også kontrollere ved å se på klokken nede i høyre hjørne. Hvis det står f.eks. 18:56 er det bra. Hvis det står 06:56PM er det ubra. Da må du endre i kontrollpanelet.
Kontroller at H: ble riktig oppmontert. (skal gå automatisk) Der skal katalogen H:\kortsys\ finnes, forhåpentligvis.
Start Rita. Start -> Programs -> Rita Access Control v2.4 -> Rita Main Program.
Logg inn med et brukernavn / passord du har tilgang på. ITK har ett, KK har ett annet. Slike ting administreres for tiden av John Kristian Evjen på evjen@stud.ntnu.no.
La programmet starte opp. Det kan hende du får noen feilmeldinger på lopcom02, det er ikke så farlig. (noen har lekt med oppsettet) Bare trykk avbryt. Hvis du derimot får to slike feilmeldinger, kan det være verdt å sjekke at ledninga mot undersentralene står i og i rett port.
I Rita-menyen, velg "Moduler" og "Data Inn/Ut"
Hent opp "Import" på menylinjen når programmet har startet. I menyen velger du "Automatisert". Det dukker da opp en ny boks med endel felter som skal fylles ut. Den kan se f.eks. slik ut:
Det viktige her er pathen til person og gruppefilene, hvor lenge mellom hver import og at den skal slette filene når importen er ferdig.
Kjør opp loggvinduet med å trykke på Loggvindu -> Vis Logg på menylinjen.
Trykk "OK" på automatisert-boksen for å snurre i gang importeringen.
Litt viktig: Når du trykker OK først, vil en import gå med en gang. I tillegg til dette er det litt viktig å huske på at "15 minutter mellom hver import" vil si kvart over, halv og kvart på. Ikke 15 minutter relativt til når du startet den.
Ferdig! Den automatiserte importeringen skal nå være operativ. Sjekk loggvinduet etter feilmeldinger. At importfilene ikke finnes når du starter den er greit, men repeterende beskjeder om feil bør kanskje sjekkes ut.

Løpende info

En statusside finnes på http://www.samfundet.no/~rita.

Bulk-script

I ~rita/vedlikehold/ finnes det noen script for bulkoppdateringer av medlemsdatabasen.

Dette er spesielt nyttig ved f.eks. slutten av en uke, når en haug med lusere (local users, altså) skal frarøves tilgang.

Lenker: Start, arkiv, atir, gammel dokumentasjon, historie, kortsys med rita, kortsys2, medlemsdb2oversikt