====
Orka
====

Orka je referentna implementacija klijenta za Web servise univerziteta. 
Koristi se za dostavljanje podataka od strane visokoškolskih ustanova 
(fakulteta i instituta) Rektoratu univerziteta. 

Dodatno, Orka ima mogućnost eksportovanja rang lista za prijemni 
ispit, podataka o nenastavnom osoblju i podataka o istraživačkom 
osoblju. Ulazni podaci moraju biti u Excel formatu i to upravo onakvom 
kakvi su dati u direktorijumu "excel". 


Softverski zahtevi
------------------

- Java 6 SE (JRE ili JDK) ili novija verzija.


Opis
----

Podatke koje Orka dostavlja putem web servisa je potrebno pripremiti u 
XML fajlu. 

XML fajl može biti dva tipa:

1. Inkrementalni eksport podataka
2. Kompletan eksport podataka

Inkrementalni eksport podataka predstavlja sekvencijalni skup 
instrukcija koje treba izvršiti da bi se podaci koji su ranije poslati 
bili sinhronizovani na novo stanje. Drugim rečima, inkrementali eskport 
podataka mora da sadrži sve one instrukcije (kreiranje novih zapisa, 
menjanje postojećih zapisa, brisanje zapisa) koje su se desile od 
prethodnog slanja podataka. 

Zbog toga svaki zapis u inkrementalnom eksportu podataka ima oznaku tipa 
akcije (insert, update, delete). Za pimer pogledati fajl 
xml-data/increment.xml. Sve instrukcije u inkrementalnom eksportu će 
biti izvršene u okviru iste transakcije. Ukoliko dođe do greške 
prilikom izvršavanja, podaci će biti vraćeni u stanje kao pre 
početka slanja inkrementalnog eksporta. 

Kompletan eksport podataka predstavlja trenutnu sliku svih podataka koji 
se dostavljaju. On za razliku od inkrementalnog eksporta ne sme imati 
niti jednu oznaku akcije (i ni jedan <Delete> tag), jer ne predstavlja 
sekvencijalni skup instrukcija koje treba izvršiti, već predstavlja 
sve podatke koji se eksportuju. Za primer kompletnog eksporta pogledati 
fajl xml-data/kumulativniPodaci.xml. 

Kompletan eksport podataka može sadržati objedinjene sve potrebne 
podatke, ili neki podskup potrebnih podataka. Primer podskupa podataka 
su: podaci o nastavnicima, podaci u jednom upisnom roku na prijemnom 
ispitu, podaci o studijskim programima i slično. Razlozi za 
eksportovanje podskupa podataka su dvojaki: sa jedne strane nekada su 
izvori podataka iz kojih se eksportuje XML nezavisni (tipično: odvojen 
softver za kadrovsku od softvera za studentsku službu), a sa druge 
strane nekada institucije želje da šalju različite podatke 
različitom dinamikom. Za detalje pogledati poglavlje "Slanje podskupova 
podataka". 

Validnost XML fajla (bilo da se radi o inkrementalnom eksportu ili 
kompletnom eksportu) se proverava na osnovu propisane XSD šeme. 


Upotreba
--------

Orka se može koristiti za:

1. Validaciju XML fajla sa potrebnim podacima 
   (opcija -validate)
  
2. Testiranje konekcije prema Web servisima univerziteta 
   (opcija -test)
   
3. Slanje kompletnog eksporta podataka posredstvom Web servisa 
   (opcija -bulk)
   
4. Slanje inkrementalnog eksporta podataka posredstvom Web servisa 
   (opcija -increment)
   
5. Preuzimanje kompletnog eksporta podataka posredstvom Web servisa 
   (opcija -fetch)
   
6. Generisanje svih otključanih diploma 
   (opcija -genDipl)
   
7. Proveru pripreme za štampu i preloma diplome
   (opcija -dipl)

Prilikom svih komandi koje koriste Web servise kao kanal komunikacije, 
moguće je zadavanjem opcije -server, izabrati na koji tačno od 
predefinisanih Web servis konfiguracija se šalju podaci. Konfiguracije 
su date u folderu conf. Između ostalog, moguće je zadati sledeće 
konfiguracije: 

