Opetushallituksen (OPH) valtionavustusten hakemiseen, käsittelyyn ja myöntämiseen tarkoitetut palvelut.
Projekti koostuu kahdesta web-palvelusta: va-hakija ja va-virkailija. Näillä on omat Leiningen-projektit tämän git-repositoryn juurihakemistossa. Web-sovelluksien yhteinen koodi on Leiningen-projektissa soresu-form.
Tässä README:ssä on yleiskuvaus palveluista, lisää dokumentaatiota:
Hakija on käyttäjä, joka täyttää ja lähettää hakemuksen avoimeen avustushakuun. Kuka tahansa voi lähettää hakemuksen (ei autentikointia). Tähän käytetään va-hakija-sovellusta.
Virkailijan käyttöliittymässä (va-virkailija-sovellus) arvioidaan hakemuksia. Sovellukseen kirjaudutaan OPH:n CAS-palvelun (autentikointi) ja Käyttöoikeuspalvelun (autorisointi) kautta.
Käyttäjätyypit:
- Normaali (VA-käyttäjä)
- voi lukea kaikkia hakuja ja hakemuksia
- voi muokata niitä hakuja, joissa on esittelijä-roolissa
- voi arvioida niitä hakuja, joissa on arvioija-roolissa
- Admin (VA-pääkäyttäjä)
- voi lukea ja muokata kaikkia hakuja ja hakemuksia
Hakukohtaiset roolit:
- Esittelijä
- voi muokata hakua ja siihen saapuneita hakemuksia
- haun "vastaava"
- vastaa rahoituksen jakautumisesta hyväksyttyjen hakemuksien kesken
- Arvioija
- voi rajatusti muokata hakua: arvioi tiettyjä kohtia hausta ja voi muokata osia rahoituksesta
- tukeva rooli esittelijälle
Haun roolista huolimatta kuka tahansa VA-käyttäjä voi kommentoida hakemuksia.
Käsite | Kuvaus |
---|---|
Haku tai avustushaku | Mahdollistaa rahan jakamisen hakijoille. Avustushaulle tehdään lomake, joka julkaistaan. Hakija lähettää avustushakukohtaisen hakemuksen. |
Hakemus | Hakijan kirjoittama avustushakukohtainen anomus rahoituksen saamiseksi. |
Asianumero | Tunniste haun arkistointia varten. Usealla haulla voi olla sama asianumero. va-virkailija-sovellus lähettää haun (joka sisältää asianumeron) sähköpostilla kirjaamo.oph.fi:hin, jossa haut tulostetaan ja arkistoidaan. OPH:lla on suunnitteilla on ottaa käyttöön sähköinen arkistointi, jolloin asianumero tulisi hakuun automaattisesti integraation kautta. |
- Node.js
- npm
- Leiningen, versio 2.8.1
- Java SE Development Kit, versio 8
- PostgreSQL, vähintään versio 12.2
- GNU make, vähintään versio 3.81
Käytä OPH:n VPN:ää, jotta voit ladata tarvittavat jar-paketit OPH:n Artifactorystä.
Kehitystyössä hyödyllisiä työkaluja:
Projektin juurihakemistossa on Makefile
, jolla voi ajaa koko projektia koskevia yleisiä komentoja. Sen käyttöön on ohje:
make help
Juurihakemisto sisältää lein
-skriptin, jota voi käyttää Leiningenin
ajamiseen. Tämä takaa staattisen version käytön Leiningenistä.
ls -lA oph
drwxr-xr-x 26 username staff 884 Feb 17 09:46 postgres-data/
drwxr-xr-x 26 username staff 884 Feb 17 09:46 valtionavustus/
drwxr-xr-x 25 username staff 850 Feb 17 10:54 valtionavustus-secret/
Missä postgres-data
on data-hakemisto PostgreSQL:lle ja
valtionavustus
ja valtionavustus-secret
ovat projektin
git-repositoryt.
Docker-imagen luonti:
cd valtionavustus/script/postgres-docker
docker build -t va-postgres:12.2 .
Data-hakemiston luonti:
mkdir -p postgres-data
Tietokannan ajaminen Dockerissa:
run_database.sh
Tietokannan palauttaminen, esim Lammen backupista:
pg_restore --user va -h localhost -v --clean --if-exists --no-acl --no-owner --dbname va-dev ./valtionavustukset-2.backup
Huom: Linux-koneilla Postgres-komennot on helpointa ajaa postgres-käyttäjänä:
sudo -s -u postgres
Luo data-hakemisto:
initdb -D postgresql-data
Halutessasi aseta seuraavat tiedostoon postgres-data/postgresql.conf
,
jotta voit seurata tarkemmin mitä tietokannassa tapahtuu:
log_destination = 'stderr'
log_line_prefix = '%t %u '
log_statement = 'mod'
Käynnistä tietokantapalvelin:
postgres -D postgres-data
Luo käyttäjät va-hakija
ja va-virkailija
(kummankin salasana va
):
createuser -s va_hakija -P
createuser -s va_virkailija -P
Luo tietokanta nimeltään va-dev
:
createdb -E UTF-8 va-dev
Kun web-sovellus käynnistyy, ajaa se tarvittavat migraatiot tietokantaan.
Tietokannan saa tyhjennettyä ajamalla:
dropdb va-dev
createdb -E UTF-8 va-dev
Asenna kaikki frontendin buildaamiseen käytetyt npm-moduulit, projektin juurihakemistossa:
make npm-clean npm-install-modules
Käynnistä frontendin assettien buildi webpackilla. Tällöin webpack generoi selaimen käyttämät JavaScript-tiedostot. Webpack buildaa tarvittaessa uudelleen, jos lähdekoodi yllä olevissa hakemistoissa muuttuu:
cd va-hakija
npm run build-watch
cd va-virkailija
npm run build-watch
Frontendin tuotantoversion buildi, projektin juurihakemistossa:
make npm-build
Kaikkien frontendin yksikkötestien ajo, projektin juurihakemistossa:
make npm-test
Varmista, että JAVA_HOME
-ympäristömuuttuja osoittaa haluamaasi
JDK:hon.
Asenna ensin backendien riippuvuudet paikalliseen
~/.m2
-hakemistoon. Tarvitset tätä varten OPH:n VPN:n, koska osa
riippuvuuksista on OPH:n Artifactoryssä. Projektin juurihakemistossa:
make lein-clean lein-install-jar-commons
Backendien ajaminen Leiningenissa tapahtuu käyttämällä
trampoline
-komentoa, jotta JVM ajaa shutdown-hookit, joissa
vapautetaan resursseja (uberjarin kautta ajaessa ongelmaa ei ole):
cd va-hakija
../lein trampoline run
cd va-virkailija
../lein trampoline run
Backendin käynnistys ajaa tietokannan migraatiot automaattisesti.
Va-hakijan tai va-virkailijan käynnistys lein trampoline run
:lla
saattaa epäonnistua:
Exception in thread "main" java.lang.IllegalArgumentException: No matching ctor found for class java.net.Socket, compiling:(/private/var/folders/sk/grc8h2hn49lc8wfgnxnl5jqh0000gn/T/form-init5349156603706809421.clj:1:125)
# tai
Exception in thread "main" java.lang.IllegalArgumentException: Duplicate key: null, compiling:(kayttooikeus_service.clj:15:5)
Tämä on todennäköisesti bugi Leiningenissä: se ei suorita tiedostoa
soresu-form/src/oph/soresu/common/config.clj
silloin, kun va-hakija
tai va-virkailija requiraa sen. Ongelman voi kiertää komentamalla:
touch soresu-form/src/oph/soresu/common/config.clj
Backendin uberjarrien buildi, projektin juurihakemistossa:
make lein-build
Yksittäisen Leiningen-projektin testien ajaminen, esimerkkinä va-hakija:
cd va-hakija
../lein with-profile test spec -f d # kerta-ajo
../lein with-profile test spec -a # monitorointi ja ajo muutoksista
../lein with-profile test spec -a -t tag # monitorointi ja ajo vain testeille, jotka merkitty tägillä `tag`
Backendin testit sisältävät myös frontendin yksikkötestien ajon
Mikäli muutat frontendin koodia, pitää frontendin buildi ajaa uudelleen (katso ylhäältä).
Huom! va-virkailijan testien ajaminen edellyttää, että va-hakijan testit on ajettu aiemmin.
Kaikkien Leiningen-projektien testien ajaminen, juurihakemistossa:
make lein-test
Sovelluksen ajoympäristön voi asettaa Leiningenin komennolla
with-profile PROFILE
. Esimerkiksi test
-ympäristön käyttö
web-sovelluksen ajamiseen:
cd va-hakija
../lein with-profile test trampoline run
Ajoympäristojen konfiguraatiot ovat Leiningen-projektien
config
-hakemistossa
.edn
-tiedostoissa.
Komento lein test
käyttää test
-ympäristöä
automaattisesti. Lisätietoja Leiningenin profiileista.
Hakijasovelluksen tuotantoversion ajo:
cd va-hakija
../lein uberjar
CONFIG=config/va-prod.edn java -jar target/uberjar/hakija-0.1.0-SNAPSHOT-standalone.jar
Frontendin ja backendin puhdas buildi ja testien ajo, projekin juurihakemistossa:
make clean build test
Backendin riippuvuuksien versioiden tarkistus, projektin juurihakemistossa:
make lein-outdated-dependencies
Frontendin riippuvuuksien tarkistus, projektin juurihakemistossa:
make npm-outdated-dependencies
Hakemusten generointi:
cd va-hakija
../lein populate 400
Luo checkouts
-hakemistot hakijan ja virkailijan
sovellusmoduuleihin. Projektin juurihakemistossa:
make lein-install-checkouts
Leiningen tunnistaa nyt soresu
ja common
-kirjastot ns. checkout
dependencyinä,
jolloin muutokset lähdekoodissa ja muutoksen evaluointi voidaan saada
näkyviin hakijan ja virkailijan sovelluksissa ajonaikaisesti.
Jotkut kehitystyökalut saattavat injektoida Leiningeniä käynnistäessä
overridaavan riippuvuuden org.clojure/tools.nrepl
-jarriin, jota myös
Leiningen itse käyttää. Mikäli overriden versio on eri kuin Leiningenin
käyttämä versio, ilmoittaa Leiningen virheestä ja aborttaa, koska asetus
:pedantic? :abort
on päällä. Voit ratkaista ongelman kahdella eri
tavalla:
-
Aseta
:pedantic? :range
Leiningenin user-profiiliin tiedostossa~/.lein/profiles.clj
:{:user {:pedantic? :range}
Tällöin Leiningen varoittaa overridaavista riippuvuuksista, mutta ei aborttaa.
-
Määrittele
org.clojure/tools.nrepl
-jarrin versio samaksi kuin mitä kehitystyökalu käyttää tiedostoon~/.lein/profiles.clj
. Esimerkiksi:{:repl {:dependencies [[org.clojure/tools.nrepl "0.2.13"]]}}
Esimerkiksi Emacsin CIDER-kehitysympäristöä käyttäessä:
-
Aseta
(customize-set-variable 'cider-prompt-for-symbol nil)
, jotta CIDER ei injektoi riippuvuuksia automaattisesti. -
Aseta CIDERin riippuvuudet
~/.lein/profiles.clj
:ssä (versionumerot riippuvat CIDER:n versiosta):{:repl {:plugins [[cider/cider-nrepl "0.15.1"]] :dependencies [[org.clojure/tools.nrepl "0.2.13"]]}}
-
Käynnistä REPL hakijan tai virkailijan moduulissa: avaa moduulissa oleva clj-lähdekoodi puskuriin (esim. tiedosto
va-virkailija/src/oph/va/virkailija/routes.clj
) ja suorita Emacs-komentocider-jack-in
-
Kun REPL on käynnistynyt, käynnistä sovelluspalvelin REPL:ssä:
oph.va.virkailija.main> (def main (-main))
-
Muokkaa
soresu
taicommon
-kirjastossa olevaa clj-lähdekoodia, evaluoi muutos (esim. Emacs-komentocider-eval-defun-at-point
) -
Muutoksen vaikutuksen pitäisi näkyä sovelluksessa.
Va-hakija ja va-virkailija käyttävät seuraavia palveluja integraatioina:
Kuvaus | Dokumentaatio | Käytössä | Muuta |
---|---|---|---|
CAS | palvelukortti protokolla | va-virkailija | Käyttäjän autentikointi va-virkailijaan. Va-virkailija-sovelluksen autentikointi muihin OPH:n palveluihin (service user). |
Käyttöoikeuspalvelu | palvelukortti api | va-virkailija | VA-käyttäjän haku käyttäjätunnuksen perusteella, VA-palvelun kaikkien käyttäjien haku. |
Organisaatiopalvelu | palvelukortti api | va-hakija | Hakijan organisaation tietojen haku Y-tunnuksen perusteella. |
Oppijanumerorekisteri | palvelukortti api | va-virkailija | Käyttäjän haku person-oid:lla. |
Koodistopalvelu | palvelukortti api hallinta-ui | va-hakija, va-virkailija | Koodien ja metatietojen haku ja luonti. |
Hakijan käyttöliittymä: viimeisin stabiili Google Chrome ja Mozilla Firefox, IE11.
Virkailijan käyttöliittymä: viimeisin stabiili Google Chrome ja Mozilla Firefox.
Ei näkymää, jossa listataan avoimet haut. OPH linkittää avoimet haut oph.fi:hin käsin. Tämä johtuu prosessista, joilla hakuja luodaan (uusi haku vaatii asetuksen).
Hakemuksen voi arvioida vasta hakuajan umpeuduttua. Tämä siksi, että hakija voi muokata hakemusta siihen asti.
Hakemuksen tilat:
- hakijan näkökulmasta
- uusi
- luonnos
- lähetetty
- odottaa täydennystä
- poistettu
- virkailijan ja arvioijan näkökulmasta
- käsittelemättä
- käsittelyssä
- mahdollinen
- hylätty (mahdollinen lopputila)
- hyväksytty (mahdollinen lopputila)
va-virkailijan hakulomakkeen json-editorilla voi täysin muokata lomakkeen sisältöä. Kaikkia graafisen lomake-editorin komponentteja ei ole toteutettu. Lomakkeen voi kopioida json-editorin kautta toiseen avustushakuun.
08/2018 lisätty kommenttien piilotus, jos käyttäjä ei ole itse vielä kommentoinut (Jira VA3-438). Kommenteissa ei ole ollut aiemmin käyttäjän tunnistetta. Näin ollen vanhemmissa hauissa ei voida tarkistaa, onko käyttäjä vielä kommentoinut. Tällöin näytetään kaikki kommentit.
Uudemmissa hauissa toimintatapa on seuraava:
- Kun haku on jossain muussa tilassa, kuin ratkaistu
- Jos käyttäjä ei ole kommentoinut, näytetään teksti, että mahdolliset muiden käyttäjien kommentit näkyvät, kun käyttäjä on kirjoittanut oman kommenttinsa
- Käyttäjä ei voi tietää, onko hakemuksessa kommentteja vai ei
- Kun haku on ratkaistu
- Näytetään kaikki kommentit tai teksti "Ei kommentteja"
Sovellus tarkistaa jokaisen maksatuksen lähetyksessä, että virkailija ei ole asettanut "Ei maksuun" tietoa tai hakija ei ole ilmoittanut, että ei ota avustusta vastaan.
Handi palauttaa XML-muodossa vastauksen maksatuksesta, mikä luetaan payment-schedulerin avulla ajastetusti ja maksatuksen tila päivitetään tietokantaan.
Maksatukset-näkymässä listataan sekä julkaistut että ratkaistut haut. Ainoastaan ratkaistujen hakujen maksatuslistaukset ovat käytettävissä.
Kun haun päätökset lähetetään, kaikille hakemuksille luodaan 1. erän maksatus seuraavin ehdoin:
- Tila on hyväksytty
- Virkailija ei ole asettanut "Ei maksuun" täppää
- Hakija ei ole ilmoittanut, että ei ota avustusta vastaan
Maksatusprosessi etenee seuraavasti yhdessä erässä maksettavan haun kanssa:
- Ensimmäisen erän suuruus on luonnollisesti myönnetty summa (OPH:n osuus)
- Virkailija luo Maksatukset-näkymässä uuden maksuerän täyttämällä tarvittavat tiedot ja lähettää maksatukset Handiin
Maksatusprosessi etenee seuraavasti useammassa erässä maksettavan haun kanssa:
- Ensimmäisen erän summa määräytyy haussa tehtyjen määritysten (avustuksen
summan leikkuri yms.) mukaan
- Jos näitä ei ole haun tietoihin määritelty, käytetään oletusarvona, että kaikille maksetaan useassa erässä ja ensimmäinen erä on 60% myönnetystä summasta
- Virkailija luo Maksatukset-näkymässä uuden maksuerän täyttämällä tarvittavat
tiedot ja lähettää 1. erän maksatukset Handiin
- Asiakirjoja virkailija voi lisätä mielivaltaisen määrän maksuerää ja vaihetta kohden. Näitä tietoja käytetään maksatusten sähköposti-ilmoituksen lähettämiseen.
- Seuraavan erän summan asettaa virkailija Väliselvitys-välilehdellä
- Tämän jälkeen maksu ilmestyy Maksatus-näkymään, josta sen voi lähettää, kuten ensimmäisen erän
Maksusanomassa on pitkäviite, jolla tunnistetaan hakemuksen maksatus VA-järjestelmässä. Pitkäviite koostuu hakemuksen asianumerosta ja maksuerän numerosta alaviivalla erotettuna. Samainen pitkäviite palautuu Handista sanoman mukana, kun maksatus on maksettu.
Vanhoissa maksatuksissa ei ole pitkäviitteessä maksuerän numeroa. Näitä parsittaessa oletetaan, että kyseessä on maksatuksen 1. erä.
Maksatusten mahdolliset tilat ja niiden selitteet löytyvät tietokannasta taulusta paymentstatus
.
Tällä hetkellä järjestelmä tukee hakijan luomaa muutosta ainoastaan avustuksen vastaanottamatta jättämisen osalta.
Jokaiselle hakemukselle luodaan lähetysvaiheessa (submit) vahvistussähköpostin luonnissa uniikki tunniste, jolla hakija pääsee lähettämään muutoshakemuksen. Tämä tunniste vanhenee, kun avustuksen ensimmäinen maksatus lähetetään.