-server pixy        -- Produkcioni server Univerziteta u Beogradu 
                       (default)
                       
-server unitest-ng  -- Testni server Univerziteta u Beogradu, sa 
                       najnovijom verzijom aplikacije. Ispravke 
                       problema se prvo instaliraju na ovom serveru, a 
                       tek kasnije na produkcionim serverima.

-server ns          -- Produkcioni server Univerziteta u Novom Sadu

-server ni          -- Produkcioni server Univerziteta u Nišu

-server kg          -- Produkcioni server Univerziteta u Kragujevcu


Ukoliko je na serveru došlo do greške, Orka će podrazumevano ispisati 
samo prvi nivo poruke o grešci. Za pomoć pri otkrivanju grešaka koje 
su se desile na serveru, kao i grešaka koje su se desile na klijentu, 
preporučeno je da se koristi opcija -debug. Dodatno, ukoliko je 
potreban detaljniji ispis na konzoli o tome šta Orka trenutno radi, 
može se koristiti opcija -verbose. 


1. Validacija generisanog XML fajla sa potrebnim podacima
---------------------------------------------------------

U poddirektorijumu xml-data se nalaze primeri XML fajlova:

a. kumulativniPodaci.xml -- kao primer kompletnog eksporta podataka
b. increment.xml -- kao primer inkrementalnog eksporta podataka

Fajl kumulativniPodaci.xml sadrži primer kompletnog eksporta podataka o 
nastavnom procesu (nastavnici, studenti i slično), dok fajl 
increment.xml sadrži primer inkrementalnog eksporta podataka u odnosu 
na podatke u fajlu kumulativniPodaci.xml. 

Potrebno je generisati ekvivalentan fajl (verzija a ili b) koji sadrži 
validne podatke sa visokoškolske ustanove. U komentaru fajla 
kumulativniPodaci.xml možete naći opis podataka koje je potrebno 
dostaviti. 

Validnost fajla može se proveriti zadavanjem komande:

orka -validate -xmlFile filename.xml

"filename.xml" je ime XML fajla koji je potrebno validirati, a koje se
zadaje apsolutnom putanjom, ili relativnom putanjom u odnosu na tekući 
direktorijum. U slučaju već postojećeg fajla komanda za validaciju je:

orka -validate -xmlFile xml-data/kumulativniPodaci.xml

Podrazumevano ime fajla je xml-data/kumulativniPodaci.xml, pa je 
dovoljno i samo:

orka.bat -validate


Iako se koristi ista XSD šema za validaciju i kompletnog i inkrementalnog 
eksporta, postoje određene razlike između ova dva fajla:

a. Inkrementalni fajl mora da sadrži atribute "action", i može da sadrži
tagove "delete".
b. Sa druge strane komletan eksport ne sme da sadrži atribute action, 
niti tagove "delete". 



2. Testiranje konekcije prema web servisima univerziteta
--------------------------------------------------------

Konekcija prema Web servisu univerziteta može se testirati zadavanjem
komande:

orka -test

Slanjem nekoliko testnih podataka (IP adresa i lokalno vreme mašine sa
koje se pokreće Orka) proveriće se dostupnost Web servisa preko HTTPS-a, 
prenos UTF-8 kodiranog ćiriličnog teksta i podaci o tome biće ispisani 
na konzoli.


3. Slanje kompletnog eksporta podataka posredstvom Web servisa 
--------------------------------------------------------------

Po generisanju kompletnog eksporta podataka u XML (i njegovoj 
validaciji), podatke možete poslati komandom 

orka -bulk -xmlFile filename.xml

Svi podaci biće poslati korišćenjem kredencijala koje ovlašćeni 
predstavnici fakulteta dobijaju od Rektorata. Korisničko ime, lozinka i 
akronim fakulteta je neophodno uneti u XML fajl 
xml-data/kredencijali.xml. Korisničko ime i lozinka moraju biti uneti 
latinicom i ne smeju sadržati dijakritičke znakove (š, č, ć i 
slično). Akronim fakulteta može biti unet ili latinicom ili 
ćirilicom, ali ukoliko sadrži dijakritičke znakove oni moraju biti 
ispravno uneti (npr. ŠF za Šumarski fakultet). 

XML entiteti koji se odnose na pojedinačne zapise u bazi podataka, 
moraju u XML fajlu da budu navedeni u redosledu od nezavisnih prema 
zavisnim. 

Svi podaci u kompletnom eksportu će biti poslati u jednom requestu i u 
okviru jedne transakcije.

Prilikom svakog slanja kumulativnih podataka na server, Orka pokušava 
da pošalje samo neophodne podatke, tj. razliku u odnosu na prethodno 
slanje. Drugim rečima, prilikom prvog slanja podataka biće poslati svi 
podaci, a kopija XML fajla sa kompletnim eksportom podataka će biti 
sačuvana u direktorijumu xml-data-sent. Prilikom svakog sledećeg 
slanja podataka, Orka će pokušati da izračuna razliku u odnosu na 
prethodno slanje, poređenjem sa fajlom koji se sačuvan u folderu 
xml-data-sent. Ukoliko takav fajl nije nađen, Orka će povući sa 
servera ranije poslate podatake, pa onda uraditi poređenje. Čak i 
prilikom prvog slanja podataka, Orka pokušava da povuče sa servera 
ranije poslate podatke i u xml-data-sent direktorijum snima suštinski 
prazan XML fajl.



4. Slanje inkrementalnog eksporta podataka posredstvom Web servisa 
------------------------------------------------------------------

Po generisanju inkrementalnog eksporta podataka u XML (i njegovoj 
validaciji), podatke možete poslati komandom 

orka -increment -xmlFile filename.xml

Podrazumevano ime fajla uz opciju -increment je 
xml-data/increment.xml.

Slično kao što je objašnjeno u tački 3, potrebno je popuniti fajl 
xml-data/kredencijali.xml.

Uz opciju -increment nije moguće koristiti opciju -bulk.

XML entiteti koji se odnose na pojedinačne akcije nad redovima u 
bazi podataka (create, update i delete), moraju u inkrementalnom 
eksportu imati validan redosled u smislu mogućnosti da se navedenim
redosledom izvrše sve zadate komande bez narušavanja referencijalnog
integriteta. 


5. Preuzimanje kompletnog eksporta podataka posredstvom Web servisa 
-------------------------------------------------------------------

Svi poslati podaci u određenom prostoru imena mogu se preuzeti pomoću 
komande: 

orka -fetch [namespace]

Preuzeti podaci biće snimljeni u direktorijumu xml-data-sent.

Pomoću opcije -fetchIdInstitucija true/false, moguće je kontrolisati 
da li se u preuzetim podacima treba pojaviti polje idInstitucija ili ne. 
Default je false, kada se polje idInstitucija ne pojavljuje. 


6. Generisanje svih otključanih diploma
---------------------------------------

Web servisi univerziteta nude mogućnost pokretanja generisanja svih 
otključanih diploma pomoću komande: 

orka -genDipl true

Ovo generisanje se podrazumeva ukoliko su zadate opcije -bulk ili 
-increment. Drugim rečima, komande: 

orka -bulk
orka -increment

su ekvivalentne, respektivno, komandama:

orka -bulk -genDipl true
orka -increment -genDipl true

U određenim situacijama potrebno je poslati podatke bez ponovnog 
generisanja diploma. Tipičan slučaj korišćenja je kada se šalju 
podaci iz više fajlova. Slanje podataka bez generisanja diploma se 
može uraditi komandama: 

orka -bulk -genDipl false
orka -increment -genDipl false


7. Provera pripreme za štampu i preloma diplome
-----------------------------------------------

Kada fakultet pošalje zahtev za štampanje diplome, pre finalnog 
štampanja, moguće je pregledati/proveriti podatke koji će biti 
štampani u toj diplomi. Orka se, u tom slučaju poziva sa dva 
parametra: 

orka -dipl D -format F
 
gde je:
 
D -> lokalni id zahteva za izdavanje diplome
F -> format u kom ce biti isporucena diploma fakultetu,
    - moze imati vrednosti txt, pdf ili html
    
Primeri korišćenja:

orka -dipl 5004 -format pdf
orka -dipl 5004 -format txt
orka -dipl 5004 -format html

Rezultat ovakvog pozivanja orke su dva fajla: diploma-5004.pdf i fajl 
dodatak-5004.pdf (u druga dva slučaja ekstenzije su .txt i .html), koji 
prikazuju približnu pripremu za štampu za odgovarajući zahtev (id 
zahteva 5004). Ako je u zahtevu navedeno da se štampa i čisto engleska 
diploma pored navedenih datoteka rezultatu se dodaju 
diploma-5004-engleski.pdf i dodatak-5004-engleski.pdf. Fajlovi će 
biti snimljeni u poddirektorijum xml-data. 

 
Takođe je moguće popuniti fajl sa listom zahteva, tako što se u 
svakom redu navede po jedan zahtev. 

Orka se, u tom slučaju poziva sa dva parametra:

orka -diplFile D -format F
 
gde je:

D -> lokacija fajla u kome se nalazi spisak zahteva za izdavanje diploma
F -> format u kom ce biti isporucena diploma fakultetu,
    - moze imati vrednosti txt, pdf ili html
    
Primer korišćenja:

orka.bat -diplFile xml-data\zahtevi.list -format pdf

Ako je sadržaj fajla xml-data\zahtevi.list:
5003
5004

Rezultat ovakvog pozivanja su četiri fajla: diploma-5003.pdf, 
dodatak-5003.pdf, diploma-5004.pdf i dodatak-5004.pdf, koji prikazuju 
približnu pripremu za štampu za odgovarajuće zahteve (id zahteva 5003 
i id zahteva 5004). Ako je u zahtevima navedeno da se štampa i čisto engleska 
diploma pored navedenih datoteka rezultatu se dodaju diploma-5003-engleski.pdf, 
dodatak-5003-engleski.pdf, diploma-5004-engleski.pdf, dodatak-5004-engleski.pdf. 
Fajlovi će biti snimljeni u poddirektorijum xml-data. 


Slanje podskupova podataka
--------------------------

Praksa pokazuje da pojedine institucije imaju mogućnost da eksportuju 
sve potrebne podatke u jedan objedinjeni XML fajl, dok druge imaju 
potrebu da kreiraju različite XML fajlove, sa različitim podskupovima 
podataka. Ovi podskupovi mogu biti iz različitih izvora podataka 
(informacionih sistema) ili iz samo jednog. Orka nudi osnovnu podršku 
za slanje podataka iz više izvora, kao i njihovo eventualno ukrštanje. 

Svaki od podataka koji fakultet šalje se referencira lokalnim 
identifikatarom. Na primer, svaki student ima svoj lokalni identifikator 
u informacionom sistemu fakulteta (idStudentLocal). Ovi lokalni 
identifikatori se takodje referenciraju u tabelama u kojima je to 
potrebno (na primer, student se referencira u tabeli ocena). 
Identifikatori mogu sadržati i oznaku prostora imena (eng. namespace) u 
uglastim zagradama. Primera radi, validan identifikator bez namespace-a 
je "1234", a sa namespace-om "[KS]1234". Zadavanje identifikatora bez 
namespace-a, povlači pripadanje tog identifikatora podrazumevanom 
prostoru imena (eng. default namespace). 

Na ovaj način je moguće slanje različitih podskupova podataka, gde 
svaki podskup označava lokalne identifikatore sopstvenom oznakom 
namespace-a. Pri time se treba pridržavati pravila "jedan XML fajl -- 
jedan namespace". Primera radi: 

1. podaci iz informacionog sistema studentskog odseka se mogu 
eksportovati u XML u default namespace-u (svi lokalni identifikatori i 
njihove reference u XML fajlu koji sadrzi podatke iz studentskog odseka 
nemaju oznaku namespace-a), a 

2. podaci iz informacionog sistema kadrovske službe se mogu 
eksportovati u namespace-u [KS] (svi lokalni identifikatori i njihove 
reference u XML fajlu koji sadrzi podatke iz kadrovske sluzbe moraju 
imati prefiks [KS]). 

Na ovaj način je moguće nezavisno slanje podataka iz dva međusobno 
disjunktna podskupa.


Međusobna zavisnost podataka iz više prostora imena
---------------------------------------------------

Ponekad je potrebno da su podaci iz različitih izvora međusobno 
referencirani. Na primer, ukoliko se nastavnici eksportuju iz 
informacionog sistema za kadrovsku službu, a podaci o studentima iz 
informacionog sistema za studentski odsek, potrebno je da nastavnici 
budu referencirani u angažovanjima i ocenama. 

U takvoj situaciji, pored uslova koji su dati u prethodnom poglavlju, 
potrebno je u XML eksportu podataka u kome se nalaze i ocene, za 
referencirane podatke iz kadrovske službe, dodati odgovarajući 
namespace. Primera radi: 

  <ocena>
    <idOcenaLocal>123</idOcenaLocal>
    <idDosijeLocal>234</idDosijeLocal>
    <idPredmetLocal>345</idPredmetLocal>
    <datum>2007-01-19</datum>
    <godinaStudijskogPrograma>1</godinaStudijskogPrograma>
    <ocena>9</ocena>
    <idNastavnikLocal>[KS]987</idNastavnikLocal>
    <espb>9.00</espb>
    <idIzbornostPredmeta>2</idIzbornostPredmeta>
  </ocena>

Reference idDosijeLocal i idPredmetLocal sadrže identifikatore iz IS 
studentskog odseka, dok se referenca idNastavnikLocal odnosi na 
identifikator IS kadrovske službe. 

Na ovaj način je moguće međusobno referenciranje podataka.

Ukoliko se podaci iz ova dva izvora sinhronizuju sa podacima koji su 
ranije poslati pomoću inkrementalnog eksporta podataka, nije potrebna 
nikakva sinhronizacija između jednog i drugog slanja. Drugim rečima u 
primeru se podaci iz studentske službe mogu slati potpuno vremenski 
nezavisno u odnosu na podatke iz kadrovske službe, na primer: 

orka -increment -xmlFile podaci-kadrovska-sluzba.xml
orka -increment -xmlFile podaci-studentski-odsek.xml


Ukoliko se podaci iz ova dva izvora podataka šalju pomoću kompletnog 
eksporta podataka, onda je potrebno koristiti opciju -bulk:

orka -bulk -xmlFile podaci-kadrovska-sluzba.xml
orka -bulk -xmlFile podaci-studentski-odsek.xml

Eksport podataka iz Excel fajlova
---------------------------------

U Orka paketu su dati i primeri rang lista, lista nenastavnog 
osoblja i lista istraživačkog osoblja, koji su priloženi u 
direktorijumu "excel". Pomoću skripte excel-export.bat moguća je 
konverzija ovih Excel fajlova u XML fajlove koji su u fromatu koji 
propisuje Univerzitet. 

Primer:

  excel-export excel\rang-lista.xls

Moguće je i navođenje više od jednog Excel fajla.

Eksportovane rang liste će imati prostor imena (namespace) koji 
identifikuje jedan upisni rok i vrstu studija. 

Da bi se smanjila mogućnost greške da se pošalju rang liste u nekom 
ranijem namespace-u, Orka će prijaviti grešku ukoliko se pokuša 
eksport podataka za godinu studija koja se razlikuje od godine iz 
sistemskog vremena. Primera radi, ako 15.6.2012. pokušate eksport 
podataka za rang listu iz 2011. dobićete poruku o grešci. Moguće je 
forsiranje eksporta pomoću parametra "-force" u komandnoj liniji, ali 
ovaj parametar treba koristiti sa oprezom. 
