Ehitisregistri tarkvaraline arhitektuur
Ver. 9 05.03.2020
Ülo Puskar, Kristjan Kaiklem
Alates 2018 neljandast kvartalist on planeerimisel EHR arhitektuuri muudatused ning uue e-ehituse
keskkonna arendused, mis lähtuvad käesolevas dokumendis toodud nõuetest. Käesolev dokument
kajastab MKM IT osakonna ja EHR arendajate poolt tehtud e-ehituse keskkonna arhitektuuri
kokkuleppeid. Uutes arendustes tuleb järgida käesolevat dokumenti. Juhul, kui tekkib vajadus
käesolevas dokumendis toodud nõudeid laiendada või muuta tuleb selleks eelnevalt saavutada
kokkuleppe MKM IT spetsialistidega ning tehtud kokkulepped käesolevasse dokumenti sisse viia.
Arhitektuuri muutmise eesmärk
1. Lammutada olemasolev monoliitne Javal baseeruv EHR (edaspidi vana e. olemasolev EHR)
rakendus osadeks, et
a. Tagada lõppkasutajatele kiirem töökeskkond (praegune rakendus on tänu
keerukusele kohati muutunud väga aeglaseks).
b. Muuta rakenduse edasiarendamine kiiremaks ja odavamaks (tänase monoliitse
rakenduse arendamine nõuab pikka õpiaega, testimine on ajamahukas ja seetõttu on
arendused kauakestvad ning kallid).
2. Tagada uus (edaspidi viidatakse uuel arhitektuuril baseeruvale EHR rakendusele, kui uuele
EHR-le) ja tehniliselt kaasaegne platvorm e-ehituse kontseptsiooni realiseerimiseks. E-ehituse
üks oluline osa on EHR ja seetõttu on vajalik, et EHR tehniline lahendus võimaldaks
realiseerida kõiki e-ehituse vajadusi.
3. Tagada EHR jätkusuutlikkus võttes arendustes kasutusele järk järgult uusi tehnoloogiaid ja
rakenduse käitluskeskkondi nii, et olemasolevaid rakendusi saaks töös hoida, kuni uued need
välja vahetavad.
4. Tagada EHR vastavus kõigile ISKE klassiga määratud nõuetele.
Uue EHR-i tarkvaralise arhitektuuri põhimõtted
1. Arhitektuur lähtub mikroteenuste kontseptsioonist
(https://en.wikipedia.org/wiki/Microservices), ehk plaanis on EHR monoliitrakendus jagada
osadeks nii, et iga osa oleks käsitletav eraldi käitatava teenusena. (Mikroteenuse asemel on
edaspidi kasutusel sõna teenus).
2. Olemasolev rakendus on töös senikaua, kui uued teenused selle järk järgult välja vahetavad.
Uute teenuste arendusel lähtume „Brownfield“ arendusmetoodikast
(https://en.wikipedia.org/wiki/Brownfield_(software_development)), ehk teenuste loomine
lähtub olemas olevast tarkvarast ja seetõttu on vajalik, et teenuste arendajad omaksid
põhjalikke teadmisi EHR olemasoleva rakenduse kohta.
3. EHR tarkvaraline arhitektuur koosneb järgnevatest tasemetest:
a. Kasutajaliides
b. Veebiserver
c. Rakendusserver
d. Andmebaas
web Architecture diagram
Client Browser
Page EHR Java Client Browser::
application EHR React User
Interface
REST requests
TMS requests
«link»
«link»
Apache Web Server
Docker EHR API
«link» «redirect» Proxy Proxy
Link to Menetlus React page load
Page close
«link» «link»
Routing to service provider
App server «redirect»
EHR Java application Docker container Docker containers
API component
App server::EHR UI provider NodeJS/Python/Java
Java application:: NodeJS(React
Old EHR pages «redirect» App)
TMS, WMTS
SQL
SQL SQL
Connection to database
«builds»
Oracle 12.2 DB
server EHR database
GeoLocation Andmeait
PostgreSql PostgreSQL kaart.maaamet.ee
JSON
SQL
JSON SQL
Docker
Docker
Rabbit MQ Online data
messaging
Datapump
Joonis 1 EHR - arhitektuur
e. Kasutajaliides:
i. Kasutajaliides (User Interface) – lähtub microfrontend (https://micro-
frontends.org/) põhimõttest ehk kasutajaliides on jaotatud teenuste vahel
komponentideks (custom elements). Komponentide laadimiseks kasutame
SSI(server side include). Kõikides jagatud komponentides kasutame ühte ja
sama jagatud ruuterit (router), et ära hoida komponentide vahel lülitamisel
page reload vajadust.
ii. Kõik uued komponendid kasutavad ühtesid ja samasid aluskomponente: JS
Polyfills, Veateated, monitooring, püsifailide hoidmine.
iii. Kasutajaliidese loomisel kasutame React, HTML, CSS ja Javascripti viimaseid
versioone.
iv. Kasutajaliides luuakse EHR aluskomponentidest
(link: https://styleguide.ehr.ee/) Commented [A1]: Muudetud 9. aprill 2021
v. Kasutajaliidese aluskomponente kasutatakse npm paketist ehr-components.
Aluskomponendi arendamisel luuakse uus ehr-components paketi versioon
npm paketihoidlassse ning suurendatakse versiooninumbrit vastavalt
semver2 standardile.
vi. E-ehituse aluskomponendi loomisel ei tohi muuta esialgseid komponente.
Esialgse komponendi alusel tuleb luua uus komponent ning lisada see e-
ehituse komponentide projektis “src/ehr_components” folderisse. Commented [A2]: Muudetud 9. aprill 2021
vii. E-ehituse kasutajaliides käivitub juurkomponendist, mis asub projektis:
https://git.mkm.ee/ehr/ehr-k8s-pipeline/ehr-ui ning kõik uued loodavad
komponendid peavad olema integreeritud juurkomponenti.
viii. Juurkomponendis on komponentide infovahetuseks kasutusel Redux pakett
ix. Komponendid integreeritakse juurkomponenti npm paketina. Komponendi
sisenditeks on “React props” ja väljunditeks “render props event”-d.
Komponentide sisendid ja väljundid dokumenteeritakse React Styleguidist
paketiga
x. Kasutajaliidese juurkomponent integreeritakse olemasoleva Java
rakendusega linkide kaudu, nii et www.ehr.ee lingi avamisel käivitatakse
juurkomponent ning sellest omakorda uue või vana Java rakenduse lehed vt.
joonis
xi. Kasutajaliidese navigeerimiseks kasutame juurkomponendis react-router
paketti
xii. Kasutajaliidese stiilid võetakse juurkomponenti integreeritud e-ehituse CSS
stiilifailist.
xiii. Kasutaliidese stiilide muutmiseks või lisamiseks on e-ehituse stiiliraamat. E-
ehituse stiilifail asub siin projektis. E-ehituse stiilifaili täiendamisel peab
arendaja tagama, et muudatused ei kahjustaks olemasolevate komponentide
töötamist. Peale muudatuste sisseviimist tuleb genereerida uus CSS
ja integreeridasee e-ehituse juurkomponenti. Commented [A3]: Muudetud 9. aprill 2021
xiv. Kasutaja õigused kasutajaliidese elementidele leitakse juurkomponendis või
vajadusel alamkomponentides kasutades e-ehituse JWT tokenit. Vt.
Kasutajaõiguste süsteemi detailanalüüs
xv. Kasutajaliidese andmevahetuseks andmebaasiga kasutame REST teenustel
põhinevat API-t.
xvi. Vormi väljade kohustuslikkuse kontroll ja väljade kuvamise/ täitmise
ärireeglid realiseerime võimalusel lehitsejas ja Andmebaasi kirjutamisel
vastavas API-s.
xvii. Kasutajaliidese põhivaated realiseeritakse prototüüpimisel kasutades e-
ehituse aluskomponente. Commented [A4]: Muudetud 9. aprill 2021
xviii. E-ehituse kasutajaliides peab olema testitud enamlevinud lehitsejatega Commented [A5]: Muudetud 9. aprill 2021
(Chrome, Edge, Firefox, Safari) ja mobiilivaates.
xix. Kasutajaliides peab olema koostatud nii, et autoriseeritud kasutaja saaks
muuta html elementide pealkirju, veateated ning abitekste.
xx. Kasutajaliidese tekstid peavad asuma juurkomponendis keelefailides (eesti,
inglise).
xxi. Lõppkasutajale kuvatavatel html elementidel peavad olema unikaalsed ID-d,
et saaks rakendada kasutajaliidese automaattestimist.
xxii. Komponentidele luuakse staatiline html, et kuvada komponente ka juhul, kui
javascript pole kättesaadav/lubatud.
xxiii. Uute komponentide loomisel kasutame antd ja reacstrap pakette.
xxiv. Kasutajaliidese loomisel kasutame creat-react-app tööriistu (webpack, babel,
eslint airbnb reeglitega).
f. Veebiserver:
i. EHR olemasolevas Java rakenduse infrastruktuuris kasutatakse Apache
veebiserverit.
ii. Microteenuste loomisel kasutatakse eelkõige Nginx veebiserverit, mis on
kasutusel uue rakenduse juurkomponendi serveerimiseks.
g. Rakendusserver:
i. Uute API-de loomisel kasutatakse kas: Java (ver.11 Zulu), NodeJS(ver. 12) või
Python programmeeriskeeli.
ii. Uue API rakendusserverid käitatakse Docker https://www.docker.com/
konteinerites riigipilves Kubernetes klastris.
iii. Kubernetes klastrite haldusvahendina kasutatakse Rancher tarkvara
https://rp-rancher.opnd.eu/g/clusters.
iv. Uue API rakendused peavad sisaldama automaattarne: MKM Git ->
Riigipilves Helm Chart vajalikke Helm konfiguratsiooni faile vt. Näiteks Helm
konfiguratsioonifaile: https://git.mkm.ee/ehr/ehr-k8s-pipeline/ehr-
geoservices/tree/master/helm ja Juhend Helmi kasutamiseks
v. Automaattarne riigipilve lisatakse MKM Git-s projektidele, mis asuvad
https://git.mkm.ee/ehr/ehr-k8s-pipeline grupis.
vi. Helm Charti abil peab saama paigaldada rakendused Rancher App kaudu:
https://rancher.com/docs/rancher/v2.x/en/catalog/ e-ehituse test- ja
toodangu klastris olevatesse: development, test, prelive, live projektides
asuvatesse namespacedesse.
vii. Olemasoleva Java rakenduse server (paikneb Tieto majutuses) jääb tööle,
kuni olemas olev Java rakendus on kasutuselt maha võetud.
viii. Olemasolev kaardiserver jääb eraldiseisva teenusena tööle, kuni luuakse
uued kaarditeenused. Olemasolev kaardiserver kasutab Maaameti
kaarditeenuseid:
1. Gazetteer: http://xgis.maaamet.ee/gaz/JGazetteer
2. ADS hoone SVG: http://kaart.maaamet.ee/ehrwxs/svg
3. ADS hoone WFS: http://kaart.maaamet.ee/ehrwxs/wfs
4. ADS hoone info: http://kaart.maaamet.ee/wms/ads-kov-t?
5. Kitsenduste ja KÜ info: http://kaart.maaamet.ee/wms/alus?
ix. Luuakse mikroteenuste kontseptsioonil baseeruv E-ehituse REST API. API
kavandamiseks ja dokumenteerimiseks kasutatakse OpenAPI standardit
(https://github.com/OAI/OpenAPI-Specification/) ja Swagger tööriistu:
https://swagger.io/ Swagger UI ja Swagger Editor. EHR API kavandamisel
tuleb järgida: EHR API kirjeldamise reeglid.
x. E-ehituse REST API kirjeldus asub: https://swaggerui.ehr.ee/. Uue API
loomisel tuleb API kirjeldus lisada projekti: https://git.mkm.ee/ehr/ehr-k8s-
pipeline/swaggerui ning uus versioon tarnida riigipilve.
xi. E-ehituse API loomisel tuleb tagada, et teenused ei korduks ja soovitav on Commented [A6]: Muudetud 9. aprill 2021
olemasolevat teenust edasi arendada, mitte luua uusi teenuseid. Teenused
peavad olema vähemalt 2 põhiversiooni (semver2) tagasiulatuvalt ühilduvad.
xii. Andmete ülekandmiseks API-st kasutajaliidesesse kasutatakse võimalusel
JSON formaati või eelneval kokkuleppel mõnda muud XML formaati (näiteks
CityGML).
xiii. E-ehituse Kaardikomponendist ja geo-otsingu teenustest andmete Commented [A7]: Muudetud 9. aprill 2021
vahetuseks kasutatakse GeoJSON formaati.
xiv. Juhul, kui API teostab andmebaasis CUD 1 operatsioone siis andmete
verifitseerimine toimub kahel tasemel ehk esmalt UI vormi kasutajaliideses ja
seejärel enne andmebaasi viimist API rakenduses.
xv. Teenuste autoriseerimine toimub vastavalt: Kasutajaõiguste süsteemi
detailanalüüs
xvi. Teenused, mis teostavad andmebaasiga CRUD operatsioone tuleb luua nii, et
transaktsioonid ning vajalikud Join operatsioonid toimuvad andmebaasis,
kasutades andmebaasi protseduure, mitte API rakenduses.
xvii. Andmete terviklikkuse tagamiseks andmebaaside üleselt kasutatakse
võimalusel (juhul, kui saga pattern realiseerimine pole otstarbekas)
kahetasemelist “commit” lahendust (2PC) lisades transaktsiooni
koordineerimist vajavate teenuste üleselt uue “commit” teenuse või
vajadusel mikroteenustes nn. “Choreography-based saga pattern”
metoodikat (https://microservices.io/patterns/data/saga.html). Message
Brokerina on kasutusel RabbitMQ (https://www.rabbitmq.com/).
h. Andmebaas:
i. Olemas olev EHR Oracle andmebaas jääb kasutusele, kuni uute
mikroteenuste andmebaasid on kasutusele võetud.
ii. Olemas olev andmeaida Postgre SQL andmebaas jääb kasutusele
iii. Mikroteenuste vajadusteks luuakse uued PostgreSQL andmebaasid.
iv. Igal andmeobjektil on üks baas, kuhu andmed kirjutatakse ja vajadusel
kasutada neid mõnes teises baasis JOIN-de teostamiseks luuakse teise baasi r
prefiksiga view, mille abil andmeid saab lugeda. Andmete
sünkroniseerimiseks andmebaaside vahel kasutatakse pglogical tarkvara.
v. Olemas olev Oracle ja uued baasid hoitakse sünkroonis RabbitMQ
(https://www.rabbitmq.com/) sõnumiedastusega, kuni olemasolev Java
rakendus on kasutusel.
1 CRUD(Create, Read, Update, Delete)
vi. EHR unikaalvõtmete (EHR-kood, dokumendi number jm.) loomiseks
kasutatakse teenuseid: Koodide omistamise teenused
vii. Andmebaasi siseste operatsioonide teostamiseks luuakse SQL protseduurid,
mida API-t realiseerivad komponendid välja kutsuvad.
i. Failisüsteem
i. Konteinerakendustele on klastris kasutusel NFS block storage ja Longhorn
block storage.
ii. Klastrites on kasutusel S3 Object storage teenus, mis on eelistatud failide
hoidmise lahendus
j. Muud komponendid
i. Cache jaoks on kasutusel Redis. Vt. https://git.mkm.ee/ehr/ehr-k8s-
pipeline/redis-proxy. Redist saab rakendada vajadusel konteinerite vahel info
jagamiseks või rakenduse andmete ajutiseks säilitamiseks kiires püsimälus.
ii. Pilve arhitektuuris kasutame nimelahendust (DNS). Vt. Eehitus DNS kirjeldus
4. Mikroteenuste rakendustele tuleb lisada Kubernetes liveness probe
5. Uue teenuse loomisel kasutatakse võimalikult palju valmis arendatud komponente
(https://www.npmjs.com/) ja olemas olevaid raamistikke või teeke.
6. E-ehituse teenused peavad arenduse käigus olema kaetud unit testidega, mille abil Commented [A8]: Muudetud 9. aprill 2021
kontrollitakse teenuse komponentide (alamosade) vigadeta tööd.
7. Javascripti kasutamisel (React, NodeJs) peab tarnitav kood olema kontrollitud Eslint
(https://eslint.org/) Airbnb reelitega ning ei tohi sisaldada linteri veateateid.
8. Koodi kvaliteeti kontrollitakse CI/CD tarnetel Sonarqube (https://www.sonarqube.org/)
tarkvaraga. Koodi Sonarqube raport https://sonarqube.mkm.ee/dashboard?id=<projekti
nimi> peab olema:
a. Reliability Bug = 0
b. Security Vulnerability = 0
9. Rakenduse arendusel tuleb arvestada, et rakendus peab olema testitav Katalon
(https://www.katalon.com/) automaattestidega ehk kasutajaliideses kasutatavad html
elemendid peavad sisaldama unikaalset atribuuti näiteks id. Kasutajaliides peab olema
testitud automaattestidega mobiilivaates ning toetatavate veebilehitsejate vaadetega. API
peab olema testitud Katalon API testimiseks mõeldud testidega.
10. Rakenduste logid kogutakse kesksesse logihalduse teenusesse ja seetõttu peavad rakenduste
logid olema Json formaadis. Logiteenuse kirjeldus
Üleminekuprotsessi etapid
Etapid on toodud ajalises järgnevuses aga samas on võimalik etappe ka paralleelselt käivitada juhul,
kui selleks on olemas piisavalt ressursse.
1. Tarkvaralise arhitektuuri dokumenteerimine
2. Olemasoleva EHR komponentideks jaotamine ja teenuste kavandamine (vt. järgmine ptk.)
3. Automaattarnete ja testide käivitamine
4. Teenuste kasutajaliidese arendamine (MTA UI + React)
5. Turvateenuste arendamine: JWT – ehk teenustele juurdepääsu pass, autoriseerimise
süsteem ehk kasutajad/grupid/rollid/juurdepääsuõigused, andmete turvalisuse ja
juurdepääsu muudatused.
6. Teenuste arendusprojektid, mille käigus arendatakse uus teenus ja muudetakse
olemasolevat rakendust nii, et uue teenuse saab kasutusele võtta.
EHR olemasoleva rakenduse komponentideks jaotamine
Olemasoleva rakenduse teenusteks jaotamisel on aluseks EHR tänase rakenduse komponendid.
Samuti tuleb komponentidena arvestada tänases EHR infrastruktuuris paiknevad eraldi rakendused:
andmeait, EHR infoportaal, VRM, kaardirakendus. Uue teenuse arendusel tuleb järgida
mikroteenuste põhimõtteid ehk teenuses peavad olema andmed, rakenduse server ja kasutajaliides
nii, et EHR muude teenuste (va. Elutähtsad teenused, mis on aluseks kõigi teiste teenuste
toimimisele) katkestused ei mõjutaks ülejäänud teenuste tööd.
Kuna uute teenuste loomisel tuleb need integreerida olemasoleva rakendusega siis olemasolevad
EHR komponendid tuleb jaotada teenusteks arvestades olemasoleva rakenduse ülesehitust ja
võimalusi nii, et uusi teenuseid saaks kasutusele võtta võimalikult vähe olemasolevat rakendust
muutes. See võimaldab hoida kokku ressursse ning tagada lõppkasutajatele võimalikult sujuva ja
probleemideta ülemineku protsessi.
EHR tarneprotsess (tehnoloogia vaade)
E-ehituse teenuste tarkvaraline protsess on lahti kirjeldatud allpool olevas joonisel (vt. Joonis 1). Commented [A9]: Muudetud 9. aprill 2021
Uue tarkvara tarnimisel võetakse kasutusele konteineri põhine lähenemine – selle protsessi
realiseerimiseks kasutatakse järgmisi tarkvarasid :
• GIT / GIT CI (https://about.gitlab.com/) – kooditarnete tegemine (rakenduse kood, sql kood,
docker paigaldusfailid, automaattestid). Tarne protsessi automaatne käivitamine.
Kasutatakse tellija keskkonda aadressil : https://git.mkm.ee
• Docker ( https://www.docker.com/) – vastavalt GIT-is oleva infole konteinerite loomine ja
levitus ( rakendus + andmebaas + rakenduse toimimiseks vajalik infrastruktuur). Docker-iga
integreeritud tarkvarad :
o Unit testid – arendaja poolt kirjutatud testid kontrollimaks EHR-i ja selle
komponentide toimimist vastavalt nõuetele;
o Apache Maven ( https://maven.apache.org/) - Java koodi kompileerimine,
o SonarQube (https://www.sonarqube.org/) – koodi kvaliteedi kontrolli teostamine,
o Liquibase ( https://www.liquibase.org/) – andmebaasi loomine ja muutmine,
o Artifactory (https://jfrog.com/artifactory/) – Java artifaktide loomine ja konteinerite
registreerimine.
o Helm kaartide hoidla - (https://chartmuseum.com/)
• Kubernetes (https://kubernetes.io/)– konteinerite haldamine, skaleerimine ja koormuse
jaotamine.
• Katalon (https://www.katalon.com/) – EHR UI ja API testmine.
Joonis 1. E-ehituse tarneprotsess (tehnoloogia vaade) Commented [A10]: Muudetud 9. aprill 2021
Mittefunktsionaalsed nõuded
V1.2 13.01.2020
Järgnevalt on toodud Ehitisregistri rakenduste arendamise mittefunktsionaalsed nõuded ja nõudega
seotud vajalikud lingid.
Nõude kirjeldus Selgitus Kategooria
https://pilv.mkm.ee/s/lyWdATR1SUmVIfQ/d
Rakenduse arhitektuur peab lähtuma EHR
1. ownload?path=%2F&files=Ehitisregistri%20t Arhitektuur
arhitektuuridokumendist
arkvaraline%20arhitektuur.docx
Rakenduse kasutajaliides peab olema juurdepääsetav https://www.w3.org/TR/2018/REC-
2. Kasutajaliides
ning vastama vähemalt WCAG 2.1 tasemele AA. WCAG21-20180605/ Commented [TJ1]: Muudetud 9. aprill 2021
Rakenduse kasutajaliides peab olema kasutatav
3. järgmiste veebibrauseritega: Chrome, Safari, Firefox ja Kasutajaliides
Commented [TJ2]: See „ja“ tuleks asendada komaga
Edge, Android Chrome ja IOS lehitsejad.
(arendajaportaalis sama moodi)
Rakenduse kasutajaliides peab ühilduma täielikult
4. HTML5, CSS3 ja Javascript kehtivate standarditega ning Kasutajaliides
kõikide nõutud veebilehitsejate viimaste versioonidega.
Rakenduse kasutajaliides peab kohanduma erinevate
5. Kasutajaliides
ekraanivaadetega (arvuti, tahvel ja mobiiltelefon).
Rakenduse kasutajaliidese disainiotsused tuleb tellijaga
6. Kasutajaliides
kooskõlastada.
Rakenduse kasutajaliides peab olema tehtud lähtudes
7. Kasutajaliides
värskeimatest UX trendidest
8.
Rakenduse kasutajaliidese kujunduses tuleb lähtuda E- E-ehituse stiiliraamat Kasutajaliides
ehituse stiiliraamatust veebiversioon
Rakenduse kasutajaliidese aluskomponentideks on MTA
9. EHR-komponendid Kasutajaliides
komponendid
Kasutajaliidese komponendid peavad olema react-styleguidist
10. Kasutajaliides
dokumenteeritud
Kasutajaliidese komponendi Git projekti readme.md Vt. näidis
failis peab olema: Ehitise kehtivate andmete teenus
Komponendi eesmärgi tutvustus
Juhend, kuidas komponenti saab teistes projektides ja
kasutada
11. https://swaggerui.ehr.ee/ehitise_kehti Kasutajaliides
Viide dokumentatsiooni asukohale – dokumentatsioon
vate_andmete_teenus
peab sisaldama näiteid, kuidas komponenti võõrast Commented [TJ3]: Uuendatud 9. aprill 2021
koodist välja kutsuda
Juhend edasiarendamiseks
Juhend versioneerimiseks ja publitseerimiseks
Rakendus peab töötama veebibrauseritega, mis
12. eID
toetavad ID-kaarditarkvara 2 viimast versiooni
Rakendus peab kasutama kasutaja tuvastamiseks
13. https://e-gov.github.io/TARA-Doku/ eID
keskset TARA autentimisteenust
Arendusprojekti juhtimiseks ja projekti läbiviimiseks
Arendustööde tellimused ja tarkvaravigade
14. kasutatakse Hankija projektijuhtimistarkvara JIRA organisatsioon
haldamine.
(https://jira.mkm.ee)
Arendusprojekti käigus loodav lähtekood esitatakse
15. dokumenteerituna läbi koodihalduskeskkonna organisatsioon
https://git.mkm.ee/projektinimi
Arendusprojekti käigus loodavate rakenduste versioone
tähistatakse vastavalt Semver 2.0 standardile „versioon-
16. x.x.x“. Versiooni numbrid peavad kajastuma Semver 2.0 organisatsioon
koodihoidla Git Tag-des
Statistilisi parameetreid mõõdetakse Google Analytics Tellija annab omalt poolt vastava Google
17. analüütika
keskkonna kaudu. Analytics konto andmed
Jõudluse parameetrid:
Üldjuhul peavad API päringud tagastama tulemuse
browserisse alla 1s.Mõõdetakse browseri põhiselt.
18. Kvaliteet
API erijuhud lepitakse Tellijaga eraldi kokku
Kasutajaliidese html koos stiilide ja Javascriptiga
laaduma <1s
API rakenduse endpoint-id peavad olema vastavuses EHR API teenuste nimetused ja teenuste
19. Kvaliteet
viidatud juhendile. kirjeldamine
API rakenduse kõik „route“-d peavad olema varustatud
20. Katalon Kvaliteet
Katalon testiga, mis testib sisend/väljundit ja kiirust.
Rakendus peab tagama isikuandmete töötlemise
https://eur-lex.europa.eu/legal-
21. vastavalt isikuandmete kaitse üldmäärusele ja Infoturve
content/ET/TXT/?uri=CELEX%3A32016R0679
isikuandmete kaitse seadusele
Rakenduse ja andmebaasi turvalisuse tagamiseks tuleb https://www.owasp.org/index.php/OWASP_
22. Infoturve
järgida OWASP-i parimaid praktikaid. Cheat_Sheet_Series
Rakendus peab salvestama kõik paroolid ainult
23. Infoturve
krüpteeritud kujul
Rakendus ei tohi lubada ühe kasutajaga mitut
24. Infoturve
samaaegset sessiooni
Rakenduse ja kasutaja vaheline infovahetus tohib käia
25. Infoturve
ainult üle HTTPS protokolli.
ISKE turvaklassi täpsustab Tellija. Täpsem
Rakendus peab olema kirjutatud arvestades info RIA lehel :
26. töödeldavatele andmetele määratud ISKE turvaklassi https://www.ria.ee/et/kuberturvalisus/infos Infoturve
nõudeid. usteemide-turvameetmete-susteem-
iske.html
Krüptograafiliste algoritmide valmisel lähtuda RIA https://www.ria.ee/et/ametist/uuringud-
27. Infoturve
krüptograafiliste algoritmide elutsükli uuringutest analuusid-ulevaated.html
API rakendus peab olema turvatud: Denial-Of-Service
28. (DOS), Cross-Site-Scripting (XSS), Brute Force ja Infoturve
SQL/NoSQL Injection rünnakute vastu.
API peab sisaldama …/version route-i, mis tagastab API
kehtiva versiooni ja k8s liveness probe, mille abil K8s liveness probe
29. Infoturve
kontrollib API rakenduse „elus“ olekut
Loodavat infosüsteemi majutatakse Riigipilve
30. keskkonda ning sellega tuleb arvestada arhitektuuri https://riigipilv.ee/ Infra
planeerimisel.
Eelistatud on vabavaraliste andmebaaside platvormide
31. Infra
kasutamine. nt PostgreSQL
Rakendusserverite ja andmebaasi teenuste
32. Infra
jooksutamise tuleb kasutada plokksalvestuskeskkonda.
Faililao loomisel eelistatakse objektsalvestuskeskkonna
33. Infra
kasutamist S3 REST API-ga.
Rakenduse logimine peab vastama isikuandmete kaitse https://www.riigiteataja.ee/akt/104012019
34. andmekaitse
seaduses §36 kehtestatule 011
Automaatseks rakenduse ehitamiseks ja paigaldamiseks
35. DevOps
kasutame Gitlab CI/CD töövooge koos Docker-iga
Rakendused käitatakse Docker konteinerites
36. Kubernetese klastrites. Kubernetes haldamiseks DevOps
kasutame Rancher-it.
Kubernetesesse paigalduseks tuleb rakendusele lisada
https://helm.sh/ DevOps
37. Helm chart, mis arvestab, et rakendust paigaldatakse
https://chartmuseum.com/
erinevatesse Rancher projektidesse.
Helm chart peab sialdama paigalduse juhendit koos
rakenduse tööks vajalike secretite ja configmap
Kvaliteet
38. muutujate kirjeldusega failis: app-readme.md ning
paigalduseks vajalike muutujate kirjeldusi
failis:questions.yml
Rakenduse kasutajaliidese kood peab olema silutud
39. ning linter „Eslint“ Airbnb reeglitele vastav väljund ei https://eslint.org/ Kvaliteet
tohi sisaldada vea ning hoiatusteateid.
Rakenduse testimiseks peavad olema koostatud
testilood ning igale testiloole peab olema koostatud
40. https://www.katalon.com/ Kvaliteet
sellele vastav Katalon automaattest. Automaattestid
peavad töötama ilma vigadeta.
Rakendusele html kujul kasutusjuhendit tuleb
41. täiendada ja viia see vastavusse rakenduses tehtud Kvaliteet
muudatustega.
42. Kasutajajuhendi stiil lähtub e-ehituse stiiliraamatust Kvaliteet
Commented [TJ4]: Muudetud 9. aprill 2021
Kasutusjuhend peab olema kasutusloo põhine, ehk
43. juhendama kasutajat samm sammult iga konkreetse Kvaliteet
kasutusloo läbiviimisel
https://unstoppablesoftware.com/5-best-
44. Kasutusjuhendi kirjutamisel tuleb juhinduda: practices-for-writing-fantastic-software- Kvaliteet
user-guides/
Kasutajajuhend peab olema kontekstipõhiselt lingitud
45. Kvaliteet
kasutajaliidese elementidega
Rakendusele peab olema koostatud paigaldusjuhend ja
46. Turve
taasteplaan.
Rakenduses peab saama MKM-i Peakasutaja hallata
väljade, nuppude, pealkirjad nimetusi, info (i) tekste,
39. abitekste, veateateid. Kasutajaliides
Rakenduse loomisel tuleb arvestada võimalusega muuta
see mitmekeelseks (nt inglise, eesti, vene).
40. Kasutajaliides
ba
E-EHITUSE PLATVORMI STIILIRAAMAT
E-ehituse veebikeskkond
MKM
2021
E-ehituse platvormi stiiliraamat
SISUKORD
Sisukord ................................................................................................................................................... 1
1 Sissejuhatus .................................................................................................................................... 2
Stiiliraamatu lahutamatud osad ............................................................................................... 2
Stiiliraamatu alused ................................................................................................................. 2
Mõisted ja lühendid .................................................................................................................. 3
2 E-ehituse keskkonna üldpõhimõtted ............................................................................................... 4
Keskkonna kasutaja ................................................................................................................ 4
Kujunduspõhimõtted ................................................................................................................ 4
Teenuste ja liidese disainimise põhimõtted ............................................................................. 5
Keelekasutus ja tekstide koostamine ...................................................................................... 7
Tõlked ...................................................................................................................................... 9
Kasutajaliidese kujundamise põhimõtted ................................................................................ 9
3 Ekraanivaate ülesehitus ................................................................................................................ 12
Päis / Header ......................................................................................................................... 12
Menüü .................................................................................................................................... 15
Töölaud .................................................................................................................................. 16
Jalus / Footer ......................................................................................................................... 16
4 Abikeskus ...................................................................................................................................... 18
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 1 / 18
E-ehituse platvormi stiiliraamat
1 SISSEJUHATUS
E-ehituse platvormi stiilireeglid tagavad kõikidele e-ehituse teenustele ühise kasutajakogemuse.
Stiiliraamatus on kirjeldatud nii keskkonnas kasutatavate elementide stiili (värvid, kirjastiilid, ikoonid),
navigatsiooniloogikat, keelekasutust kui ka keskkonna kohandumist vastavalt kasutaja seadmele ja
rollile.
Juhised puudutavad kõiki e-ehituse kasutajagruppe – nii ettevõtjaid, kodanikke, kohalike omavalitsuste
ja teiste pädevate asutuste ametnikke ning muid osapooli (notarid, ülikoolid, jne). Eesmärk on luua igale
kasutajale sarnane kogemus, mis aitab kaasa ka tavakasutaja-menetleja-klienditoe omavahelisele
suhtlusele.
Reeglite loomise põhimõte on teenuse igal sammul vastata kasutaja vajadustele ja ootustele. Arvestame
maksimaalselt kasutajate reaalse elu olukordi, arvestame kasutaja ajalistest, tehnilistest, kogemustest
ja teadmistest tulenevate piirangutega.
Stiiliraamat on abiks nii uute teenuste disainimisel kui ka olemasolevate teenuste täiendamisel. Raamat
on loodud nii, et põhjendatud vajaduse korral ja uute teenuste loomisel on raamatut võimalik
aluspõhimõtteid kasutades täiendada.
STIILIRAAMATU LAHUTAMATUD OSAD
Lisad
Lisa 1. Stiilielemendid
Lisa 2. Ikoonide loetelu
E-ehituse stiiliprojekt
e-ehitus_visuaal
E-ehituse komponentide raamatukogu
E-ehituse kasutajaliidese React komponendid ja CSS stiilinäidised
https://styleguide.ehr.ee/
E-ehituse stiili näited
Kõige parema ülevaate stiili kasutamise näidetest saab külastades e-ehituse keskkonda:
https://www.ehr.ee (kui favicon on halltoonis, on tegemist uue e-ehituse teenusega, mis on lahendatud
vastavalt sellele stiiliraamatule).
Oma protüübid oleme ehitanud Figma keskkonnas. E-ehituse keskkonda uue teenuse loomisel palun
küsige ligipääsu meie sealsele projektile.
E-ehituse keskkonna mittefunktsionaalsed nõuded
developer.e-ehitus.ee/documentation/mittefunktsionaalsed-nouded
STIILIRAAMATU ALUSED
Stiiliraamatu lahendused tuginevad kasutajakeskse lähenemise põhimõtetel. Välja töötatud visuaalseid
valikuid tuleb kasutada kõikide e-ehituse teenuste puhul.
Juhul kui alusmaterjalis esineb erinevate dokumentide vahel vasturääkivusi, tuleb konsulteerida e-
ehituse haldusmeekonnaga MKM-is, kuid üldjuhul tuleb lähtuda rangemast nõudest.
Maksu- ja Tolliameti e-keskkonna stiiliraamat (VELVET)
https://koodivaramu.eesti.ee/veebiraamistik/react/tree/MTA
Käesolev raamat on edasiarendus EMTA stiiliraamatust. Olgugi, et tugineme pea täielikult EMTA stiilile
ja komponentidele, oleme teinud täiendusi, et täita e-ehituse platvormi vajadusi ja osad komponendid
on edasiarendatud funktsionaalsuse lisamise või koodi parandamise eesmärgil.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 2 / 18
E-ehituse platvormi stiiliraamat
VEERA Disainisüsteem (RIA)
https://veera.eesti.ee
E-ehituse keskkond liigub samm sammult EMTA stiililt VEERA stiilile. Käesolev e-ehituse stiiliraamat
peegeldab ülemineku olukorda, kus esimese sammuna on osaliselt üle võetud VEERA ikoone.
Web Content Accessibility Guidelines (WCAG) 2.1
https://www.w3.org/TR/2018/REC-WCAG21-20180605/
Euroopa Parlamendi ja nõukogu direktiiv (EL) 2016/2102, 26. oktoober 2016, mis käsitleb avaliku sektori
asutuste veebisaitide ja mobiilirakenduste juurdepääsetavust, märgib, et avaliku sektori veebilehed
peavad vastama WCAG 2.1 tase AA-le (WCAG viide uuendati 2.0 versioonilt 2.1 versioonile detsembris
2018). See nõue kehtib kõigile pärast 23. septembrit 2019 loodud lehtedele. Vanad lehed tuleb nõuetele
vastavaks viia 23. septembriks 2020 ja mobiilirakendused 23. juuniks 2021.
MÕISTED JA LÜHENDID
Siinse dokumendi spetsiifilised mõisted
Töölaud Kliendile esmast ülevaatlikku koondinfot pakkuv funktsionaalsus (nt avalehe
töölaud, minu dokumentide töölaud, minu ehitiste töölaud).
Kasutaja E-ehituse süsteemi kasutav füüsiline isik või muu väline süsteem. Kasutaja
saab esindada mõnda isikut, nt iseennast, mõnda teist füüsilist või juriidilist
isikut (juhul, kui kasutajal on vastav volitus). Üks füüsiline isik võib omada
rakenduse keskkonnas mitut kasutajat.
Globaalne menüü Valitud esindatava menüü on oma menüüpunktide jaotuselt sama mis globaalne
menüü, aga iga teenuse valikul arvestatakse juba esindatava valikuga.
Menüü alamjaotus Iga menüüelemendi alla kuuluvad jaotused. Näiteks menüüpunkti EHITISED
alla kuulub teenus “Ehitusluba/-teatis”. Alamjaotuses piirdume ühe tasemega
(kuid grupeerime teemad).
Tab Vaheleht, kus kuvatakse objekti (dokument, ehitis, …) kohta käiv samaliigiline
ja korraga kuvatav info. Näiteks Andmete esitamise teatisel olevad tab-id: Ehitis,
Dokumendid, Isikud, Esitamine (hiljem lisandub menetluse / märkuste
lahendamise tab)
Ühtlasi näiteks brauseri vaheleht/tab.
Alajaotus Sisuliselt sarnaste andmete grupp või plokk ühel vahelehel. Näiteks Andmete
esitamise teatisel olevad andmete alajaotused: Ehitise üldinfo, Ehitise
mõõtmed, Ehitise konstruktsioonid ja materjalid, Ehitise tehnilised näitajad,
Ehitise asukoht
Üldised e-ehitusega seotud mõisted
Muud e-ehituse terminid ja lühendid on leitavad siin.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 3 / 18
E-ehituse platvormi stiiliraamat
2 E-EHITUSE KESKKONNA ÜLDPÕHIMÕTTED
See peatükk kirjeldab e-ehituse kasutajakeskkonna kõige üldisemaid kasutus- ja kujunduspõhimõtteid,
mis on aluseks kõikidele järgnevatele reeglitele ja disainiotsustele.
KESKKONNA KASUTAJA
Keskkonna kujundamisel arvestame erinevate kasutajagruppide ja -juhtude eripärasid. Meie eesmärk
ei ole kujundada igale võimalikule kasutajale just temale mõeldud keskkonda, vaid kõigi vajadusi
arvestav keskkond, mille kasutamine on lihtne nii esimest korda sisenevale kasutajale kui ka
igapäevasele kasutajale.
Arvestame, et e-ehituse keskkonna kasutajad on oma kogemuselt ja oskustelt väga erineval tasemel.
KOVi ametnikele võib süsteem olla igapäevane töövahend, professionaalid kasutavad seda
iganädalaselt, või –kuiselt, kuid koduomanikud võivad süsteemi kasutada mõned korrad aastas või isegi
mõned korrad elus, seejuures võivad nad ka arvuti kasutamises end ebakindlana tunda. Kõigile
kasutajagruppidele on lihtsus, sõbralikkus, visuaalse müra vabadus ja efektiivsus oluline. Efektiivsus
tähendab kasutajate lõikes erinevat asja. Igapäevasel süsteemi kasutajal on oluline, et tegevustele
kuluks minimaalselt aega ja hiireklikke ja klahvivajutusi, juhukasutajal on oluline protsessi jagamine
arusaadavateks osadeks. Kuna professionaalil on aega ja vajadust süsteemi tundma õppida, võib talle
suunatud funktsionaalsust vajadusel pisut peita, samas juhukasutaja teenused olgu selgelt nähtaval.
Platvormile sisse loginu on alati mingi kindla kasutajana. Kasutajapoliitika ei ole küll kirjeldatud siin
dokumendis, kuid kasutajaliideses kuvame komponendid vastavalt kasutaja valikule. Reeglina loome
vaated ja komponendid universaalsed ja kuvame vastavalt kasutaja õigustele.
KUJUNDUSPÕHIMÕTTED
E-ehituse keskkonna eesmärk on olla kasutaja tegevusi toetav ja infoga abistav sõbralik keskkond.
Eesmärk on säästa kasutaja aega ja tagada selgus keskkonnas tehtud toimingutest ning nende
toimingute tulemusest. Keskkonna loomisel oleme lähtunud neljast olulisest põhimõttest.
Süsteem ei eelda spetsiaalset väljaõpet
Ehitised ja ehitatud keskkond on teemad, millega kodanikud aeg-ajalt kokku puutuvad. Loome selge,
abistava, kasutaja reaalse eluga arvestava keskkonna, mis ei vaja toimetuste tegemiseks erilist
väljaõpet. Iga isik peab suutma kasutada keskkonda ise ning täitma vajadusel teatisi ning taotlusi.
Töökeskkonna kohandamine
Algaja kasutaja soovid ja eesmärgid erinevad oluliselt professionaali omadest. Professionaal vajab
keskkonda, mida ta saab oma spetsiifilise tööprotsessi optimaalseks läbimiseks ise kujundada, ning kus
on võimalik kiire ja vigadeta töö tagamiseks infot prioriseerida. Üheks võimaluseks on keskkonna
kohandamine kasutaja harjumustele, tema rolli iseloomust tulenevatele nõudmistele ja vajadustele.
Selle tagamiseks loome kasutajale võimaluse oma töölauda, tabelit või vaadet vastavalt vajadustele
seadistada.
Keskkonna kohandamise võimaluste näited, kui need ärilises vaates põhjendatud on:
1. töölaual on võimalik muuta sisuplokkide järjestust.
2. tabelites on võimalik muuta kuvatavate veergude arvu ja valikut.
Muudatused, mida kasutaja kohandamise võimalusi kasutades keskkonnas teeb, salvestuvad selliselt,
et järgmisel korral kas samast või mõnest teisest seadmest sisse logides, näeb kasutaja enda jaoks
eelmisel korral seadistatud pilti. Siinkohal on oluline, et vastav punkt ei pruugi alati olla rakendatud, kui
äriloogika seda sel hetkel ei vaja.
Seadistused on kasutajapõhised. See tähendab, et näiteks juriidilise isiku töölaud ühe kasutaja vaates
võib olla teistsugune, kui sama juriidilise isiku töölaud mõne teise kasutaja vaates.
Kõikide kasutaja poolt seadistatavate vaadete puhul loome alati optimaalse vaikimisi vaate, mis
arvestab enamiku kasutajate vajadustega.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 4 / 18
E-ehituse platvormi stiiliraamat
Kiire ja lihtne ülevaade tagab õigeaegse reageerimise ja väldib probleeme
Me ennetame kasutaja sattumist täbarasse olukorda lihtsalt seepärast, et ta ei teadnud, kust vaadata
õiget infot, või ei leidnud õiget vormi. Kujundame kasutajaliidese nii, et see suunab kasutajat intuitiivselt
tegelema kõige olulisemate asjadega, ning näitab kasutajale teed tema töö korraldamiseks, saame
kasutaja aega kokku hoida ning vähendada tema stressi. See hoiab kokku ka ametnike aega, mis kulub
ebaõnnestunud dokumentide menetlemisele.
Sõbralikkus ja lahendusele orienteeritus
Suhtluses avalike asutustega, sisestades andmeid andmebaasidesse ning tehes suuri investeeringuid
puudutavaid otsuseid, kus viga võib tähendada kulutusi või ajakadu ning sellest tulenevaid probleeme,
on iga inimene põhjendatult pinges. Meie eesmärk on vähendada inimeste stressi ehitusteemadega
tegelemisel. Saame seda teha läbi meeldiva visuaalse lähenemise, konkreetse teksti ja selge
keskkonna ülesehituse. Loome e-ehituse keskkonnale iseloomu, mis on abivalmis, sõbralik,
lahendusele orienteeritud.
TEENUSTE JA LIIDESE DISAINIMISE PÕHIMÕTTED
E-ehituse keskkond on loodud kasutajatele, kes on väga erinevad: kes puutuvad e-ehituse teenustega
kokku vaid kord aastas, kelle jaoks on e-ehituse keskkond igapäevane töövahend. Me ei eelda kasutajalt
tehnilisi ega ehituse alaseid süvateadmisi ning oskust kantseliitlikust tekstist vihjeid välja lugeda.
Soovime, et kasutaja leiab kõigile küsimustele kiired vastused ja et ta tunneb end keskkonnas hästi.
Ühekordse küsimise põhimõte
Me ei küsi asju, mida juba teame. Kui informatsiooni, mida me kasutajalt soovime, on meile juba teada,
siis teist korda sama infot küsida ei ole vaja. Eeltäidame vormides võimalikult paljud väljad, et kasutaja
saaks varem teada infot uuesti kasutada. Võimalusel kasutame brauseri mälu andmeid.
KISS ja vaid vajalikud elemendid
„Keep it short and simple“ ehk KISS-printsiip. Kasutajaliides peab olema lihtne ja arusaadav, ülesanded
peavad olema lahendatavad minimaalsete tegevuste ja sammudega. Sellest tulenevalt eemaldame
ebavajalikud elemendid. Kasutajale ei ole vaja näidata kogu võimalikku infot ja kasutajaliidese elemente.
Igas kasutajaliideses on olulised elemendid ja väheolulised või isegi mõttetu süsteemi info. On tarvis
keskenduda olulistele elementidele ning vältida visuaalset müra.
Tugineme kaasaegsete rakenduste üldlevinud omadustele
Kasutajaliidese elementide loomisel tuleb eelistada kasutajaile juba varem harjumuspäraseks saanud
elemente ning ikoone. See vähendab kasutaja õppimisaega. Harjumuspärasuse all mõistame siinjuures
häid levinud töötavaid süsteeme (Google, Google Maps, MS Office, tavapärane brauseri rakenduste
käitumine jms), mitte olemas olevat EHR rakendust (seisuga veebruar 2020). Ühtlasi me järgime
viimastest kasutajaliidese ja teenuste arendamiste nõuetest, sh WCAG 2.1.
Näiteks, kuid mitte lõpliku nimekirjana, tuleb arvestada järgnevaga:
- Rakenduses peab saama kasutada levinumaid klahvikombinatsioone, nagu ctrl+z = undo;
ctrl+y = redo (ehk undo tagasi võtmine), nii undo kui redo toimivad ühe välja piires, kui
funktsionaalsetes nõuetes ei ole nõutud teisiti; ctrl+c = kopeeri; ctrl+x = lõika; ctrl+v = kleebi;
ctrl+s = salvesta; ctrl+p = trüki jm.
- Väljadel, millel on teksti vormindamine lubatud ctrl+b, ctrl+u vms tegevused.
- Klaviatuuri kasutamine kasutajaliideses liikumiseks ja andmete sisestamiseks on tagatud.
- Enteri vajutus lõpetab fookuses oleva välja täitmise ja viib fookuse järgmisele väljale või klikib
fookuses olevat nuppu.
- Shift + hiire kerimisratas kombinatsioon lubab horisontaalset kerimist.
- Rakendus pakub autocomplete-i, kui kasutaja on oma brauseril lubanud enda andmete
autocomplete-i vormides (e-post, telefon, nimi, aadress…).
- Mobiilses seadmes pakub rakendus vastavalt välja iseloomule ise tähtede või numbrite
klaviatuuri.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 5 / 18
E-ehituse platvormi stiiliraamat
- Kerimist (scrollimist) eelistame klikkimisele
- Eelistame vormide sisu näidata ühes veerus (ei kehti tabelite kohta).
Me ei ole kinni harjumuspärases
Tuntud kui innovaatori dilemma. Meil on varasemast kasutajaid, kellel on juba kujunenud harjumused,
kuidas asju teha. Uute teenuste loomisel ei saa me lähtuda ainult olemasolevatest tavadest, vaid peame
looma ka uusi võimalusi, mis saavad traditsioonideks tulevikus. Samuti, olles suures osas avalike
teenuste vahendaja, peame oma kasutajaliideses tihti pigem kasutaja käitumist uuele teele suunama,
kui et kasutaja harjumuslikule käitumisele kaasa aitama.
Kus asjakohane, säilitame võimaluse asju „pool-vanamoodi“ teha. Näiteks, ehkki ehitusteatise
alustamine ehitise andmetelt või kaardilt on lihtsam ja intuitiivsem, säilitame võimaluse valida menüüst
vastava vormi alustamise, et need, kes on harjunud varasema keskkonnaga, ei satuks segadusse.
Uues keskkonnas säilib vähemalt esialgu ka võimalus paberi(sarnaste) dokumentidega tegutsemine,
kuid eesmärk on minna üle täielikult digitaalsele süsteemile.
Infot kuvame infole omasel viisil
Ehitusalane info on suures osas graafiline, mida esitatakse jooniste, pildimaterjali, 3D mudelite ja
kaardiinfo abil. E-ehituse keskkonnas peab kasutaja saama infot esitada ja vaadata võimalikult
lähedasena selle olemusele. Seetõttu kogume ja kuvame lisaks tekstile infot kaardil ning võimaldame
graafilist materjali näha graafilises esituses (nt jooniste vaatamine).
Ehitusalane dokumentatsioon sisaldab suurel hulgal üles laaditavat sisu. Olgu selleks ehitusprojektid
või fotod ehitistest. Kõike seda peab saama keskkonnas mugavalt kasutada. Kui kasutaja brauser
võimaldab üldlevinud failiformaatide (pdf, jpg, png, ...) eelvaateid, siis kasutajale tuleb võimaldada
eelvaate näitamist, kuid võimaldame ka faili alla laadimist. Üldjuhul ei tohi eelvaate/alla laadimise vahel
valimine kasutajale täiendavat klikki/vormi avamist kaasa tuua, kuid kasutaja peab olema teadlik, et
seadmesse fail salvestatakse. Seetõttu küsime kasutajalt, kas ta soovib faili alla laadida. Eelvaade
avaneb vastavalt ärijuhule kas uuel brauseri vahelehel või teenuse peal modaalis, hallil taustal.
Kui e-ehituse keskkonnas on realiseeritud vektorgraafika moodulid (näiteks BIM-projektide
menetlemine), pakume kasutajale ka vektorgraafikale (nt dgn, dwg, ifc) eelvaadet.
Grupeerime tegevused ja sisu
Grupeerime info loogilisteks osadeks. Lehel oleva informatsiooni jaotame loogilisteks plokkideks
(gruppideks), nii on kasutajatel lihtsam sisust aru saada. Infot grupeerime näiteks:
- Selle järgi, kus see asub ekraani vaatel (vt Lisa 4. Ekraanivaate ülesehitus)
- Menüüpunktidesse (vt Lisa 4. Ekraanivaate ülesehitus)
- Teenustesse (vt Lisa 1. Stiilielemendid)
- Vormi sees vormi sammudeks, vahelehtedele, vormiplokkidesse (vt Lisa 1. Stiilielemendid)
Oleme selged, et mitte panna kasutajat kahtlema
Ülesannete lahendamine peab olema ilmselge. Nupud ja lingid peavad täpselt näitama, kuhu nad viivad.
Kahemõttelist teksti tuleb vältida. Tuleb vältida keerulisi tegevusi, mis panevad kasutajat kahtlema
tegevuste sisus, mõttekuses või protsessis.
Ekslike tegevuste kaitse
Väldime olukorda, kus kasutaja kaotab juba tehtud töö.
- Vormil andmete salvestamine hõlmab kõikidel vormi vahelehtedel olevaid andmeid.
- Andmete automaatsalvestamist ei toimu, kui funktsionaalsetes nõuetes ei ole ette nähtud teisiti.
Küll aga peame kasutajale meelde tuletama, kui ta on unustamas andmete salvestamist. Kui
kasutaja liigub vormilt välja ja andmed on salvestamata, siis kuvatakse kasutajale teade tekstiga
„Oled lahkumas vormilt. Kas soovid kavandi salvestada?“. Vastused „Jah“ (vaikimisi fookuses),
„Ei salvesta“, „Jätkan vormi täitmist“.
- Vormil hüpikakendes ja modaalides tuleb kasutajal muudatuste salvestamiseks need eraldi
salvestada või lisada (nt tabelisse rea lisamine, faili lisamine).
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 6 / 18
E-ehituse platvormi stiiliraamat
- Salvestamise kohta kuvame infot. Pärast salvestamist on vormi kohal info andmete
salvestamise kohta „Salvestatud“. Kui kasutaja on andmeid muutnud, on kiri „Salvestamata“.
Lisaks tegevustele ja valikutele kinnituste pakkumisele, peab kasutajal olema võimalus neid ka tühistada
(Loobun taotlusest).
Kaitseme ja ennetame kasutaja poolt sisestatud info vääriti mõistmist ja parandame tema eest vead.
Numbriliste väärtuste sisestamisel aktsepteerime koma asemel ka sisestatud punkti ja parandame
sellised formaadivead juba kasutaja eest ise. Näiteks koma/punkt, liigne tühik, suur/väike täht on meil
võimalik rakenduses üle vaadata.
Kasutame piiravat andmete sisestamist. Näiteks valikvastused, kuupäeva väli jms. Vormide üles
ehitamisel eelistame andmete sisestamist ühes tulbas asuvate väljadega ja vajadusel kasutame
tabeleid.
Seadmele kohanduv kasutajaliides
Rakendused peavad arvestama kõikide sisestusviiside (klaviatuur, hiir, puuteekraan jne) ning
esitlusviisidega (mobiiltelefon, suur ekraan, tahvelarvuti ekraan või ekraanilugejad).
Oleme järjepidevad
Erinevad keskkonnad, selle osad või alamsüsteemid peavad toimima sarnastel põhimõtetel. Kasutaja
jaoks ei tohi olla tuntavat vahet erinevatel aegadel ja erinevate tegijate poolt loodud süsteemide vahel.
Visuaalselt sarnased asjad teevad sarnaseid tegevusi.
KEELEKASUTUS JA TEKSTIDE KOOSTAMINE
E-ehituse keskkonna sõnastused toetavad kasutajat e-teenuste kasutamisel. Menüüde, nuppude,
linkide, selgituste jm lihtne ja arusaadav keelekasutus on keskkonna loogiline osa. Kasutaja ei pea
üldjuhul abi saamiseks juhendeid lugema või konsultatsiooni kasutama.
Üldised nõuded tekstile
1. E-ehituse keskkonna suhtlusstiil on riigile omaselt asjalik ja korrektne, kuid samas sõbralik,
toetav ja julgustav.
2. E-ehituse keskkonna keelekasutus järgib õigekirjareegleid, on kantseliidivaba ja erialase
žargooni vaba (näiteks ütleme „maja number“, mitte „aadressinumber“).
3. Kasutajaga suhtlemisel kasutame Sina vormi, nt “Aadress on aegunud, palun lisa uus aadress!”.
4. Sõnastused on koostatud kliendi vaatest lähtuvalt, nt “Minu andmed / taotlused / ehitised”, mitte
“Teie andmed”.
5. Kasutame läbivalt ühtseid ja korrektseid termineid, nt “EHR”, mitte “ehitiste register” vmt.
6. Väldime umbisikulist tegumoodi ning kolmandas isikus pöördumist, nt „Tallinna
Linnaplaneerimise Amet on taotluse menetlusse võtnud“ (või „Kohalik omavalitus on taotluse
menetlusse võtnud“), mitte „Taotlus on menetlusse võetud.“
7. Võimalusel väldime võõrsõnu ja lühendeid. Lühendeid kasutame vaid juhul, kui need antud
kontekstis üheselt ja selgelt mõistetavad (näiteks EHR).
8. Pealkirjad lõpevad ilma kirjavahemärgita, tekstivälja pealkirja järel koolonit ei märgi, teenuse
pealkirja järel ei kasuta punkti.
Nuppude ja linkide sõnastused
E-ehituse keskkonna näol on tegemist iseteeninduskeskkonnaga, kus üldjuhul otsustab kasutaja ise,
millise tegevuse ta valib ja teeb. Selliste tegevuste sõnastused on nuppudel ja linkidel mina-vormis.
Näiteks: Salvestan, Esitan, Saadan, Kustutan, Muudan, Laadin alla, Trükin, Valin vormi.
Vajadusel võib kasutada ka järgmisi sõnastusi:
1. Tegevused, mis viivad teisele teenusele või avavad uue toimingu. Näiteks: Uus kasutaja, Uus
hooneosa, Uus märkus
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 7 / 18
E-ehituse platvormi stiiliraamat
2. Tegevused, mis on pigem süsteemsed, ja mille sõnastamiseks on välja kujunenud ühene
kasutuspraktika. Näiteks: Otsing e-ehituse keskkonna päises, Vali, Märgi, Jäta mu valik meelde,
Edasi, Tagasi (taotluse juurde)
Abiinfo
Kasutajale tuleb teha kättesaadavaks abiinfo
1. Kasutajajuhend sisaldab teenuse kohta käivaid abistavaid materjale, mis aitavad kasutajal täita
vorme, mõista erinevaid toimimisloogikaid ning teha paremaid ja informeeritumaid otsuseid.
Kasutajajuhendi koostamisel väldime seaduste ümberkirjutamist. Tekstid on hästi liigendatud,
pikemas tekstis kasutame sisu kokku võtvaid vahepealkirju. Materjalid võivad olla esitatud ka
videojuhenditena, skeemide või illustratsioonidena.
2. Sõnastik. Selgitame teenuse ja teemaga haakuvaid termineid ja lühendeid nagu EHR, ADS jmt
ning seaduste ja määruste lühendeid.
3. KKK. Siia koondame abimaterjalid teenuste kasutamise kohta küsimuste ja vastuste vormis.
Sisulistele küsimustele ja vastustele lisame viitena veebi lingi.
Veateated
Veateade:
1. peab olema viisakalt, positiivselt sõnastatud (näiteks „Palun sisesta oma e-posti aadress“, mitte
„E-posti aadress sisestamata!“);
2. ütlema probleemi põhjuse ja viitama, mille kohta see veateade käib (näiteks „Sisestatud
kasutajanimi ja parool ei sobi kokku“, mitte „Sisselogimine ebaõnnestus“);
3. peab selgitama kasutajale, kuidas ta saab probleemi lahendada (näiteks „Köetav pind ei saa
olla suurem kui suletud netopind“, mitte „Pindade suurused ei ühti!“ ja näiteks „Selle nimega fail
juba eksisteerib“, mitte „Faili nimi on vigane“);
4. vajadusel soovitab kasutajale, kust ta saab täiendavat informatsiooni;
5. peab olema tavakasutajale / tehnilisi teadmisi mitteomavale inimesele arusaadavalt sõnastatud;
6. ei sisalda ballasti (näiteks „Köetav pind ei saa olla suurem kui suletud netopind“, mitte „Ups!
Paistab, et köetava pinna suurus on rohkem kui suletud netopind. Palun paranda ära.“)
7. kui on kohane, annab kasutajale võimaluse kohe probleem lahendada (näiteks „Selle nimega
fail juba eksisteerib. Kas soovid a) automaatselt uue faili ümber nimetada; b) muuta selle nime
käsitsi“, mitte „Faili nimi on vigane“).
Üldised teated (katkestused, uuendused, muudatused)
Teated on selgelt sõnastatud ja piisavalt täpselt kirjeldavad olukorda. Näiteks:
„Neljapäeval, 17.03.2016 kell 18.00–18.30 toimub seoses tehniliste hooldustöödega katkestus e-ehituse
keskkonna teenuste kasutamises. Vabandame.“
„Neljapäeval, 3. märtsil 2016 kell 7.00–9.00 toimub seoses versiooniuuendusega Andmete esitamise
teatise koostamise ja esitamise teenuste töös katkestus. Vabandame võimalike ebamugavuste pärast.“
Reeglid numbrite kirjutamisele
Valuutad ja rahaühikud
Valuutade märkimiseks kasutame rahvusvahelisi lühendeid, nt EUR, USD, GBP, NOK, RUB jne.
Eurot võib teksti sees märkida kas sõnaga (10 eurot) või tähisega (10 €).
Euro ja eurosendid eraldame tekstis komaga, mitte punktiga. Sama reegel kehtib tabelis, kus rahaühikut
iga summa juures eraldi ei märgita, nt 100,50.
Telefoninumbrid
Telefonumbrid kirjutame Rahvusvahelise Sideliidu ning Tarbijakaitse ja Tehnilise Järelevalve Ameti
soovituse kohaselt tagantpoolt alates neljakaupa:
- 7-kohalised telefoninumbrid: 123 4567
- 8-kohalised telefoninumbrid: 1234 5678
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 8 / 18
E-ehituse platvormi stiiliraamat
- rahvusvahelised telefoninumbrid: +372 123 4567
- lühinumbrid: 123
Rahvusvahelise riigikoodi alguses on plussmärk, riigikoodi ei panda sulgudesse.
Kuupäevad
- Kuupäevad kirjutame kujul pp.kk.aaaa (nt 12.05.2016).
- Ajavahemikku märgime nii: 12.05.2016–20.05.2016.
Arvude vahel ei ole tühikuid. Arvude vahel asendab sõna “kuni” mõttekriips.
Parema loetavuse ja selguse huvides võib tekstis kasutada ka järgmisi võimalusi: 12.–20. mail; 12.–20.
maini; 12. kuni 20. maini.
Arvud ja summad
Tabelites joondame numbreid üldjuhul paremale. Koodidesse (isikukood, EHR kood vms) ja
telefoninumbritesse suhtume kui teksti ja need joondame üldjuhul vasakule.
Komakohtade arv numbri lõpus sõltub ärivajadusest. (pindala vs korruste arv jm.)
Tekstides järgime eesti keele reeglit: viie- ja suuremanumbrilistes arvudes jagame numbrid kolme
numbri kaupa rühmadesse lõpust alates, nt 6 748 422,00. Järguühikute vahel ei ole komasid:
1 000 000,00
10 000,00
1 000,00
Koodides (ka kümnendmurdudes) numbreid ei rühmita, nt isikukood 44204280253, pangakonto
11024846781, registrikood 10223787.
Negatiivsete arvude korral kirjutame "miinus" märk ja "number" omavahel kokku, tühikut ei jäta. Lisaks:
miinus puhul kasutame mõttekriipsu (pikem), mitte sidekriipsu (lühem).
Arvu ja mõõtühiku või selle lühendi või tähise vahel on üks tähekoht vahet, nt 10 €, 10 m.
Erandiks on protsendi lühend, mis kirjutatakse eelneva arvuga kokku, nt 16%.
TÕLKED
Kasutajaliides on üles ehitatud eestikeelsena, kuid nii, et seda on võimalik kohandada erinevatesse
keeltesse tõlgitavana (nupud, väljade nimed, abitekstid jne ei ole staatilised).
E-ehituse keskkonna aluskeeleks on eesti keel. Kasutajal on tulevikus võimalik oma keele-eelistust
muuta, kasutades selleks vastavaid linke keskkonna päises. Valitud keele jätab keskkond iga kasutaja
jaoks meelde. Kui kasutaja vahetab keelt mõne teenuse sees (näiteks taotluse vormil), siis peale
keelevahetust viiakse ta samale lehele, kus ta keelevalikut alustades viibis.
Tõlgitakse kogu kuvatav sisu, sh nuppude tekst, sisutekst, piksel- ja vektorgraafika, millel on tekst.
Teenuste puhul, mille loomisel ei ole keelevaliku nõudega arvestatud, kuvame kasutajale teenuse
eestikeelset versiooni.
KASUTAJALIIDESE KUJUNDAMISE PÕHIMÕTTED
Alusjoonestik
https://styleguide.ehr.ee/#section-css-classes
Keskkonna kasutajaliidese aluseks on alusjoonestik ehk grid. Alusjoonestik võimaldab defineerida
kõikide disainielementide omavahelised proportsionaalsed suhted. Alusjoonestik muudab disaini
korrapäraseks, selgeks ja kasutajatele arusaadavaks.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 9 / 18
E-ehituse platvormi stiiliraamat
Alusjoonestik on jagatud 20 tulbaks. See tähendab, et näiteks enimlevinud 1200 piksli laiune ala on
jaotatud maksimaalselt 20 tulbaks, milles iga tulba sisu laius on 40 pikslit ja igast tulbast mõlemale poole
jääb 10 piksli suurune kaitseala.
Kasutaja kontekstile kohalduv disain
Responsive design ehk kohalduv disain tähendab, et teenuse sisuelemendid arvestavad, millise
ekraaniga teenust vaadatakse, ja kohaldavad sisu vastavalt sellele.
Erinevate ekraanide puhul arvestame kolme põhilise seadmega: nutitelefon, tahvelarvuti,
sülearvuti/monitoriga arvuti. Vastavalt sellele jaotusele määratakse ka kohalduva disaini murdepunktid
(breakpoint), mis näitavad, millisest vaate laiusest alates muudetakse sisuelementide paigutust.
Tänapäevaste levinuimate resolutsioonide järgi nendel kolmel seadme tüübil, kasutame murdepunkte
järgnevalt:
1. Nutitelefon: 320px–599px
2. Tahvelarvuti (portrait): 600px–899px
3. Tahvelarvuti (landscape): 900px–1199px
4. Sülearvuti või monitoriga arvuti: üle 1200px
Tahvelarvuti vaate (600px-1199px) erinevus desktop vaatest seisneb peamiselt menüü lahenduses.
Peidame küljemenüüd, et kasutaja saaks keskenduda teenuste sisule. Globaalne menüü on peidetud
menüü ikooni alla, millel vajutades see avaneb.
Tahvelarvuti landscape vaate (900px–1199px) sisu kuvamine desktop vaatest ei erine. Sellesse me
suhtume kui väikesema resolutsiooniga desktop vaatesse.
Tahvelarvuti portrait mode vaate (600px-899px) puhul kuvame lehe sisu ühes veerus.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 10 / 18
E-ehituse platvormi stiiliraamat
Abikeskuse paremalt poolt avanev ala suleb avatud globaalse menüü (juhul kui see oli vastavas vaates
avatud) ja teeb sisuala kitsamaks. Abikeskuse ploki ala laius on muutumatu.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 11 / 18
E-ehituse platvormi stiiliraamat
3 EKRAANIVAATE ÜLESEHITUS
Ekraanivaate malli ülesehitus:
- Kes > päis (ja millises rollis > kasutaja valiku molekul)
- Mida > burger
- Kuidas > menüü
- Teeb > töölauad, kus kuvame teenused
- Info > jalus
- Abi > abikeskus
Kuva komponentide sisse seadmisel tuleb jälgida, et iga komponent peab töötama. Näiteks, kui sõltuvalt
kasutaja õigustest või arendustöö järjest ei ole teenus saadaval, siis selle teenuse välja kutsuv
nupp/ikoon/link ei ole kuvatud rakenduses.
PÄIS
Autentimata kasutaja päis
Päises on:
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 12 / 18
E-ehituse platvormi stiiliraamat
- Burgeri peanupp
- Teenuste otsing
- Keele valik
- Uudisteadete ikoon
- „Sisenen“ nupp
Autenditud kasutaja päis
Päises on:
- Burgeri peanupp
- Kasutaja valik
- Teenuste otsing
- Keele valik
- Uudisteadete ikoon
- Vestluste ikoon
- Teadete ikoon
- Kiirviidete ikoon
- Sisse loginud füüsilise isiku nimi
- „Väljun“ nupp
Päise koostisosad
Päise ikooni ja nuppude grupid on eraldatud vertikaalse punktiirjoonega (vt päise illustratsiooni).
Burgeri peanupp
Kui menüü on avatud, siis kuvab menüü sulgemise ikooni:
Kui menüü on suletud, kuvab menüü avamise ikooni:
Kasutaja valik
Siin kuvab, millise kasutaja rollis sisse loginu hetkel on. Esmakordsel sisse logimisel on kasutaja
autenditud avaliku kasutajana (tema ise füüsilise isikuna). Kasutaja saab endale kasutaja halduses
määrata omale sobiva vaikimisi kasutaja.
Kasutajat saab vahetada hüpikmenüü abil. Kasutajad on järjestatud asutuse nime tähestiku järjekorras.
Kõige esimene valik on alati avalik autenditud kasutaja (see valik ei arvesta tähestiku järjekorda).
Kui kasutajate variante on üle 10, siis on hüpikmenüül scrollbar.
Teenuste otsing
Teenus otsib vasteid rakenduse lehekülgede tekstidest. Esialgsed tulemused kuvatakse hüpikmenüüs.
Kasutaja saab avada kõikide tulemuste lehekülje.
Keele valik
Teostame siis, kui teostame mitmekeelsuse.
Uudisteadete ikoon
Analoogne lahendus vestluse hüpikmenüüle.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 13 / 18
E-ehituse platvormi stiiliraamat
Kõikide uudiste valimine avab uudiste lehekülje.
Kindla uudise valimine avab uudiste lehekülje avatuna valitud uudise artikli juures.
Vestlused (foorum). KOV kasutajatele
Kõikide vestluste valimine avab suhtluskeskkonna lehekülje.
Kindla vestluse valimine avab suhtluskeskkonna lehekülje avatuna valitud vestluse viimase
kommentaari juures.
Teated (seadete ja taotluste juures tellitud teavitused)
Analoogne lahendus vestluste flyoutile.
Kõikide teadete valimine avab teadete lehekülje.
Kindla teate valimine avab teadete lehekülje avatuna valitud teate juures.
Kiirviited
Kasutaja saab määrata lemmiklehed kiirviiteks, näitab
1. Määratud kiirviidete valikut
2. Hetkel avatud oleva lehe kiirviidetesse lisamise või eemaldamise võimalust
Abikeskus
(?) – Ikoonist avaneb abikeskus ekraani paremal küljel.
Abikeskuse lahendus vaata peatükk Abikeskus
Sisse loginud füüsilise isiku nimi
Kasutaja andmete alale klikkides avaneb flyout kiirvalikutega e-ehituse keskkonna kasutajaga otseselt
seotud lehtedele. Esialgu teostame lingi lehele „Minu andmed“
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 14 / 18
E-ehituse platvormi stiiliraamat
„Sisenen“ nupp
Selle nupu klikkimisel käivitub TARA autentimise teenus.
„Väljun“ nupp
Nupu vajutamisel avaneb kinnitusvorm:
MENÜÜ
Menüü asub ekraani vasakul küljel ja koosneb kahest osast:
- Burger, kus jaotatakse teemad suurtesse plokkidesse
- Menüü, kus on suure ploki alateemad (Läbivalt suurte tähtedega kirjutatud) ja alateemad e
teenused (suure algustähega).
Kogu e-ehituse kasutajaliides on jaotatud suurtesse teemaplokkidesse, millel on alajaotused. Vastavalt
kasutajate õigustele, kuvatakse kasutajagrupile või konkreetsele kasutajale lubatud teemad ja
teenused.
Ilma sisse logimiseta on ligipääs avalikule infole.
Burgeri nupul vajutades avaneb halli menüü vastav teemade ja teenuste nimekiri. Töölaual avaneb sellel
hetkel esimese halli menüü pealkirja teenus/teenused.
Kasutaja saab halli menüü järjekorda muuta (kahest kriipsust kinni võttes saab pealkirjade järjekorda
muuta). Rakendus jätab meelde kasutaja menüü järjekorra ja avab iga kord kõige esimese pealkirja.
Hall menüü avaneb töölaua peale.
Aktiivne menüüpunkt on sinise kirjaga:
Menüü avatud:
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 15 / 18
E-ehituse platvormi stiiliraamat
Menüü peidetud:
Vaikimisi on kasutajal sisenemisel burgeri menüü avatud ja hall menüü suletud.
Kui kasutajale on tulnud mingi reaktsiooni nõudev teade (Näiteks allkirjastamiseks või arvamuse
avaldamiseks), siis sisse logides avaneb töölaud kohe selle koha pealt, kus reaktsiooni vaja on,
olenemata sellest, mis on kasutaja eelistused.
TÖÖLAUD
Töölaud on ekraanivaate ala, kus kõik toimub ja kus kuvatakse teenused – veebilehekülg (nt Ehitusloa
taotlus, Andmete esitamise teatis, minu menetlused). Töölaud on halli taustaga. Sellel kuvatakse valgel
taustal teenused. Teenused on iseseisvad, see tähendab, et kui kuvatakse mitu erinevat valge taustaga
teenust, siis need üldjuhul ei ole omavahel seotud.
Rakenduse töölaual paiknevad teenused. Teenused koosnevad päisest ja teenuse alast. Teenuse alal
avanevad nii ülevaated tabelid, kui vormid, vastavalt ärivajadusele.
JALUS
E-ehituse keskkonna jalus on kujundatud põhimõttel “mida soovin edasi teha?” Kui kasutaja on jõudnud
lehe lõppu, on ta alati valiku ees, kas minna tagasi üles, liikuda edasi kusagile mujale või võtta ühendust
keskkonna omanikuga. Seepärast pakub jalus võimalust kõiki kolme teha.
Sotsiaalmeedia ala
„Tagasi ülesse“ nupp viib kasutaja tagasi lehe algusesse.
Sotsiaalmeedia ikoonid avavad uues aknas vastava sotsiaalmeedia keskkonna. Nupud linkidega
lisatakse, kui vastav sotsiaalmeedia kanal üles seatakse. Esialgu FB lingitakse MKM FB lehele.
e-ehituse veebi nupp viib kasutaja eehitus.ee lehele.
Logod
Jaluses on Majandus- ja kommunikatsiooniministeeriumi ning rahastuse ikonograafia.
Kiirelt kätte lingid
Need lingid viivad kasutaja e-ehituse, MKM või mõne teise kodulehe vastav rubriigi juurde.
Lingid on MKM peakasutaja vaates hallatavad.
Saab lisada kuni 6 linki. Rakendus ise lülitab sisse välja viiva lingi ikooni, kui URL ei suuna samale
domeenile.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 16 / 18
E-ehituse platvormi stiiliraamat
Versiooni link kuvab rakenduse viimase versiooni numbrit. Lingile klikkides viib rakendus kasutaja
versiooniuuenduste lehekülje peale, avatud on viidatud versiooniuuenduse kirjelduse plokk.
Kontaktinfo
Seni, kuni ei ole suhtluskeskkond arendatud, on kontaktinfos e-post. Kui suhtluskeskkond on valmis,
siis menetlejale ja MKM-ile on “Alustan vestlust”
e-postil klikkides toimub selle e-posti “Ctrl+C” + tuleb roheline töölaua teade “e-post kopeeritud”.
Kontaktinfo jaotuse kohal hiirega olles või puuteekraanil pika vajutuse korral ilmub tooltip kokkuvõtva
abitekstiga selle kohta, kellega kasutaja võiks ühendust võtta.
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 17 / 18
E-ehituse platvormi stiiliraamat
4 ABIKESKUS
E-ehituse platvormi arendamisel on eesmärgiks see võimalikult selgelt üles ehitada ja teenused
võimalikult loogiliselt kasutajale esitada, kuid sellegi poolest on kasutajal vaja abi, mille tarbeks on
keskkonnas abikeskus. Abikeskus avaneb töölaua kõrvale paremas servas. See on iseseisev ekraani
osa, mis ei keri sisulehega kaasa. Sellel on oma scrollbar.
Abiinfo KKK Teated
Töölaual avatud oleva teemaga Töölaual avatud oleva teemaga Nt seaduseid, määruseid vm
seotud info- ja abimaterjal. seotud korduma kippuvad suurt küsimust puudutavad
Näiteks vormi täitmise juhend, küsimused. ajakohased olulised teated
kaardi kasutamise juhend vms. kogu kasutajaskonnale
Uuendas 30.03.2021 Ingrid Aasoja-Zverev lk 18 / 18
Ehitisregistri (EHR) rakenduse koodi haldamise ja tarnejuhend
Dokumendi eesmärk: Juhend on mõeldud EHR arendajale ning juhendis on kirjeldatud reeglid, EHR
rakenduste tarnimiseks EHR testi ja toodangu keskkondadesse. EHR rakendused on:
• EHR olemas olev Java rakendus
• EHR kaardirakendus
• EHR VRM e. võrgurajatiste rakendus
• EHR React e. uus kasutajaliides
• EHR API e. uued teenused ja teenuste seotud rakendused Kubernetes klastris
• Andmeait
EHR Java rakenduse1 tarneprotsess
1. EHR lähtekood paikneb Git https://git.mkm.ee/ehr/ehr-monolith-pipeline. Uue EHR Java
rakenduse versiooni arenduse alustamisel tuleb algkood võtta alati Git ehr/ehr_main
ehk peaharust. Iga arendaja vastutab, et kõik peaharusse teiste arendajate poolt tehtud
muudatused, mis on tehtud peale koodi arenduseks võtmist, on koodi sisse viidud
enne, kui rakendus viiakse testiks prelive keskkonda (test.ehr.ee).
2. EHR koodi versioneeritakse ja algkoodi võtmisel peab arendajal olema teada, et millise
versiooni alusel arendustööd teostatakse. Rakenduse tarnimisel ükskõik millisesse
testi (test, test2, test3) keskkonda tuleb alati suurendada rakenduse versiooni numbrit
ning uus versiooni number peab olema näha rakenduse avalehelt. Versiooni number
peab vastama Semver 2.0 standardile.
3. Git peaharusse võib lisada ainult töötavat (kompileeriv, unit testid töötavad ja
www.ehr.ee e. toodangukeskkonnas töötavat) koodi. Koodi lisamiseks teeb arendaja
Git-s „Merge requesti“ hiljemalt rakenduse toodangusse tarnimise päeval. „Merges“ ei
tohi esineda konflikte. Pärast „merge requesti“ tegemist informeeritakse (projekti Skype
vestluses) partnereid ja MKM projektijuhti.
Kõik andmebaasi muudatustega seotud SQL scriptid peavad olema samuti paigaldatud
Git peaharu EHR DB haru alamharusse. Alamharu nimetus peab sisaldama aasta kuu
ja päeva ning rakenduse versiooni numbrit. Selgitusse tuleb lisada arendaja firma nime
ja rakenduse versiooni numbri.
4. Arendustööde üleandmine algab rakenduse paigaldamisest EHR testikeskkonda (test
2 või 3). Esmalt paigaldatakse andmebaasimuudatused. Selleks koostada andmebaasi
muudatuste skriptidest paigalduspakett ja lisada see tarnepakettide FTP-sse
(ftp.mkm.ee/tarned). Peale FTP-sse tarnepaketi lisamist koostatakse JIRA keskkonnas
(https://jira.mkm.ee/projects/MKMEHR/) tarnepilet (pileti tüüp = „tarne“) ja suunatakse
see majutaja esindajale (Eero Tammelaan). Tarnepiletisse lisatakse viide tarnepaketile
ja juhend tarnimiseks. Samuti lisatakse piletisse tarnepaketiga tehtavate uuenduste
lühikirjeldus ja vajadusel ka parandatud veapiletite loetelu.
Juhul, kui tarnepaketis sisaldub rohkem kui üks käivitamist vajav skript siis peab
tarnepakett sisaldama nn. masterskripti, mille abil käivitatakse kõik tarneskriptid õiges
järjekorras.
1 EHR Java rakendus on olemas olev Tieto majutuses olev monoliitrakendus, mis ei kasuta mikroteenuste
arhitektuuri.
5. Rakenduse paigalduseks testikeskkonda toimub automaattarnega. Kood viikse Git
harusse, mis vastab testikeskkonnale: test2 või test3. Peale koodi harusse viimist
käivitub automaattarne, mis kompileerib koodi, viib läbi esmase testi ning peale seda
on rakendus vastavasse testikeskkonda paigaldatud. Automaattarne kirjeldus on
toodud: Automaattarne protsessi kirjeldus
6. Peale majutaja poolt tarnepaketi testikeskkonda paigaldust (info selle kohta kajastub
tarneks tehtud JIRA piletis, kui tarnija poolt tehakse pileti staatuse muudatus) peab
tarnija koheselt kontrollima, et paigaldatud pakett töötab vigadeta ning käivitama
Katalon automaattestid (https://git.mkm.ee/EHR-testid/automaattestid). Peale
automaattestimise lõppu esitab Täitja üleandmise akti. Tellija poolne test algab kohe
peale tarnija poolse üleandmise akti esitamist.
7. Paigalduspaketi koostamisel tuleb kasutada EHR Archiva repositooriumi vastavalt
juhendile: EHR Archiva juhend
8. Juhul, kui testkeskkonda paigaldatud pakett sisaldab „kriitilisi“ vigasid ka peale
teistkordset testikeskkonda paigaldamist peab Tarnija Tellija projektijuhi nõudmisel
tarnepaketi testikeskkonnast eemaldama. Paketi eemaldamine on vajalik, kui mõni
teine tarnija soovib vahepeal oma arendused üleandmiseks testikeskkonda tarnida.
9. Arendustööde üleandmine lõppeb peale arenduste paigaldamist rakenduse toodangu
keskkonda. Toodangu keskkonda paigaldamist võib alustada peale Tellija projektijuhilt
vastava teate saamist. Toodangu keskkonda paigaldus toimub analoogselt
testikeskkonda paigaldamisega. Tarnepakett -> FTP -> JIRA pilet - > paigaldus ->
arendaja test -> paigalduse aruanne.
10. Kogu loodud või muudetud lähtekood peab olema kommenteeritud, nii et see on kõigile
osapooltele arusaadav. Kommentaaridest peab olema tuvastatav, et kes, millal ja mis
eesmärgil on koodi muudatused teinud.
11. Kogu loodud või muudetud lähtekood peab olema kaetud moodultestidega (unit test);
EHR mikroteenuste paigaldusprotsess
1. EHR mikroteenuste rakenduste lähtekoodid paiknevad Git https://git.mkm.ee/ehr/ehr-
k8s-pipeline. Uue EHR mikroteenuste rakenduse arenduse alustamisel tuleb luua uus
projekt eelpool mainitud GIT gruppi.
2. Uue projekti loomisel tuleb projekti selgituseks lisada projekti eesmärk
3. Uue projekti loomisel tuleb projekti readme.md failis lisada juhend arendajale: koodi
käivitamiseks, testimiseks ja tarnimiseks ning vajadusel koodi teistes projektides
kasutamiseks. Readme failis peavad sisalduma viited tarnimiseks vajalikele secretitele
ja configmap-le ning Rancheris asua Helm Charti nimetus.
4. EHR mikroteenuste koodi versioneeritakse vastavuses Semver 2.0 standardile.
Rakenduse Helm charti2 tarnimisel Kubernetese keskkonda tuleb alati suurendada
rakenduse versiooni numbrit vastavuses Semver 2.0 standardiga, kujul “version-x.x.x”.
5. Git peaharusse “Master”, kust toimub automaattarne protsess võib lisada ainult
töötavat (kompileeriv, unit testid töötavad, Sonarcube raport vastab nõuetele3) koodi,
mida hakatakse toodangusse viimiseks testima.
6. Kasutusel on kaks Kubernetes klastrit: mkm-ehr ja mkm-ehr-tst. Kood tarnitakse esmalt
katsetusteks ja arendusteks mkm-ehr-tst klastri “Development” projekti, milles olev
andmebaas ja rakendused on seotud EHR Java rakenduse test3.ehr.ee nimelise
testikeskkonnaga ja test3 Oracle andmebaasiga.
a. Tellija poolseks testiks tarnitakse üle antavad rakendused mkm-ehr-tst klastris
“Test” projekti, milles olev andmebaas ja rakendused on seotud EHR Java
rakenduse test2.ehr.ee nimelise testikeskkonnaga ja test2 Oracle
andmebaasiga.
b. Peale Tellijalt kinnituse saamist viiakse üle antavad rakendused mkm-ehr
klastris “Prelive” projekti, milles olev andmebaas ja rakendused on seotud
EHR Java rakenduse test.ehr.ee nimelise testikeskkonnaga ja test1 Oracle
andmebaasiga. Prelive viimise teeb Tellija poolt määratud Majutaja, kes hiljem
tarnib rakendused ka toodangusse e. “Toodang” projekti. “Prelive”
tarnejuhendid tuleb lisada “Helm Charti” “readme” faili.
7. Iseseisvalt ei tohiks luua uusi Kubernetes namespace ja Rancher projekte. Juhul, kui
see on vajalik siis tuleb need Tellija projektijuhiga eelnevalt kooskõlastada.
8. Peale koodi viimist projekti peaharusse tuleb lisada Git Tag kujul “version-x.x.x”. Tagi
lisamine käivitab automaattarne protsessi vt. Automaattarne protsessi kirjeldus
9. Juhul, kui koodi muudatused eeldavad andmebaasi muudatusi siis andmebaasi
muudatustega seotud SQL scriptid peavad olema viidud Git
https://git.mkm.ee/ehr/databases grupis olevasse vastavasse andmebaasi projekti.
10. Arendustööde üleandmine algab rakenduse paigaldamisest EHR testikeskkonda
Rancher Test Projekt. Esmalt paigaldatakse andmebaasimuudatused. Selleks
2 Helm chart on rakenduse tarnejuhised, mille alusel käivitatakse Kuberneteses rakendusele vajalikud ressursid
8. 3Koodi Sonarqube raport https://sonarqube.mkm.ee/dashboard?id=<projektinimi> peab
olema:
a. Reliability Bug = 0
b. Security Vulnerability = 0
koostada andmebaasi muudatuste skriptidest paigalduspakett ja teostada selle alusel
paigaldus (vt. E-ehituse andmebaasid ja nende uuendamine).
11. Rakenduse paigaldus testikeskkonda toimub eelnevalt tarnitud ja testitud Helm
Chartiga ning järgib juhendit: Automaattarne protsessi kirjeldus
12. Peale rakenduste testikeskkonda paigaldust peab tarnija koheselt kontrollima, et
paigaldatud pakett töötab vigadeta ning käivitama Katalon automaattestid
(https://git.mkm.ee/EHR-testid/automaattestid). Peale automaattestimise lõppu esitab
Täitja üleandmise akti. Tellija poolne test algab kohe peale tarnija poolse üleandmise
akti esitamist.
13. Juhul, kui testkeskkonda paigaldatud pakett sisaldab „kriitilisi“ vigasid ka peale
teistkordset testikeskkonda paigaldamist peab Tarnija Tellija projektijuhi nõudmisel
tarnepaketi testikeskkonnast eemaldama.
14. Arendustööde üleandmine lõppeb peale arenduste paigaldamist rakenduse toodangu
keskkonda. Toodangu keskkonda paigaldamist võib alustada peale Tellija projektijuhilt
vastava teate saamist. Toodangu keskkonda paigalduseks koostab Tarnija JIRA pileti,
milles on toodud Helm Charti nimetus ja juhend selle käivitamiseks.
15. Kogu loodud või muudetud lähtekood peab olema kommenteeritud, nii et see on kõigile
osapooltele arusaadav. Kommentaaridest peab olema tuvastatav, et kes, millal ja mis
eesmärgil on koodi muudatused teinud.
16. Kogu loodud või muudetud lähtekood peab olema kaetud moodultestidega (unit test),
mis peavad olema arendaja poolt käivitatud enne rakenduse uue versiooni
paigaldamist Git koodihoidlasse;
EEHITUS API teenuste nimetused ja teenuste kirjeldamine
V6 – 05.03.2021 Ülo Puskar
Eesmärk: Dokument kirjeldab “eehitus” API teenuste ja kasutajaliidese URL-de (sisendpunkt)
kokkuleppeid
Sissejuhatus
API kirjeldamise reeglid on vajalik kokku leppida, et tagada ühtne API sisendpunkt nii, et teenuse
kasutajad ei peaks teadma, et millises EHR infrastruktuuri serveris teenust käitatakse ja teenuste
nimetused ei korduks. Lisaks API sisendpunktidele on kasutusel sisendpunktid andmebaasi
põhiobjektide EEHITUS kasutajaliideses avamiseks
Reeglid
1. API teenused ei tohi korduda. Uute teenuste loomisel tuleb esmalt veenduda, et olemas
olevas API-s juba pole sarnast teenust. Kui on siis tuleb olemas olevat teenust edasi
arendada, mitte luua uut teenust
2. API rakenduses olemasolevate teenuste kirjeldused tuleb enne teenuse loomist lisada EHR
API teenuste kirjelduste andmebaasi: https://git.mkm.ee/ehr/ehr-k8s-pipeline/swaggerui
3. Teenuse kirjeldused tuleb lisada “yaml” failina. Failinimi peab olema sama, mis Java (või
NodeJS või Python) paketi nimi, näiteks Java paketinimi “ee.ehr.document_api” siis teenuse
yaml faili nimi: “document_api.yaml”.
4. Teenuste URL nimetamisel tuleb järgida <domain>/api/nimetus/vN/…
a. <domain> tuleneb API rakenduse Rancher projektist. Igale Rancher projektile vastab
domain näiteks “devkluster.ehr.ee”
b. /api/ - kõigil API-del sarnane tähistus
c. Nimetus on APIt iseloomustava rakenduse nimetus, näiteks: arhiiv, andmeait,
statistikaportaal, kaardirakendus vms.
d. vN on API versiooni number, näiteks v1 v2 jne.
e. peale versiooninumbrit tuleb API teenust e. endpointi iseloomustav nimetus, mis ei
tohiks kattuda API-s juba kirjeldatud teenuse nimedega.
5. API teenuste uued versioonid peavad olema ühilduvad vähemalt kaks versiooni tagasi ehk
uue versiooni API “route” e. “url” peab toetama kahe eelneva versiooni “route” sisendeid ja
väljundeid.
6. API-l peab olema “route” /version, mis väljastab API kehtiva versiooni numbri kujul: “version-
x.x.x”.
7. API-l peab olema K8s “liveness probe”
8. API URL peab olema inglise keeles
9. API uuendamisel tuleb järgida põhimõtet, et kui muudetakse API-t sellises ulatuses, et
olemas olevates API-t kasutavates rakendustes tuleb teha API uuema versiooni kasutamiseks
muudatusi: (näiteks muudetakse API olemasolevate parameetrite nimetusi või lisatakse uusi
“kohustuslikke” parameetreid) siis tuleb muuta API URL-s versiooninumbrit ja tagada, et API
uus ja vana versioon töötaksid samaaegselt.
10. Uue API versiooni lisamisel tuleb Swaggeris olemasolev API responses: objekt tähistada
prefiksiga deprecated näiteks: kui responses: "Media type” on “application/json” siis uue api
"Media type” on “application/json” ja vana API "Media type” saab olema “deprecated-
application/json”. Analoogselt tuleks tähistada API parameetrid. Kui prameetreid
muudetakse siis kasutuselt maha võetavad parameetrid tuleks tähistada parameters:
description väljal “deprecated” märgendiga. “Deprecated” märgendiga objektid tuleks
kustutada Swagger kirjeldustest peale API aegunud versiooni kasutuselt eemaldamist.
11. Kasutajaliideses sisendpunkte omavad objektid on ehitis ja dokument. Objekti
identifitseerimiseks kasutame query stringi.
a. Ehitis sisendpunkt avab ehitise andmete vormi:
<domeen>/ui/ehr/v1/building?ehrkood=
b. Dokument sisendpunkt avab dokumendi andmete vormi:
<domeen>/ui/ehr/v1/document?doknr=
Teenustele Liveness probe lisamine
1. Liveness probe abil tuvastab Kubernetes perioodiliselt konteinerrakenduse töötamist ja juhul
kui probe ei anna http päringu vastuse staatuseks 20* -30* siis teostab konteineri restardi.
Koos liveness probega tuleks konfigureerida ka readiness probe, kuna ilma selleta võib
juhtuda, et aeglaselt käivituvale konteinerile tehakse enne restart, kui ta pole veel jõudnud
tööle hakata. Readiness probe kutsutakse välja kogu konteineri elutsükli jooksul (vt.
Võimalikud karid).
2. API-s peab olema endpoint, mille alusel saab teostada päringu API töösoleku kontrollimiseks
perioodiliselt päringuid näiteks timestamp küsimine andmebaasit vms. Endpoint peaks olema
mõni tegevus, mis võtab vähe ressurssi (aeg, maht).
3. Liveness probe lisamiseks deploymentile tuleb Helm chartis Kubernetese deploymentis
(deployment.yaml) kirjeldada konteinerile kaks probet: readiness, liveness näiteks:
spec:
containers:
readinessProbe:
failureThreshold: 10
httpGet:
path: /health
port: 3000
scheme: HTTP # kuna probe töötab ilma Ingressita siis peaks kasutama http
initialDelaySeconds: 10
periodSeconds: 30
successThreshold: 1
timeoutSeconds: 3
livenessProbe:
failureThreshold: 10
httpGet:
path: /health
port: 3000
scheme: HTTP
initialDelaySeconds: 10
periodSeconds: 30
successThreshold: 1
timeoutSeconds: 3
4. Peale App deploy tegemist kontrollida Rancheris workload>pod>container ja vaadata Event
alamosast, kas probe töötamise eventid on näha. Samuti on võimalik kontrollida konteineri
enda logist, kas health päringud on logist näha (juhul kui rakenduse logisse on health
endpointi logimine arendaja poolt lisatud).
5. Täiendav info Kubernetes juhend
Ehitisregistri andmebaasid ja nende uuendamise juhend
V2.1 23.03.2020
Dokumendi eesmärk on kirjelda Ehitisregistri (EHR) ja e-ehituse infrastruktuuris olevad andmebaasid
ning nende uuendamise protsess, et tagada andmebaasides andmete kooskõla ning andmebaaside
vaheliste konfliktide vältimine.
EHR arhitektuur baseerub mikroteenuste kontseptsioonil vt. Ehitisregistri arhitektuur. Tänane EHR on
liikumas monoliitselt arhitektuurilt mikroteenuste arhitektuurile, kasutades järkjärgulisel
ümberkujundamisel baseeruvat metoodikat („Brownfield development“).
Esialgne EHR Oracle andmebaas - edaspidi EHR monoliit sisaldas kogu EHR andmestikku. Lisaks
monoliidile on kasutuses EHR „andmeaida“ Postgre andmebaas, kuhu kogutakse kõik EHR baasis
toimuvad sündmused ning EHR VRM Oracle andmebaas, kus hoitakse võrgurajatiste mooduliga
seotud andmeid. EHR monoliitbaasis hoiti 2019 aasta lõpuni lisaks eraldi skeemidena Hooneregistri ja
EHR 1 andmeid.
Vastavuses mikroteenuste kontseptsioonile võetakse EHR infrastruktuuris kasutusele uute
teenustega seotud andmebaasid ning seetõttu on oluline tagada uute ja olemasolevate
andmebaaside omavaheline kooskõla. Selle saavutamiseks rakendatakse uus roll EHR „Data
steward“, kelle vastutusel on EHR andmebaaside kooskõlas hoidmine.
EHR andmebaasi loogiline kirjeldamine ning edasiarendamine toimub Enterprise Architect tööriista
kasutades.
EHR andmebaasi analüüs ja arendamine
1. Analüüsi lähteandmeteks on SP-s paiknev EA fail EHR andmemudelid ja selles olevad
andmebaaside skeemid:
a. <Datamodel>Oracle – EHR Java rakenduse andmebaasi skeemi EHR andmetabelid,
vaated (Oracle andmebaas)
i. <Datamodel> YHR – hooneregistri andmebaasi skeem (Oracle andmebaas)
ii. <Datamodel>SHR – ehr1 rakenduse andmebaasi skeem (Oracle andmebaas)
iii. <Datamodel> YHR – hooneregistri andmebaasi skeem (Oracle andmebaas)
iv. <Datamodel>VRM – VRM e. võrgurajatiste andmebaasi skeem (Oracle
andmebaas)
v. <Datamodel> EHRGIS – EHR GIS rakenduse skeem (Oracle andmebaas),
rakendus pole enam kasutusel
vi. <Datamodel>DOGISCONTEXT – EHR kaardirakenduse (XGIS) skeem (Oracle
andmebaas)
b. Andmebaasi Andmeait (Postgre) skeemid:
i. DW - core data (tabelid)
ii. DM - datamardid andemekaevurile (materialiseeritud vaated)
iii. RVA - väljundvaated erinevatele rakendustele (tabelid, materialiseeritud
vaated)
iv. RVA_VIEW - vaated kasutajatele (andmekaevur, aruande koostaja)
v. KOV - statistika portaali andmed (tabelid, funktsioonid )
vi. PPA- politsei ja piirivalve (tabelid, funktsioonid)
vii. PSA - laadimisteks staging area (tabelid ja funktsioonid)
viii. SB - andmekaevuri sandbox (kasutaja poolt loodud abitabelid)
c. Andmebaasi Xtee (Postgre) skeem “xtee” x-tee teenuste andmetabelid ja
funktsioonid
d. Mikroteenuste andmebaas “ehrdb” (Postgre). Andmebaasis on iga mikroteenuse API
jaoks oma skeem.
i. Geo – ehitiste ja KÜ aadressid, ruumikujud
ii. Eehitus – dokumendid, ehitised, menetlused, failid
iii. Kasutaja – isikud, kasutajad, rollid, õigused
iv. Koodid - kooditabelid
2. Füüsiliselt andmebaasis olemas olevad tabelid/veerud/vaated jm. objektid peavad olema
tähistatud EA staatusega „Implemented“.
3. EHRi andmebaasides muudatuste tegemiseks koostab arendaja/analüütik esmalt muudatuse
EA mudeli ja kooskõlastab selle EHR "Data stewardiga". Kooskõlastuse palvele lisab ta lühida
põhjenduse ja – juhul kui see on konkreetsel juhul mõistlik – viite(d) arenduse JIRA
piletile/piletitele. "Mudeli koostamisel tuleb kasutada uutel või muudetavatel elementidel EA
staatust „Proposed“, et eristada plaanitavaid muudatusi juba kasutusel olevatest objektidest.
Mudeli kohta peab olema koostatud ERD joonis, millel on kujutatud kõiki tabeleid ja view-sid,
mis on seotud käesoleva arendusega.
4. EHR „Data steward“ tellib vajalike muudatuste sisseviimise ka teistesse EHR
andmebaasidesse nagu „andmeait“ jm. koostades selleks JIRA arenduspiletid ja suunates
need hooldajatele.
5. Peale kooskõlastuse saamist tuleb koostada andmebaasi muutmiseks SQL-d ja esitada need
vastavuses EHR koodi haldamise ja tarnimise juhendile
6. Peale andmebaasi uuendamist tuleb uuendada SP-s paiknev EA faili EHR andmemudelid ning
viia muudatused staatusesse „Implemented“.
7. EA mudelit võivad samaaegselt muuta mitmed isikud ja seetõttu peab viimasena muudatusi
teinud isik ühildama oma muudatused EA faili kõige viimasesse versiooni. Selleks, et
muudatusi oleks lihtsam ühildada tuleb enne muutmist EHR „data stewardiga“ kooskõlastada
muudatuste ulatus.
Andmetabelite ja atribuutide nimetamise reeglid
1. Tabelid ja atribuudid on eesti keeles v.a. : created_by, date_created, updated_by,
date_updated, deleted_by, date_deleted
2. Kõik tabelid ja atribuudid peavad olema kommenteeritud ning kommentaarid peavad andma
ülevaate tabeli ja atribuudi eesmärgist ning vajadusel ka kasutamise reeglitest
3. Tabelite nimedes tuleb kasutada prefiksit, mis tähistab objekti, mida tabel kirjeldab näiteks:
do – dokument, eh – ehitis, ad – aadress, ak – kasutaja, kl – klassifikaator.
4. Tabeli nimetamisel tuleb lähtuda tabeli eesmärgist ja üldjuhul peaks tabeli nimi olema:
objekt_alamobjekt_seos_seose_liik. Näiteks do_doku on dokumendi objekti tabel, do_ehitis
on dokumendil olevate ehitiste tabel, do_doku_ehitis_rel on dokumendi ja dokumendi
ehitiste omavaheliste seoste tabel.
5. Juhul, kui tabel on koopia (link) mõnest teisest andmebaasist siis lisatakse tabeli nimetuse
ette r_. Näiteks r_ad_aadressid on aadressi tabeli koopia geo andmebaasist ehk originaal
tabel asub geo skeemis, kus toimub selle kirjete create, update, delete ning JOIN tegemise
eesmärgil on tabeli lingitud mõne teise andmebaasiga ja seetõttu on nimes r_.
w
EHR andmebaasi hooldusprotsessis tehtavad muudatused
1. EHR andmebaasi pisimuudatused, mis tehakse hooldusprotsessi käigus vigade paranduse või
pisiarenduse eesmärgil nagu välja pikkuse muudatus, uus indeks vms. tuleb kooskõlastada
EHR „Data stewardiga“. Kooskõlastamiseks saadab hooldustöö tegija (arendaja) plaanitavate
muudatuste SQL skripti, viite JIRA veapiletile, mida lisatud skript parandab, JIRA
paigalduspiletile ja vajadusel põhjenduse ning saadab selle „Data stewardile“.
2. EHR „Data steward“ kooskõlastab muudatuse ning suunab pileti arendajale tagasi. Arendaja
esitab pileti vastavuses EHR koodi haldamise ja tarnimise juhendile.
3. „Data steward“ uuendab vastavalt SQL-le SP-s paiknev EA faili EHR andmemudelid ning
vajadusel loob JIRA arenduspiletid hooldajatele muudatusega seotud ülejäänud
andmebaaside kooskõlla viimiseks.
Andmetabelitest kirjete kustutamine
1. EHRi andmetabelitest kirjete füüsiline kustutamine on üldjuhul keelatud. Erandiks on ajutised
või tehnilised andmetabelid, mille kirjed ei ole EHRi tavakasutajatele näha ja ei või mõjutada
nende tööd.
2. Andmevigade parandamine toimub üldjuhul koos dokumendi (registri paranduskanne, AET)
loomisega, parandatava kirje kehtivuse peatamise ja uue kirje loomisega.
3. Teatud olukordades võib olla mõistlik kirjeid siiski kustutada – näiteks dokumendid, mida
kasutaja on alustanud, kuid ei ole kunagi esitanud ja mille puhul ei ole tõenäoline, et kasutaja
seda kunagi esitaks (mitme kuu jooksul ei ole infot uuendatud) või programmkoodi poolt
loodud sisutud topeltkirjed.
Sellisel juhul peab kirje kustutamise soovija vastava plaani „Data stewardiga“ kooskõlastama,
tuues välja põhjuse, miks andmeid kustutatakse, näidates ära võimalikud kustutatavate
andmete seosed ja nende haldamise viisi ning – kui otstarbekas ja kooskõlas isikuandmete ja
riigikaitseliste asutuste andmete käitlemise regulatsioonidega – saatma talle kustutatavad
andmed tabelina.
„Data stewardi“ ülesanne on ennekõike hinnata ega see tegevus ei too kaasa kasutajatele
komplikatsioone, ei riku potentsiaalselt seotud osapoolte (kasutajad, arendajad, vastutav
töötleja) õigusi, ei riku andmebaasi konsistentsust ega too kaasa tõrkeid EHRi töös ja määrata
tingimused, kas, kuidas ja millal vastava operatsiooni läbi viimine lubada.
Dokumendi muudatused
V2.1 23.03.2020 Taavi Jakobson Lisatud osa „Andmetabelitest kirjete kustutamine“
V2 06.11.2019 Ülo Puskar
BIM module technical architecture
Table of contents
Glossary .......................................................................................................................................... 2
1. Software terminology ........................................................................................................... 2
2. Business logic terminology ................................................................................................... 2
3. Technical terminology .......................................................................................................... 3
4. Other components referred to in this document ................................................................. 3
General architectural principles of how EHR, BIM module, and BIM.works are related and how
do they communicate with each other ............................................................................................ 3
BIM module as a microservice in EHR .......................................................................................... 4
5. List of technologies used for building BIM module .............................................................. 5
6. Parameters that will be passed on from EHR UI to BIM module frontend........................... 5
7. Document versions and processor’s comments .................................................................. 5
8. Processor’s comment counts ............................................................................................... 6
9. Events thrown and catched by BIM module (for communication with other components) 7
10. Swagger API endpoints provided by BIM module............................................................. 7
11. List of API endpoints used by BIM module ....................................................................... 7
Use cases / functionalities that require integration between EHR, BIM module, and BIM.works 8
12. Information flow about uploaded IFC models and connected buildings and metainfo ... 8
12.1. Request body example .............................................................................................. 8
12.2. After receiving information from Files 2.0, BIM module will do the following.... 10
13. Notifying user via EHR of completion of file uploads / checks run ................................. 11
13.1. EHR notification module is used for sending out two types of notifications ......... 12
13.2. When the checks have been completed, the following actions are taken by BIM
backend 12
13.3. Logic for detecting which user the notification should be sent to .......................... 12
14. Providing information about document’s status (BIM-related aspects)......................... 13
14.1. API description of the status endpoint .................................................................... 14
15. Provide building information (extracted from BIM model) to EHR ................................ 14
15.1. Sending extracted information to EHR ................................................................... 14
16. Commenting component................................................................................................ 16
16.1. User flow and technical description of how the two components (BIM module and
Commenting component) interact (processor’s view) .......................................................... 19
17. Providing the check results to EHR ................................................................................. 22
18. Recording that a procedure round has started .............................................................. 23
19. Details about RabbitMQ messages and handling of them by BIM module .................... 26
20. Button “Change files” re-directs to another tab ............................................................. 29
21. Managing checks (admin module) .................................................................................. 30
21.1. Admin module configurations are saved in the following tables in database......... 30
21.2. The following actions can be done in the admin module ....................................... 30
21.3. Security ................................................................................................................... 30
22. Providing BIM model export functionality for 3rd party software ................................. 32
Glossary
1. Software terminology
• BIM.works - Software provided by Future Insight. Main responsibilities are storing models,
running checks, and providing check results.
• BIM module - Software developed by Reach-U. It consists of a micro-frontend module for the
applicant and the processor (which will be integrated into EHR UI), a micro-frontend module for
the administrators, and a backend REST API.
o NB! Throughout this document, “BIM module” usually refers to the component that is
used by the applicants and processors. If it is necessary to refer to the component used
by the administrator, it is specifically referred to as “the BIM module admin
component”.
• BIM visualization component - A UI module built by BIM.works. This module is embedded in the
BIM module and used for visualizing the IFC models and the check results, etc.
2. Business logic terminology
• Application - an application (“taotlus”) for a new building permit
• Applicant - a user (“taotleja”) that wants to create a new application
• Processor - a person (“menetleja”) who will review the application
• Procedure (“menetlus”) - the process of reviewing the application. It consists of multiple
procedure rounds and ends when the application receives an approval.
• Procedure round (“menetlusring”) - one round of a procedure (processor reviews the
application, adds observations, and sends the application back to the applicant)
3. Technical terminology
• Document Nr - do_doku.dok_nr. Unique number of a document. This identificator already
exists when the user enters the BIM module for the first time. It does not change when a new
procedure round is started for that permit application.
• Document ID - do_doku.doku_id. Unique ID of a version of a document. This identificator is
allocated a value when the document is created, but it will be assigned a new value when a new
version of the same document is created (i.e. when a procedure round has been completed and
the user starts to create a new version for the new procedure round).
• Check ID - unique identifier of a check, which is an UUID (for example “123e4567-e89b-12d3-
a456-426614174000”).
4. Other components referred to in this document
• Document component - the EHR UI component which contains the BIM module, Files 2.0, and
commenting component
• Files 2.0 component - component for uploading IFC models and connecting them with EHR
buildings (see this chapter for details)
• Commenting component
General architectural principles of how EHR, BIM module, and
BIM.works are related and how do they communicate with each
other
• EHR front-end contains BIM module front-end and provides necessary data to it (see Section
“Parameters that will be passed on from EHR UI to BIM module frontend”)
• BIM module front-end communicates with BIM module back-end
• BIM module front-end communicates with the commenting component via events:
o See Events thrown and catched by BIM module (for communication with other
components)
• BIM module back-end communicates with EHR Swagger API:
o See List of API endpoints used by BIM module
• BIM module provides the following API endpoints via EHR Swagger API:
o See Swagger API endpoints provided by BIM module
• BIM module front-end does not communicate directly with BIM.works; instead, requests to
BIM.works are proxied via BIM module backend.
• There is a WebSocket communication between BIM module backend and BIM.works
The following diagram is focused on showing how the BIM.works and BIM module are integrated. It also
briefly shows what are the other entities (EHR UI, Files 2.0, Commenting component, etc.) and how they
are related to each other.
BIM entity diagram v8
BIM module as a microservice in EHR
The BIM module is implemented as a microservice in EHR. EHR UI provides the necessary information to
the BIM module micro-frontend. This includes the authentication information (KeyCloak token). BIM
module adds this token to each query made to the BIM module backend, which verifies the validity of
the token for each request. Also, user ID is obtained from KeyCloak via the token.
The BIM module component is meant to be included in a single tab; there is no need for switching
between pages in the component. Therefore, using the EHR router is not necessary.
In the main component (EHR UI) Redux is used. The BIM module does not need to communicate with
Redux itself.
BIM module will inherit the i18n component from EHR UI.
5. List of technologies used for building BIM module
BIM module backend:
• Java 11
• Spring Boot
• LiquiBase
• PostgreSQL
BIM module frontend:
• BIM component will be built as a React component and uploaded to NPM
6. Parameters that will be passed on from EHR UI to BIM module frontend
The list of parameters that will be passed on to BIM module by Document component:
• EHR UI provides information about the user:
o KeyCloak access token - string
o User role - string
• EHR UI provides information about the application (“taotlus”)
o Document Nr
• EHR UI provides information about document’s latest versions and counts of processor’s
comments in those versions (see details in Chapter Document versions and processor’s
comments below)
• Type of the document (as text, in Estonian): e.g. “Ehitusloa taotlus”
For the commenting functionality, additional events-based communication between EHR UI and BIM
module is required. See the details in the section “Commenting component”.
BIM module admin component (which is a separate UI component) takes the following parameters as
input:
• User information
o KeyCloak access token
If some of the critical parameters are missing (e.g., token, role, document Nr, document ID), then the
BIM module does not open (an error is shown instead).
7. Document versions and processor’s comments
As mentioned above, EHR UI provides information about the document's latest versions and processor’s
comments in those versions. Information should be sent about the 2 last versions.
Parameter “processorComments” contains counts of processor’s comments (how many processor’s
comments each check/check group has in that procedure round). See Chapter Processor’s comment
counts for detailed explanations and an example. This parameter is only given if the procedure round
has started.
Example case (applicant is preparing first version of document for the procedure)
{
‘12345000’: {
‘procedureRoundNr’: null,
}
}
Example case (procedure round 1 has been rejected, procedure round 2 is being reviewed by the
processor)
{
‘12345000’: {
‘procedureRoundNr’: 1,
‘processorComments’: {
...
}
},
‘12345001’: {
‘procedureRoundNr’: 2,
‘processorComments’: {
...
}
}
}
Example case (procedure rounds 1 and 2 have been rejected, new version is being prepared by the
applicant)
{
‘12345001’: {
‘procedureRoundNr’: 2,
‘processorComments’: {
...
}
},
‘12345002’: {
‘procedureRoundNr’: null,
}
}
8. Processor’s comment counts
This chapter is relevant for: MKM, Tieto, BIM module
As mentioned in the previous chapters, one of the input parameters is counts of processor’s comments
for specific checks.
This object must consist of key-value pairs, where keys are checkIDs (UUIDs) and values are comment
counts:
{
“123e4567-e89b-12d3-a456-426614174000”: 5,
“323e4557-a8ab-23a3-4a36-424314124000”: 2,
...
}
If some checkIDs are omitted, then these are assumed to be 0.
When these counts are calculated, it must be taken into account that depending on the processor's
exact role, only some of the comments may be visible for that processor.
9. Events thrown and catched by BIM module (for communication with
other components)
For implementing commenting functionality, the BIM module throws the following event:
• openCommentModal
The commenting functionality is described in more details in the section “Commenting component”.
For implementing the functionality “send extracted BIM model data to EHR”, BIM module throws the
following event:
• extractedDataToBeSent
When a user clicks on “Change files” or “Add files” in the BIM module, an event is thrown:
• requestForRedirectToFileUploadTab
10.Swagger API endpoints provided by BIM module
List of Swagger API endpoints provided by BIM module for other components
• Update models and buildings
• Providing document’s status (BIM-related aspects)
• Provide extracted building info from models
• Get check results
• Record that a procedure round has started
11.List of API endpoints used by BIM module
List of EHR Swagger API endpoints used by BIM module:
• KeyCloak module
• Notification module
Additionally, the BIM module extensively uses BIM.works JavaScript and Java APIs.
Use cases / functionalities that require integration between EHR, BIM
module, and BIM.works
12.Information flow about uploaded IFC models and connected buildings
and metainfo
When the BIM-based permit application has been activated, the wrapper tab containing the BIM module
becomes visible (this happens outside of the control of the BIM module).
If the user enters the BIM module before any models have been uploaded to the Files 2.0, the user is
shown a text informing that he/she should first go to the Files 2.0 tab and upload IFC files there.
Every time that an IFC file is uploaded in the Files 2.0 tab or it is connected with a building, an event is
thrown about it in the Files 2.0 tab and catched by the Document module. Document module will then
make a request against the EHR Swagger endpoint provided by BIM module:
• POST <domain>/api/bim_module/v1/application/round
o Input parameter: documentNr
o Input parameter: documentId
o Request body - JSON array of building objects
Important: all IFC buildings that are connected to the given application are re-sent with each query.
12.1. Request body example
The rows which are relevant for the BIM module are in bold.
The rows which are ignored by the BIM module are in italic.
[
{
"createdAt": "2021-06-18 13:37:08Z",
"id": 167727712,
"failiNimetus": "1807_EP_AR_v04 - Shifted.ifc",
"projOsa": "AR",
"failiVersioon": 1,
"ehitiseSeosKoigiga": true,
"ehitiseSeosEhrKood": "120772119",
"projStaadium": "EP",
"createdBy":"1234"
}
]
[
{
"id":"167726553",
"failiNimetus":"MA_IKT29_ET_Revit.ifc",
"projTunnus":"TST",
"projStaadium":"EP",
"projOsa":"AR",
"grupiTunnus":"7",
"grupp":"MUUD_JOONISED",
"gruppMarksona":"solm",
"jnrGrupis":"9",
"nimeSelgitus":"Üks ifc fail on.",
"failiVersioon":"1",
"failiTunnus":null,
"createdAt":"2021-04-28 16:00:12+Z", //viimane muutmine (ISO-8601)
"failiStaatus":"KORRAS",
"ehitiseSeosKoigiga":false,
"ehitiseSeosEhrKood":"120772119",
"createdBy":"1234", //faili lisaja ID
"errorMessages":[]
},
{
... //next building ...
"ehitiseSeosKoigiga":true,
"ehitiseSeosEhrKood":null,
...
}
]
Discussion about specifics of data flow (Files 2.0 → Document component → BIM module)
Discussion took place on 4.06.2021 between Callista, MKM, and Reach-U. Multiple different solutions
were discussed for how the information about IFC files is sent to the BIM module via the Document
component.
Important questions were:
• What files are sent to the BIM module (only IFC files or all files)?
o Answer: only IFC files
• Are files with status “temporary” (“AJUTINE”) sent to the BIM module?
o Answer: no. Only files with status “KORRAS” are sent to the BIM module.
• Are files with upload errors sent to the BIM module?
o Answer: no
• Are IFC files sent to the BIM module right after they have been uploaded?
o Answer: Files are sent to BIM module only after they have been assigned a discipline
and an EHR building (or marked “connected to all EHR buildings”)
• Is an update query made to the BIM module after every change in Files 2.0 tab?
o Answer: Update query is made to the BIM module by Document component only when
a relevant change has occurred regarding the IFC files
• How can the Document component know whether a IFC-related change has occurred?
o Answer: The Document component should store the timestamp of the latest query to
the BIM module files endpoint; when an event is thrown in Files 2.0 tab regarding the
file changes, Document component can compare the timestamps of changed files to
detect if there are any IFC files that have changed after the last query to the BIM
module files endpoint.
• After an IFC-related change, are only the changed files sent to the BIM module or the whole list
of IFC files for that application?
o Answer: The full list of IFC files is sent to the BIM module whenever an IFC-related
change is detected. If a file is missing from the list, it is assumed to be deleted from Files
2.0 tab and it is removed from the application’s file list in the BIM module
• What if multiple users manipulate files in the same application at the same time (for example,
both upload 2 files)?
o Answer: In the (very) rare event that the uploads are practically simultaneous and the
order of the queries gets mixed up, it may happen that there is unnecessary deletion
and re-insertion of the same file to the BIM module and BIM.works. However, since the
full list of IFC files is sent with every query, the eventual correctness of the file list in the
BIM module is guaranteed.
• Will only the latest version of the files be sent to the BIM module?
o Answer: Yes, but internally BIM module will keep track of older files also (for example
for showing file lists from previous procedure rounds in UI)
12.2. After receiving information from Files 2.0, BIM module will do the following
1. Diff between the existing state and newly received state
2. For new models that were not uploaded before:
1. Record information about the new model to the BIM module database
2. Initiate the file upload to BIM.works from S3
3. Update the BIM module UI to show that the file is being uploaded to BIM.works
3. For models that were uploaded before but are no longer present:
1. Mark the file to be “deleted” in BIM module database (soft delete from database)
2. Update the BIM module UI (remove row from file table)
4. For models for which a new version has been uploaded:
1. Record information about the new version to BIM module database
2. Overwrite data for that file in BIM module database
3. Initiate the file upload to BIM.works from S3
4. Update the BIM module UI to show that the file is being uploaded to BIM.works
5. For models which have changed (related building or metainfo has changed)
1. Record information about the changes in BIM module database
2. Update the BIM module UI to show correct information in the file table
3. At the time there is no need to inform BIM.works, since disciplines and EHR codes are
only sent to BIM.works when a check run is started.
Remark: It is possible that the user does not add IFC files to some buildings on the application form. This
is allowed behaviour in EHR. In that case the BIM module does not even know that these buildings are on
the application form.
BIM-module will inform the user before running the checks: “Oled käivitamas BIM kontrolle. Kontolle on
võimalik katkestada, et faile lisada/muuta. Failide muutmisel kas pärast katkestamist või kontrollide
teostamist tühistatakse senised tulemused ja kontrollid on võimalik käivitada uuesti. Kontrollide
lõppemise kohta saadame teile teavituse.”.
The diagram below shows the interactions and flow between Files 2.0 tab, Document component, BIM
module, and BIM.works.
Diagram “Technical_flow_diagram_Model_upload_check v7”
13.Notifying user via EHR of completion of file uploads / checks run
13.1. EHR notification module is used for sending out two types of notifications
• All pending uploads to BIM.works have been completed
• Check run has been completed
13.2. When the checks have been completed, the following actions are taken by
BIM backend
• If the user is still in EHR in the BIM module, then BIM frontend will be updated. The list of check
results will be shown to the user (and other necessary UI updates will be done).
• BIM module will make a request to the EHR notification system to create a new notification.
o When the user enters EHR again, he/she will be shown +1 notification in the EHR UI
header (this is done by general EHR UI components, not BIM module)
▪ User can go to the notifications module and read the notification
o If the user has configured receiving notifications for that type of e-mail, he/she will also
receive an e-mail notification.
← The same flow applies for the case when pending uploads have been completed.
13.3. Logic for detecting which user the notification should be sent to
• Uploads completed - user(s) who initiated file uploads to EHR
o NB! If the user IDs are missing in the query to the BIM module UI, then no notifications
are sent
• Check run has been completed - user who clicked “run checks” in BIM module frontend
Link to EHR notification system Swagger API
• https://swaggerui.ehr.ee/ehr_teavituste_saatmise_teenus
BIM module backend will use the following endpoint to create a notification to the user:
• POST /notification (create notification)
o type: BIMI_001 or BIMI_002
o usersTo: described above
o parameters: see below
The bodies and parameters of the notifications are described here:
https://365mkm.sharepoint.com/:w:/r/sites/MKM/EHR/_layouts/15/Doc.aspx?sourcedoc=%7BAAC8E85
C-BD4C-44A2-9450-C260254A0E2A%7D&file=E-ehituse_teavituste_mallid.docx&wdLOR=cCA662E86-
741D-4931-AEAE-3735CDA936FB&action=default&mobileredirect=true
• BIMI_001 (“IFC failid on BIM moodulis vaatamiseks valmis”)
• BIMI_002 (“BIM kontrollide tulemused on valmis vaatamiseks”)
There are two parameters for both queries:
• documentNr
• documentType
Both of these parameters are given via props to BIM module UI, where they are passed to BIM module
backend.
If the documentType parameter is not present (i.e. the uploads have already been completed, but the
user has never entered BIM module frontend), then a generic string like “Dokument” is used instead of a
specific document type (e.g. “Ehitusloa taotlus”).
User manual:
https://365mkm.sharepoint.com/sites/MKM/EHR/_layouts/15/doc.aspx?sourcedoc={98be99aa-9d74-
41b8-9f25-e6bb698e7635}&action=edit
14.Providing information about document’s status (BIM-related aspects)
Since multiple functionalities in EHR depend on the document’s version’s status in BIM-related aspects,
it is necessary for the BIM module to provide this information to other components.
BIM module reports the status from a predefined list of string constants. The following statuses are
possible in BIM module:
• CHECKS_NOT_STARTED
• CHECKS_IN_PROGRESS
• CHECKS_FAILED
• CHECKS_CANCELLED
• CHECK_RESULTS_CANCELLED
• CHECKS_COMPLETED_NOT_READY_FOR_PROCEDURE
• CHECKS_COMPLETED_READY_FOR_PROCEDURE
• IN_PROCEDURE_ROUND
• APPLICATION_REJECTED
• APPLICATION_ACCEPTED
The status CHECKS_COMPLETED_READY_FOR_PROCEDURE is returned when the BIM module
determines that the procedure round can be started. This requires that the following conditions have
been met:
1. Checks have been completed
2. Extracted data (extracted from the BIM model) has been sent to the EHR application form
3. User has given given at least 1 comment/group comment to each problematic check
These 3 yes/no values are also returned by the status endpoint (see API description below). These values
can be used in the EHR UI to inform the user of the steps that still need to be taken before the
procedure can be started.
The following diagram clarifies the user flow in the BIM module and how the document’s version’s
statuses change via user actions.
Diagram “BIM module statuses”, v3
14.1. API description of the status endpoint
• GET <domain>/api/bim_module/v1/bimModuleStatus
• Input parameters:
o documentId
• Response body:
o status: <status constant>
o procedure_prerequisites:
▪ checks_completed: true/false
▪ extracted_data_sent_to_form: true/false
▪ errors_have_been_commented: true/false
15.Provide building information (extracted from BIM model) to EHR
The information that is extracted from the BIM model (in BIM.works) will be sent to EHR after the user
initiates this process in the EHR UI in the Document view.
15.1. Sending extracted information to EHR
After the checks have been completed, data extraction process is started asynchronously in BIM.works.
As soon as BIM.works has informed the BIM module that the extracted data is ready, the button “Send
BIM model’s data to the document” (“Kannan andmed vormile”) becomes usable in the BIM module UI.
After the button has been pressed, its text will change to “Re-send BIM model’s data to the document”
(Kannan andmed uuesti vormile). This will allow the user to understand whether the data has already
been sent or not.
It is a requirement from MKM that this button must be clicked at least once after the checks have been
completed (otherwise it is not possible to start the procedure for the BIM-based application - see
explanations here).
When this button is clicked, an event is thrown by the BIM module (“extractedDataToBeSent”). After
this event is catched by Document component, Document component will launch a request to a
Swagger API provided by BIM module:
• GET <domain>/api/bim_module/v1/modelExtractedParameters
o Input parameter: documentNr
o Input parameter: documentId (must be the documentId of the current application
round)
BIM module returns the information that was extracted from the models during the latest check round.
The returned JSON object contains a separate sub-object for each building (which are identified with
corresponding ehrCodes).
NB! It is not possible to query for information that was extracted in previous check rounds (including
checks done during the previous processing round). If the documentId is not from the latest application
round, an error is thrown.
Proposal example for the returned object:
https://www.notion.so/Export-38d06b1524cc431b96452a69db162d65
It is up to the Document component to decide how the data is handled in the document form.
Diagram “sending information to EHR, idea 3a”.
Advantages of the proposed solution
• It maximizes encapsulation: BIM module is only responsible for providing the extracted data
• There is no need to create another channel for communication - EHR UI and BIM module already
communicate via React props and events.
• MKM can easily change business requirements about what happens with the extracted data (whether it is
always over-written; whether user is prompted; etc.) without having to change anything in BIM module
• It allows future developments / and changes to the logic of handling the extracted data to be done in the
most cost-efficient way - the BIM module does not need to be changed if the structure of the EHR forms
or EHR database or AET service changes - only the EHR UI’s handling of the data needs to be changed (in
other words, change will be localized to a single location).
Initially, there was a concern that responsibility of handling the data should not be given to the EHR front-end
components because the data might be lost in that case (if for some reason the EHR front-end is not able to enter
the data to EHR back-end; or if the user fails to click “Save” after the data has been transferred to the form; etc.).
However, the end-user has the possibility to re-enter the EHR portal and re-click “Send..” - therefore this is not an
issue.
16.Commenting component
In EHR, the following terms are used:
• Comment (“kommentaar”)
• Observation (“märkus”)
Observations (märkused) are more important than comments. Observations have official status.
Comments can be added by the applicant, but they do not have official status.
From the technical viewpoint, in this document, it is not necessary to distinguish between comments
and observations. Therefore, the word “comment” is used, in this document, for both EHR comments
and EHR observations.
More importantly, comments can be categorized further into:
1. Those that are added by the applicant (before starting the procedure round) - we call them
"applicant’s comments”
2. Those that are added during the procedure round in BIM module - we call them “processor’s
comments”
1. NB! There are actually multiple other roles involved in the procedure (approver, opinion
giver, internal opinion giver). To keep terms simple, we refer to their comments also
simply as “processor’s comments”.
3. Those that are added during the procedure round outside of BIM module (and therefore are not
related to BIM module) - we call them “general comments”
Applicant sees/adds only his/her own comments. The applicant’s comments are stored in the BIM
module database.
Diagram. Technical diagram of the user interface flow (when adding applicant’s comments).
After initiating the procedure, processors and other related roles can see the applicant's comments and
add their own. These processor’s comments are created and managed in the Commenting component.
These processor’s comments are stored in EHR.
Diagram. Technical diagram of the user interface flow for the processor. The flow involves both the BIM module
and Commenting component.
After the procedure round ends, the applicant can see both his/her comments and the comments that
the processor decided to send back to the applicant.
Diagram. User interface flow for the applicant (after the procedure round has ended).
16.1. User flow and technical description of how the two components (BIM
module and Commenting component) interact (processor’s view)
When the processor views the application in BIM model tab, he/she is presented with the following
view:
Mockup: Example of a processor’s view (commenting component is not open)
All of the UI elements that are visible here on this mockup originate from the BIM module. The red
circles near the checks show the number of existing comments for that check. These numbers are
calculated as as sum of:
A. The number of applicant’s comments for that check (0 or 1) - this information originates from
BIM module (is kept in BIM module database)
B. The number of processor’s comments for that check (0..n) - this information is given to BIM
module as a React prop when initiating the BIM module
When the user clicks on the comment indicator , an event “openCommentModal” is thrown by the
BIM module with the following parameters:
• check_id (UUID): Check ID / check group ID
• documentId (numeric): Refers to the application’s version that the checks are related to
• applicant_comment (object): Applicant's comment (if exists)
• commenting_modal_loc_x (int), commenting_modal_loc_y (int): modal window location (x, y)
This event is catched by the parent Document component, which initializes the Commenting component
in the coordinates given in the event (coordinates refer to the top-left corner of the modal window).
The commenting component visualizes both the applicant’s comment (if it exists) and the processor’s
comments.
Mockup of the commenting component showing both applicant’s and processor’s comments.
It is up to the Commenting component to determine which of the processor’s comments should be
visible (according to the exact role of the given processor). Also, it is up to the Commenting component
to determine what actions are applicable to which comment.
The detailed functionalities of the commenting component need to be described during the analysis (by
Tieto). As far as Reach-U understands, the commenting component covers the following functionalities:
• It allows for comments to be added (if the current processor’s role has sufficient rights)
• It allows for comments to be modified (if the current processor’s role has sufficient rights)
• It allows for comments to be deleted (if the current processor’s role has sufficient rights)
• It allows actions related to internal discussion circles (if this requirement is applicable in that
point of time and the current processor has sufficient rights)
Each of those actions can change the total number of processor’s comments of a check. In order to
update the BIM module UI whenever that happens, Commenting component updates the “processor’s
comments” object in the parent component (Document component), which then updates “processor’s
comments” property in BIM module (this should be done in such a way that the BIM module component
is not fully re-rendered, especially the 3D view)
Background information about the reasons why this solutions was chosen (decoupling commenting logic
from BIM module)
There are multiple roles involved in the procedure; additionally, there are institutional internal
commenting discussions (“asutuse sisering”) that take place in EHR. In order to make the BIM module as
loosely coupled as possible from the EHR, BIM module does not need to know anything about these
internal commenting discussions or the related roles (for BIM module, there are two roles only:
applicant and processor). This helps to reduce code duplication and makes further developments for
comment logic easier, since development of BIM module is not required (in most cases) when
commenting logic is further developed.
BIM module only needs to know:
• The list of BIM comments (and what checks or check groups they relate to)
• Whether the current user can see processor’s comments (or if finer control is necessary, which
comments can he/she see)
17.Providing the check results to EHR
After BIM.works has completed check running, information about the check results is sent from
BIM.works to the BIM module. This information is primarily necessary for the BIM module for showing
the list of the checks and allowing for integration of the checks with the 3D viewer.
However, the check results are also relevant for EHR, since processor’s comments, which are shown in
EHR along with general comments, will also be connected with check results. Furthermore, each check-
related row in the EHR comments table will contain information about that check.
In order to make the list of check results available to EHR, BIM module will provide the following API
endpoint:
• GET <domain>/api/bim_module/v1/check
• Input parameters:
o Document ID
o Check ID (UUID)
• Response object is an object containing the following information:
o ehrCode - EHR code of the related building (that this check is connected to)
o name - this field is filled for all 3 levels
o description - refers to description (this field is only filled for check level, otherwise NULL)
o parentUuid - UUID of the parent object, can be used to ask parent object’s info
o applicant’s comment (if it exists) - string
o treeLevel - legislation, applied_check, check_result
o These fields are only filled in at element level, otherwise NULL:
▪ result (“ERROR” / “WARNING” / “SUCCESS” / “INFO”)
▪ actualValue (e.g. „6m“)
▪ requiredValue (e.g. „8m“) - this can be NULL for INFO checks
▪ operator (e.g. “>”) - this can be NULL for INFO checks
▪ isKeyword (true/false) - this is set to “true” for INFO fields that use keywords for
translation. In these cases, “actualValue” parameter fill be empty and should
not be used.
▪ keywordValue - this is set only if “isKeyword” is true. In this case, this
keywordValue should be translated via i18n and used instead of actualValue.
18.Recording that a procedure round has started
Remark: Before a procedure round can be started (from the perspective of the BIM module), specific
conditions must be met. Document component (the component which contains the BIM module) can
query for the document status from BIM module via the endpoint described in Chapter “Providing
information about document’s status (BIM-related aspects)”.
General background about EHR RabbitMQ solution:
https://365mkm.sharepoint.com/:w:/r/sites/MKM/EHR/_layouts/15/Doc.aspx?sourcedoc=%7B1C43E24
9-9B35-431A-9FD5-0AAA33FB59AF%7D&file=EHR-RabbitMQ-
sync2.docx&action=default&mobileredirect=true&DefaultItemOpen=1&CID=D7D785C2-E5E4-4E7B-
8420-4C0790BE239E&wdLOR=cFDDE2D1F-93A7-4C83-89BB-B1678FAF10E0
The general architecture is that an event will be triggered whenever a specific table changes in the
database. Trigger will be created by MKM.
Table that should be monitored:
• do_doku_ehitis_rel
When the procedure starts, the field “seisund” is updated. This change is used to send the message.
For the BIM module
• only applications where “BIM_menetlus”:TRUE are relevant (all other are discarded)
• "Doku_id" is relevant and refers to the document’s ID
• "dok_nr" IS relevant and must be used as a unique identifier throughout the application lifecycle
• “seisund” must be monitored and its values used for making changes in the BIM module
behaviour accordingly. For example, when BIM module receives a message with “seisund =
DO_DOKUSEIS_MENETLUSES“, the BIM module will record that the procedure has started and
will disallow the user from changing anything in the BIM module until the procedure has
completed.
When a new procedure round is started, the table “do_doku” will be changed and a RabbitMQ event
will be sent (as JSON). Example of the message:
{
"Doku_id":82465022, //documentId
"Do_ehitis_id":9266188,
"ehit_men_seisund":"REGISTRISSE_KANTUD",
"Ehitusteg_liik":null,
"Doku_audit_id":45707587,
"Doty_id":11529,
"seisund":"DO_DOKUSEIS_MENETLUSES",
"Men_kohustus":null,
"dok_nr":"2111529/100912277", //document nr
"Ehr_kood":"120648641”,
“BIM_menetlus”:TRUE
}
Possible “seisund” values:
DO_DOKUSEIS_KOOSTAMISEL
DO_DOKUSEIS_ESITATUD
DO_DOKUSEIS_MENETLUSES
DO_DOKUSEIS_KEHTETU
DO_DOKUSEIS_MUUTMISEL
DO_DOKUSEIS_TAIENDAMISEL
DO_DOKUSEIS_REG_KANTUD
DO_DOKUSEIS_LOOBUTUD
Changes of “seisund” values throughout document lifecycle
Explanations:
Juhul, kui menetluses on ühe dokumendiga rohkem, kui 1 ehitis siis saab välja “ehitis_men_seisund”
alusel tuvastada, et millised ehitised on menetletud ja millised on veel menetluses.
Seisundid on klassifikaatorist: kl_klassifik_elem.kl_kood = DO_DOKUSEIS_EH, mis on tuletatud
klassifikaatorist: DO_DOKUSEIS nii, et igale DO_DOKUSEIS väärtusele vastab DO_DOKUSEIS_EH.
Ehitise menetluse seisundit tuleb muuta ehitise menetluses: NULL -> MENETLUSES ->
REGISTRISSE_KANTUD või VANA_VERSIOON, kui ehitise dokument võetakse menetlusse või kasutaja
allkirjastab ehitise loa, energiamärgise või kantakse registrisse paranduse kanne. Välja staatus on
KEELDUTUD, kui väljastati keeldumine teatisekohustusliku ehitise osas. Vanas baasis oli siis
DO_DOKU_MUUDATUSED_LUBATUD = F. Seda välja kasutatakse aktualiseerimisel ehk
REGISTRISSE_KANTUD staatus käivitab aktualiseerimise protsessi.
19.Details about RabbitMQ messages and handling of them by BIM module
As mentioned in chapters 3 and 7, there are two types of statuses:
• DO_DOKU_SEISUND (state of the document version in MKM database)
• BIM status (status of the document version in BIM module)
These two are not interchangeable; DO_DOKU_SEISUND is sometimes more detailed (for example,
DO_DOKUSEIS_TAIENDAMISEL and DO_DOKUSEIS_KOOSTAMISEL are different statuses in MKM,
but are treated in the same way by the BIM module). On the other hand, BIM statuses are more detailed
than DO_DOKU_SEISUND in aspects that are relevant to BIM module (for example, have the checks
been run?).
Because of this, both BIM status and DO_DOKU_SEISUND are stored in the BIM module database for
each document version (i.e., application round). DO_DOKU_SEISUND is directly used by the BIM module
to show the correct label in the UI for switching between versions.
As a reminder, these are the possible statuses in BIM module:
1. CHECKS_NOT_STARTED
2. CHECKS_IN_PROGRESS
3. CHECKS_FAILED
4. CHECKS_CANCELLED
5. CHECK_RESULTS_CANCELLED
6. CHECKS_COMPLETED_NOT_READY_FOR_PROCEDURE
7. CHECKS_COMPLETED_READY_FOR_PROCEDURE
8. IN_PROCEDURE_ROUND
9. APPLICATION_REJECTED
10. APPLICATION_ACCEPTED
In the following, we will call the statuses 1 … 7 pre-procedure statuses.
Now we will describe behaviour of how the BIM module reacts to RabbitMQ messages containing
specific DO_DOKU_SEISUND values.
Remark. If the existing DO_DOKU_SEISUND in the BIM module matches with the DO_DOKU_SEISUND in
the RabbitMQ message, no action is taken (this situation can occur if some field has changed in the MKM
database but the DO_DOKU_SEISUND field has not changed).
Another remark. A separate message is sent for each building in that document version on every change.
However, DO_DOKU_SEISUND will be the same for each of those buildings.
Important remark for clarity. When reading the below description, keep in mind that RabbitMQ
messages are sent for each document version separately. For example, if one procedure round is
rejected by the processor, a new document version is created and two messages (or more, if there are
more buildings than 1) are sent to the BIM module: one changing the old document version to be
DO_DOKUSEIS_KEHTETU and another message creating a new document version in the BIM module
with DO_DOKUSEIS_TAIENDAMISEL.
We will start with how the BIM module reacts to RabbitMQ messages with the state
“DO_DOKUSEIS_KOOSTAMISEL”.
DO_DOKUSEIS_KOOSTAMISEL
Situation: a RabbitMQ message with the state DG_DOKUSEIS_KOOSTAMISEL is received.
Variant 1: this is the first time that BIM module has seen this document (no application with that
document nr exists in the BIM module)
Outcome: A new application and application round are created in the BIM module with the BIM status
CHECKS_NOT_STARTED (initial status). DO_DOKU state is updated.
Variant 2: BIM module receives information about a document that BIM module already has seen
before (an application round with that document nr and document id already exists in the BIM module)
Assumptions: the BIM module status is one of the pre-procedure statuses and the DO_DOKU state is
already DG_DOKUSEIS_KOOSTAMISEL
Outcome: No action is taken.
Possible exception: if the assumption is not met, a corresponding error is logged (mismatch detected
between DO_DOKU state and the BIM module status).
Variant 3 (error): An application with that document nr exists in the BIM module, but a corresponding
application round with that document id does not exist.
Outcome: No action is taken, and a corresponding error is logged (mismatch detected between
DO_DOKU state and the BIM module status).
Explanation (why this is an error): State DG_DOKUSEIS_KOOSTAMISEL can only occur in the first version
of the document; any sub-sequent versions of the same document should have the state
“DO_DOKUSEIS_TAIENDAMISEL” when the user is modifying the application.
DO_DOKUSEIS_ESITATUD, DO_DOKUSEIS_MENETLUSES
Situation: a RabbitMQ message is received with either of these two states: DO_DOKUSEIS_ESITATUD or
DO_DOKUSEIS_MENETLUSES.
Assumptions: Status in the BIM module is one of the following:
• CHECKS_COMPLETED_READY_FOR_PROCEDURE
• IN_PROCEDURE_ROUND
Outcome: the BIM module status is set to IN_PROCEDURE_ROUND and the DO_DOKU state is updated
correspondingly.
Possible exceptions: if the assumption is not met, no action is taken and a corresponding error is logged
(mismatch detected between DO_DOKU state and the BIM module status).
Remark: In order to avoid problematic situations, EHR must query the BIM module to detect whether
the BIM module is ready for procedure (see Chapter Providing information about document’s status
(BIM-related aspects)).
DO_DOKUSEIS_KEHTETU
Situation: a RabbitMQ message is received with the state DO_DOKUSEIS_KEHTETU
Assumptions: Status in the BIM module is one of the following:
• IN_PROCEDURE_ROUND
• APPLICATION_REJECTED
Outcome: the BIM module status is set to APPLICATION_REJECTED
Possible exceptions: if the assumption is not met, no action is taken and a corresponding error is logged
(mismatch detected between DO_DOKU state and the BIM module status).
DO_DOKUSEIS_TAIENDAMISEL, DO_DOKUSEIS_MUUTMISEL
Situation: a RabbitMQ message is received with the state DO_DOKUSEIS_TAIENDAMISEL or
DO_DOKUSEIS_MUUTMISEL
Variant 1: the BIM module receives information about a new document version (an application with
that document nr exists in the BIM module, but an application round with that document id does not)
Outcome: a new application round is created by copying the buildings and check results and check
comments from the previous application round. The BIM module status will become
CHECKS_COMPLETED_READY_FOR_PROCEDURE. The state DO_DOKUSEIS_TAIENDAMISEL is set (even if
the message contained the state DO_DOKUSEIS_MUUTMISEL).
Explanation: in EHR, DO_DOKUSEIS_MUUTMISEL is an intermediate state that will soon be followed by
DO_DOKUSEIS_TAIENDAMISEL. Unfortunately, due to the current architecture of EHR, a message is not
sent to the BIM module on the transition of DO_DOKUSEIS_MUUTMISEL to
DO_DOKUSEIS_TAIENDAMISEL. This means that we will have to react to the message of
DO_DOKUSEIS_MUUTMISEL as if it already was the message containing the state
DO_DOKUSEIS_TAIENDAMISEL.
Variant 2: the BIM module receives information about a document version that BIM module already has
seen before (an application round with that document nr and document id already exists in the BIM
module)
Assumptions: the BIM module status is one of the pre-procedure statuses and the DO_DOKU state is
already DO_DOKUSEIS_TAIENDAMISEL
Outcome: No action is taken.
Possible exceptions: if the assumption is not met, a corresponding error is logged (mismatch detected
between DO_DOKU state and the BIM module status).
Variant 3 (error): No application with that document nr exists in the BIM module
Outcome: No action is taken, and a corresponding error is logged (mismatch detected between
DO_DOKU state and the BIM module status).
Explanation (why this is an error): State DO_DOKUSEIS_TAIENDAMISEL can only occur after the first
version of the document; and therefore, a document with that document nr should already exist in the
BIM module.
DO_DOKUSEIS_REG_KANTUD
Situation: a RabbitMQ message is received with the state DO_DOKUSEIS_REG_KANTUD
Assumptions: The BIM module status is NOT one of the pre-procedure statuses.
Outcome (in the BIM module database): the BIM module status is set to APPLICATION_ACCEPTED. The
DO_DOKU state is set to DO_DOKUSEIS_REG_KANTUD.
Changes in the BIM module UI: the BIM module state will become fixed. The applicant can still enter the
BIM module and see his/her check results, his/her comments and the comments added during the
procedure but cannot change anything. The 3D view will still be viewable.
Possible exceptions: if the assumption is not met, no action is taken, and a corresponding error is
logged (mismatch detected between DO_DOKU state and the BIM module status).
Question to MKM:
• How long should the 3D view remain viewable after the document has been approved?
Answer:
• Indefinitely (for both the applicant and the processor)
After the approval has been granted, information about this document can be incorporated into the 3D
twin.
DO_DOKUSEIS_LOOBUTUD
Situation: a RabbitMQ message is received with the state DO_DOKUSEIS_LOOBUTUD
Outcome: the BIM module status is set to APPLICATION_REJECTED. New version is not created.
Explanation: By setting the BIM module status to APPLICATION_REJECTED and not creating a new
version, a “dead end” situation is created in the BIM module. No further changes can be made in the
BIM module.
20.Button “Change files” re-directs to another tab
When a user clicks on “Change files” or “Add files” in the BIM module, a modal window opens. User can
confirm whether he/she wants to change the active tab. If the user clicks “yes”, an event is thrown
“requestForRedirectToFileUploadTab”.
Document component then catches this event and re-directs the user to Files 2.0 tab.
21.Managing checks (admin module)
In this chapter, we describe the functionalities of the admin module. The UI is described in Figma.
The full list of checks is defined in BIM.works.
The BIM module contains a copy of that list in the BIM module database.
21.1. Admin module configurations are saved in the following tables in database
• bim_module.check_conf
• bim_module.legislation_conf
21.2. The following actions can be done in the admin module
• Create legislation group
• Edit legislation group
o Edit name
o Activate/deactivate legislation groups
• See list of checks
• Edit check metadata
o Change status
▪ Kehtiv
▪ Kehtetu
▪ Täpsustamisel
▪ Seadistamata
o Edit name
o Edit description
o Edit law name
o Assign to legislation group
o Add link to law (URL)
21.3. Security
When admin module is opened, KeyCloak token is checked to verify that:
• businessType=”MKM”
This is to verify that only MKM employees can change the check configuration.
Automatic detection of added checks
If new checks are added to BIM.works, then this fact is detected by the BIM module when the admin
view is opened. This is done by a specific query to BIM.works.
If it is detected that there are indeed new checks, then these are shown in the table as “not configured”
(in visually distinct style). They can then be assigned to a legislation group and their metadata can be
filled in.
Important: When checks have been configured in BIM module admin view, then they must not be
deleted from BIM.works. Instead, they can be deactivated in the BIM module (and left untouched in
BIM.works).
Also important: Modifying checks is possible in BIM.works, but this causes a situation where it is hard to
track what users ran the old / new version of the check. Therefore, it is recommended to create a new
check and deactivate the previous one in the BIM module.
Diagram “Admin module v2”
22.Providing BIM model export functionality for 3rd party software
At the moment, this export functionality is planned to be used by:
• 3D twin (show exterior shell of the model)
• Users with relevant access rights should be able to download the IFCs
The endpoint for giving out models will be provided by BIM.works. However, in order to know what
BIM.works models correspond to which applications and buildings, information must be queried from
the BIM module.
For this purpose, the BIM module provides the following endpoint for 3D twin:
• GET <domain>/api/bim_module/v1/applicationModels
• Input parameters:
o <none>
• Response object is an array of applications, where each application is an object with the
following structure:
{
applicationId: …,
applicationNr: …, //refers to the latest application round
applicationStatus: …, //see chapter 10 for possible statuses
applicationLatestChangeDate: …,
buildings: [
ehrCode: …,
buildingName: …,
models: [
{
discipline: …,
versionUUID: …
},
, … //another model
],
… //another building
]
, … //another application
}
Remark: Field “applicationLatestChangeDate” allows 3D twin to detect only the changed applications.
Using this information, it is possible to query BIM.works for getting the actual models.
BIM.works has the ability to create API Tokens that have access rights on a specific folder. The idea is to
create a read-only API Token for for example the Digital Twin application (and possibly also others) with
access to all the models that have been uploaded. The API call to the BIM Module will return an array of
Version UUID which basically identify the set of models. With this information two different API calls can
be done:
1. Download the GLTF file: To get a GLTF of the outer shell of the model(s)
2. GetGeoReference: To get information about where the 0, 0, 0 point (in the GLTF) is located
geographically and how it’s rotated.
BIM.works has all these calls documented internally. Any person with access to BIM.works can read the
documentation.
EHR arendustööde läbiviimise ja testimise juhend
V4 – 03.12.2020
Käesolev juhend on mõeldud järgimiseks kõigile EHR arendusega seotud osapooltele.
Juhendis on kirjeldatud infovahetuse allikad ja kohustused.
1. EHR arendustööde dokumentatsiooni hoitakse Sharepoint dokumendihalduses (SP).
Keskkonna halduse ja juurdepääsu eest vastutab MKM. Meeskondade projektijuhid
edastavad projekti alguses nimekirja (ees- ja perenimi, isikukood, e-kirja aadress)
osalistest, kes peavad juurde pääsema EHR dokumendihoidlale.
2. Projekti alguses luuakse SP-sse projekti kaust, kuhu kogutakse kõik projektiga seotud
dokumendid nagu koosolekute protokollid, lähteülesanded, projektiplaanid jm.
dokumendid. Juhul, kui dokument paikneb kuskil teises asukohas siis lisatakse SP
projektikausta link sellele dokumendile.
3. EHR dokumentatsioon antakse Tellijale üle dokumendihalduse keskkonna kaudu. Juhul,
kui samast dokumendist edastatakse mitu versiooni, siis kõik erinevad versioonid tuleb
nimetada ühe ja sama failinimega. Versioonid eristuvad SP-s „versiooni ajaloo“ kaudu.
4. EHR dokumentide sisukord (analüüsi, disaini, arhitektuuri, testimise, projektijuhtimise
kontekstis) lepitakse kokku enne vastavate projekti tööde algust. Täitja projektijuht, kes
hakkab vastavat dokumenti koostama, esitab hiljemalt tööde alguse kuupäeval SP
projektikausta dokumendi kavandi, milles on toodud vähemalt dokumendi sisukord ja
võimalusel ka vorm.
5. Operatiivse suhtlusvahendina kasutatakse lisaks (mobiil)telefonile ka Skype keskkonda.
Projekti osalised lisatakse projekti ühisvestlusesse. Täitja projektijuht edastab vajalike
osaliste Skype kontode nimekirja MKM projektijuhile, kes lisab nimekirja liikmed vestlusele.
5.1. Projekti kestel on kõigil meeskonnaliikmetele kohustus osaleda vestluses;
5.2. Projektide vahelisel ajal tööde planeerimiseks või vigade aruteluks, on tehnilistel
projektijuhtidel, analüütikutel või arhitektidel kohustus osaleda vestluses;
5.3. Vestluses on kohustuslik informeerida kõiki osapooli kavandatavatest tarnetest. Vt.
EHR koodi haldamise ja tarnimise juhendit
6. Osapooled praktiseerivad proaktiivset kommunikatsiooni ning ei varja võimalike vigu ja
probleeme.
7. EHR tarnete, arendustööde, vigade ja hooldustööde fikseerimiseks kasutatakse JIRA
keskkonda. Meeskondade projektijuhid edastavad projekti alguses nimekirja (ees- ja
perenimi, isikukood, e-kirja aadress) osalistest, kes peavad juurde pääsema EHR JIRA
keskkonnale.
8. Arendusprojektide läbiviimise alguses koostab Täitja Lepingu lähteülesandes toodud
funktsionaalsete nõuete kohta JIRA piletid tüübiga “arendus”. Arenduspiletite
koondamiseks luuakse JIRA komponent, nii, et kõik ühe lepinguga seotud (või lepingu
alapunktiga) seotud piletid on seotud vastava komponendiga. Komponentide abil saab
ülevaate kõigist komponendiga seotud arendustöödest ja veapiletitest, mis vastavas
komponendis aja jooksul on tehtud.
9. Lepinguliste tööde arendamiseks, testimiseks ja üleandmiseks koostatakse kõikidest üle
antavatest JIRA piletitest sprint, mille kestus on max 1 kuu. Arendustööde sprindi paigaldus
ja üleandmine toimub vastavuses EHR koodi haldamise ja tarnimise juhendile
10. Lepinguliste tööde Tellijale üleandmine algab Täitja poolt üleandmise akti esitamisega (või
vastavuses Lepinguga). Üleandmise aktis peavad olema viited kõigile üleantavatele
tulemitele sh.:
10.1. Lingid üleantavatele koodidele Git-s (git.mkm.ee). Link peab olema koodiharule
ja -versioonile, milles asub üleantav kood,
10.2. Viide API teenuste endpointidele Swaggeris (swagger.ehr.ee)
10.3. Viide Katalon automaattestidele, millega üleantavat rakendust saab testida
10.4. Viited projekti tulemdokumentidele SP-s
(https://365mkm.sharepoint.com/sites/MKM/EHR)
10.5. Viit, millelt Tellija saab alustada rakenduse testimist
10.6. Üle antava rakenduse Helm Chart nimetus ja versioon (juhul, kui üle antav
rakendus paigaldatakse Kubernetes klastrisse)
11. JIRAsse loodud arenduspiletid peavad olema sellise detailsusastmega, et nende alusel
saavad arendajad teostada arendustööd ning testijad saavad läbi viia vastuvõtu testimise.
12. Arendustöödes tuvastatud vigade lahendamiseks koostab MKM Helpdesk JIRA-sse lisatud
veapiletite alusel kord kuus arendajale kriitiliste vigade sprindi, mille arendaja tarnib
järgmisel kuul MKM-le testimiseks.
13. JIRA piletite lahendamise protsessi üldine kirjeldus on järgmine:
13.1. Töid üle andva arenduspartneri testija testib kõik üle antavad piletid esmalt
MKM keskkonnas “test”. Testimisel viib testija piletid oma nimele staatusega
„TESTIMISEL“. Peale testimist viib arenduspartneri testija piletid staatusesse
„OMANIKU TESTI OOTEL“ ja suunab piletid MKM testijale. Üldpõhimõttena antakse
piletid üle “OMANIKU TESTI OOTEL” staatusesse esimesel võimalusel, ehk ei neid ei
grupeerita ega anta üle portsude kaupa.
13.2. MKM testijad testivad piletid ning peale testimist suunavad arenduspartneri
testijale staatuses „TESTITUD“ või „AVATUD“ vastavalt sellele, kas pilet oli
lahendatud või esineb vigu.
13.3. Kui kõik sprindi piletid on peale MKM testimist staatuses „TESTITUD“, siis võib
liikuda järgmisesse toodangusse viimise etappi “prelive”.
13.4. Peale “prelive” tarnet testib arenduspartneri testija kõik üle antavad piletid
esmalt MKM “prelive” keskkonnas. Testimisel viib testija piletid oma nimele staatusega
„TESTIMISEL“. Peale testimist viib arenduspartneri testija piletid staatusesse
„OMANIKU TESTI OOTEL“ ja suunab piletid MKM testijale.
13.5. MKM testijad testivad piletid prelive keskkonnas ning peale testimist muudavad
pileti staatuseks „LAHENDATUD“, „TARNE OOTEL“ või „AVATUD“ vastavalt sellele,
kas pilet oli lahendatud, vajab üle kontrollimist toodangus või esineb vigu.
13.6. Kui kõik prelives oleva tarne piletid on staatuses „LAHENDATUD“, siis võib
alustada toodangusse tarnimisega.
13.7. Juhul, kui “prelive” etapis avastati vigu siis alustatakse peale vigade
parandamist uuesti “test” etapist.
14. Kõikide osapoolte projektijuhid lisatakse JIRA tarnepiletite kohta info saajateks.
15. Tööde tähtaegade fikseerimisel tuleb arvestada, et töö tähtaeg tähendab kokkulepitud
päeva algust kell 00.00.
16. Kõik MKM projektiga seotud meediaga suhtlus tuleb alati kooskõlastada ennetavalt
MKMiga; ka MKM peab ennetavalt kooskõlastama partneritega meediasse suunatava
informatsiooni.
17. Kõik EHR arenduse projektis läbi viidud koosolekud protokollitakse (fikseeritakse otsused,
riskid, probleemid) ja soovi korral helisalvestatakse, selles osas lepitakse rollide täitjad
kokku enne koosoleku algust. Üldjuhul koostab protokolli Täitja projektijuht ja salvestab
selle koosolekule järgneval tööpäeval SP-sse projekti kausta.
18. Iga sprindi/arendusetapi lõpus viiakse vajadusel läbi üle antava töö ühisläbivaatus, mille
käigus Täitja esindajad esitlevad Tellijale üle antava töö tulemit.
19. Täitja projektijuht esitab projekti alguses MS Project formaadis projekti tööde plaani SP-
sse projekti kausta (kui MKMiga ei ole eelnevalt kokku lepitud teisiti). Täitja projektijuht
uuendab igal projekti töönädala esmaspäeval esialgselt esitatud projektiplaani ning lisab
sellesse tööde täitmise informatsiooni.
20. Tööde plaan vaadatakse kõigi osapoolte poolt üle igal projekti koosolekul ja vajadusel
viiakse sellesse muudatused.
21. Juhul, kui arendusprojekti käigus on vajalik EHR andmebaasides muudatuste tegemine
siis peab järgima: E-ehituse andmebaasid ja nende uuendamine
22. Juhul, kui arendusprotsessi käigus luuakse uus teenuste API või täiendatakse
olemasolevaid teenuseid siis arendaja täiendab API kirjeldust Swaggeris vastavalt EHR
API teenuste nimetused ja teenuste kirjeldamine
KÄSKKIRI
12.11.2021 nr 90
Riigihanke "BIM-põhise ehitusloa menetluse
tarkvaralahenduse integreerimine EHR
menetluskeskkonda " korraldamine, komisjoni ja
vastutava isiku nimetamine
Riigihangete seaduse § 14 lõike 2 punkti 1, §-de 100 ja 101 alusel ning kooskõlas ettevõtlus- ja
infotehnoloogiaministri ning majandus- ja taristuministri 09.10.2017. a käskkirjaga (registreeritud
dokumendihaldussüsteemis 03.10.2017. a) nr 1.1-1/17-199 kinnitatud „Majandus- ja
Kommunikatsiooniministeeriumi hankekorraga“:
1. Korraldada avatud hankemenetlusega riigihange (CPV kood 72200000-7, nimetus „Tarkvara
programmeerimis- ja nõustamisteenused“) „ BIM-põhise ehitusloa menetluse
tarkvaralahenduse integreerimine EHR menetluskeskkonda“ (edaspidi Töö) tellimiseks.
Riigihange rahastatakse Majandus- ja Kommunikatsiooniministeeriumi ehitus- ja
elamuosakonna (EEO) Targa Ettevõtluse Programmi (TEP) eelarvest.
2. Kinnitan käskkirja punktis 1 nimetatud Töö tellimiseks riigihanke alusdokumendid (lisatud).
3. Tellitava töö eeldatav maksumus on 85 000 eurot (lisandub käibemaks) ning see makstakse
välja Majandus- ja Kommunikatsiooniministeeriumi eelarvest.. Töö esitamise tähtpäev on 2,5
kuud lepingu sõlmimisest.
4. Määran käskkirja punktis 1 nimetatud hanke korraldamise eest vastutavaks isikuks EEO
ehitisregistri (EHR) BIM-projektijuhi Christopher-Robin Raitviir’i.
5. Moodustan hankekomisjoni punktis 1 nimetatud riigihanke korraldamiseks, sh pakkujatel
kõrvaldamise aluste ja pakkujate kvalifitseerimise tingimustele vastavuse kontrollimiseks
hankepassi alusel, pakkumuste vastavaks tunnistamiseks ja eduka pakkumuse
väljaselgitamiseks ning edukal pakkujal kõrvaldamise aluste ja kvalifitseerimise tingimustele
vastavuse kontrollimiseks hankepassis esitatud kinnitustele vastavate dokumentide
alusel järgmises koosseisus:
5.1. Komisjoni esimees:
Christopher-Robin Raitviir, EEO ehitisregistri talituse BIM-projektijuht.
2
5.2. Komisjoni liikmed:
5.2.1. Jüri Rass, Majandus- ja Kommunikatsiooniministeeriumi ehituse asekantsler;
5.2.2. Taavi Jakobson, EEO Ehitisregistri (EHR) ja e-ehituse projekti juht;
5.2.3 Jaan Saar, EEO digitaalehituse valdkonna juht.
6. Valitud hankemenetluse liigi ja käskkirja punktis 2 nimetatud riigihanke alusdokumentide
peale võib esitada vaidlustuse Rahandusministeeriumi juures asuvale riigihangete
vaidlustuskomisjonile riigihangete seaduses sätestatud korras ja tähtajal.
(allkirjastatud digitaalselt)
Ando Leppiman
kantsler
HD Lisa 2
TÖÖVÕTULEPING nr
ERITINGIMUSTE PROJEKT
Tallinn
Majandus- ja Kommunikatsiooniministeerium, registrikood 70003158, asukoht Suur-
Ameerika 1, Tallinn 10122, mida esindab põhimääruse alusel kantsler Ando Leppiman
(edaspidi tellija),
ja
XXX, registrikood …, asukoht …, mida esindab /juhatuse liige /volituse alusel … (edaspidi
töövõtja),
keda edaspidi nimetatakse üheskoos ka pooled ja eraldi pool,
sõlmivad käesoleva teenuse osutamise lepingu (edaspidi leping) alljärgnevas:
1. Üldsätted
1.1. Lepingu moodustavad eri- ja üldtingimused koos lisadega kui konkreetsest lepingu
sättest ei tulene teisiti. Eritingimused sisaldavad üldtingimuste täiendusi ja parandusi.
1.2. Lepingu dokumentide prioriteetsus on järgmine: eritingimused (I), lepingu lisad (II) ja
üldtingimused (III). Vastuolude korral lepingu dokumentide vahel prevaleerib
prioriteetsem dokument.
2. Lepingu ese, alus ja tähtaeg
2.1. Lepingu esemeks on BIM-põhise ehitusloa menetluse tarkvaralahenduse integreerimine
EHR menetluskeskkonda (edaspidi töö), mida töövõtja kohustub tegema vastavalt
lepingus ja lepingu lisades sätestatud tingimustele. Töö täpsem kirjeldus on sätestatud
lepingu Lisas 1.
2.2. Leping sõlmitakse tellija korraldatud riigihanke “BIM-põhise ehitusloa menetluse
tarkvaralahenduse integreerimine EHR menetluskeskkonda” (viitenr 243142)
tulemusena ning vastavalt riigihanke alusdokumentidele ning töövõtja edukaks
tunnistatud pakkumusele.
2.3. Töövõtja teostabpunktis 2.1 nimetatud töö ja annab selle tulemused tellijale üle kahes
etapis vastavalt Lisas 1 toodud tähtaegadele (Tehniline kirjeldus p 3.1.). I etapi tööde
üleandmise tähtaeg on 28.12.2021 ja II etapi tööde üleandmise tähtaeg on 2,5 kuud
alates lepingu sõlmimisest.
2.4. Vajadusel! Juhul kui töövõtja on alustanud töö tegemist enne kui leping sõlmitakse, siis
kirjutada: Poolte eelneval kokkuleppel on Töövõtja alustanud tööga .../kuupäev/.
3. Tasu suurus, väljamaksmise tähtaeg ja kord
Tellija tasub töövõtjale lepingus sätestatud töö teostamise eest tasu summas XXX eurot,
summale lisandub käibemaks. Töö eest tasutakse kahes osas. I etapi eest makstakse 40%
ja II etapi eest 60% lepingu maksumusest.
4. Garantiitingimused
4.1. Töövõtja garanteerib arendustöö vastavuse lepinguga sätestatud tingimustele 24
(kahekümne nelja) kuu jooksul pärast töö vastuvõtmist tellija poolt (edaspidi
Garantiiperiood).Garantii kehtib ainult tööle ning ei laiene koos tööga kasutatavatele
toodetele ja tööst tellija või kolmanda isiku poolt tehtud töötlustele.
4.2. Tellija informeerib töövõtjat Garantiiperioodil avastatud veast ning kirjeldab seda
piisava põhjalikkusega. Vigadest informeerimine toimub tellija projektijuhtimise
keskkonna JIRA lisatud veateate kaudu. Garantiiperioodil parandab töövõtja vead omal
kulul, välja arvatud juhul, kui vigade tekkimine on põhjustatud tellija süülisest
tegevusest, millisel juhul tasub parandustöödega ja vea esinemisega kaasnenud tellija
nõustamisega seotud kulud tellija.
5. Poolte volitatud esindajad
5.1. Tellija volitatud esindaja lepingu tingimuste täitmisel, täitmise kontrollimisel ja töö
vastuvõtmisel on Christopher-Robin Raitviir, telefon 58586446, e-post
[email protected].
5.2. Töövõtja volitatud esindaja lepingu tingimuste täitmisel ja täitmise kontrollimisel on …,
telefon … , e-post … .
6. Lepingu lisad
6.1. Lepingu allakirjutamisel on lepingule lisatud:
6.1.1. Lisa 1. Riigihanke alusdokumendid (leitavad riigihangete registris);
6.1.2. Lisa 2. Töövõtja pakkumus;
... 6.1.3. Lisa 3. Töö üleandmise-vastvõtmise akti vorm.
7. Muud sätted
7.1. Töövõtja kinnitab, et on üldtingimustega tutvunud elektroonselt riigihangete registris
või Majandus- ja Kommunikatsiooniministeeriumi veebis aadressil:
https://mkm.ee/et/ministeerium-kontaktid/teated-hanketeated-ja-lepingute-uldtingimused
7.2. Töövõtja on teadlik, et leping on avalik, välja arvatud osades, mis on märgitud avaliku
teabe seadusest tulenevatel alustel asutusesiseseks kasutamiseks.
7.3. Leping allkirjastatakse digitaalselt.
Tellija Töövõtja
/allkirjastatakse digitaalselt/ /allkirjastatakse digitaalselt/
HD LISA 3
CV VORM– EKSPERT/PROJEKTIJUHT
Roll hankelepingu täitmisel: …
Ees- ja perekonnanimi:
Sünniaeg:
Haridus (märkida õppeasutuse
nimi, kraadi nimetus, tase ning
tunnistuse number, väljaandmise
aeg ):
Kogemuse kirjeldus
(vastavalt hankedokumendi
punktis 8 nõutule:
Töö nimetus:
Tellija:
Läbiviimise aeg (pp.kk.aa–
pp.kk.aa):
Roll, vastutus ja ülesanded
projektis:
Töö sisu lühikirjeldus:
Mina, allakirjutanu, olles ........... (pakkuja nimi) meeskonna liige, kinnitan CV-s esitatud andmete
õigsust ja oma valmisolekut osaleda hankelepingu täitmisel käesolevas CV-s märgitud rollis kogu
hankelepingu kehtivusaja jooksul (või perioodil: nimetada periood).
Kinnitan, et kuulun pakkuja vastutavasse projektimeeskonda ja vastan riigihanke alusdokumentides
spetsialistile esitatud tingimustele hankelepingus täidetava rolli ulatuses.
Vajadusel lisada ridu (nt kui spetsialist on osalenud rohkemates projektides ning pakkuja soovib selle
kohta informatsiooni esitada). Minimaalselt tuleb esitada vormil nõutud informatsioon.
CV esitaja: Pakkuja:
/allkirjastatud digitaalselt/ /allkirjastatud digitaalselt/
HD Lisa 4
Ärisaladuse teabe esitamise vorm
Avaldame, et riigihankele viitenumbriga 243142 meie esitatud pakkumusest on ärisaladusega
kaitstud järgmised dokumendid või teave:
Jrk Dokumendi nimetus Põhjendus teabe
(terviktekst või viide ärisaladuseks
dokumendis sisalduvale määramisest
teksti osale)
1.
2.
3.
…
…
(vajadusel lisada ridasid)
Oleme teadlikud, et:
riigihangete seaduse § 111 lõige 5 kohaselt ei või pakkuja ärisaladusena märkida:
pakkumuse maksumust ega osamaksumusi;
teenuste hankelepingute puhul lisaks pakkumuse maksumusele ja osamaksumustele
muid pakkumuste hindamise kriteeriumidele vastavaid pakkumust iseloomustavaid
numbrilisi näitajaid;
asjade hankelepingute puhul lisaks pakkumuse maksumusele ja osamaksumustele
muid pakkumuste hindamise kriteeriumidele vastavaid pakkumust iseloomustavaid
näitajaid.
HD Lisa 1
BIM-põhise ehitusloa menetluse tarkvaralahenduse integreerimine EHR
menetluskeskkonda
Tehniline kirjeldus
Koostaja: Majandus- ja Kommunikatsiooni-
ministeeriumi Ehitisregistri talitus
Tallinn 2021
Sisukord
Lühendid ja mõisted ................................................................................................................................ 3
1. Sissejuhatus ......................................................................................................................................... 4
2. Eesmärk ............................................................................................................................................... 4
3. Nõuded ................................................................................................................................................ 4
3.1 Ajakava .......................................................................................................................................... 4
3.2 Üldised nõuded arendusprotsessile .............................................................................................. 5
3.3. Nõuded BIM-põhise loamenetluse tarkvaralahenduse integratsioonile EHR
menetluskeskkonda............................................................................................................................. 6
Arendaja peab integreerima BIM API UI, UX ja teenused EHR menetluskeskkonda nii, et projekti
tulemusena on võimalik BIM-põhist loamenetlust läbi viia EHR-s.................................................. 6
Nõuete täitmisel peab arvestama peamiselt järgmiste API-de koostoimimise vajadusega: .......... 6
3.3.1. BIM API integratsioon ehitusloa taotluse dokumendile ....................................................... 6
3.3.2. BIM-mudelite üles laadimise liidestus ehitusprojekti dokumentide API ning BIM API vahel 6
3.3.3. BIM mudelist ekstraktitud andmete salvestamine ehitusloa taotluse vormil ...................... 7
3.3.4. BIM-põhise loamenetluse alustamise ja katkestamise funktsionaalsus ............................... 7
3.3.5. Menetlejate, kooskõlastajate ja arvamuse avaldajate märkuste kuvamine BIM APIs........ 10
3.3.6. Teenuse haldaja vaate integreerimine EHR-ga ................................................................... 10
3.3.7. BIM API seisundite integreerimine EHR-ga ......................................................................... 10
3.3.8. BIM API-st tulevate teavituste saatmine EHR kasutajale .................................................... 10
2
Lühendid ja mõisted
API – Application Programming Interface – rakendusliides e. programmiliides
BIM – Building Information Modeling – ehitusinformatsiooni modelleerimine
E-ehituse platvorm – MKM EEO poolt välja arendatav ehitusvaldkonna e-teenuste
integratsioonikeskkond
EEO – Majandus- ja Kommunikatsiooniministeeriumi ehitus- ja elamuosakond
EHR – Ehitisregister
EV – Eesti Vabariik
IFC – Industry Foundation Classes – vabavaraline BIM informatsiooni failiformaat
KAOL – ehitise kasutusotstarvet kirjeldav klassifikaator EHR andmebaasis
KOV – kohalik omavalitsus
MKM – Majandus- ja Kommunikatsiooniministeerium
UI – User Interface - kasutajaliides
UX – User Experience – kasutajakogemus
3
1. Sissejuhatus
Ehitisregister (EHR) on Eesti Vabariigi Majandus- ja Kommunikatsiooniministeeriumi (MKM) Ehitus- ja
elamuehitusosakonna (EEO) hallatav keskne riiklik register, kus hallatakse ehitiste infot ja mille kaudu
kodanikud ja ettevõtted esitavad ehituslubade taotlusi ning kohalikud omavalitsused viivad läbi
ehituslubade väljastamise menetlust. Hetkel on käimas mitmed IT-arendused EHR tehniliseks
kaasajastamiseks, eelkõige selle üleviimiseks mikroteenuste arhitektuurile, mille kontseptuaalseks
aluseks on e-ehituse platvorm kui ehitusvaldkonna e-teenuste integratsioonikeskkond.
Projekti eesmärk on integreerida EHR menetluskeskkonnaga BIM-põhise loamenetluse mikroteenuse
tarkvara, mis võimaldaks KOV-del, teistel ehitusloa menetluses osalevatel pädevatel asutustel ja
ehitusloa taotlejatel läbi viia BIM-põhiseid kontrolle.
Projektdokumentatsiooni tehniline kontroll (vastavus planeeringutele, seadustele/normidele) on üks
aeganõudvamaid ja vearohkemaid tegevusi ehituslubade menetlemise käigus. Tehnilisi nõudeid ning
kooskõlastajaid on palju (KOV, Päästeamet, Keskkonnaamet, Muinsuskaitseamet jne). EHRis on praegu
võimalik projektdokumentatsiooni salvestada ja menetleda ainult digitaalselt mittetöödeldavas (.pdf)
formaadis. Kui mõni projekti osa vajab parandamist, tuleb kooskõlastajatel uuendatud versioon jälle
täies mahus läbi vaadata. Probleemi ressursse raiskav mõju on arvestatav, sest Eestis menetletakse
rohkem kui 12 000 ehitusluba ja üle 8600 kasutusloa aastas.
Samal ajal on ehitiste projekteerimisel aina olulisemaks ja levinumaks lahenduseks muutunud BIM
mudelite kasutamine, seda eriti suurte avalike hoonete ja kinnisvaraarenduste puhul. BIM kasutamine
aitab ehitusvaldkonna ettevõtetel oluliselt säästa aega tööprotsesside läbiviimisel ning tõsta projektide
kvaliteeti, sest info digitaalne töödeldavus ning seostatus mudelites vähendab oluliselt vigade
tekkimise võimalusi. Ehitise infomudelid on Eestis projekteerimisel ja ehitamisel juba laialdaselt
kasutusel.
BIM- põhine loamenetlus võimaldab lühendada ehitusloa menetlemise protsessi läbi ehitusprojektide
tehnilise kontrolli automatiseerimise. Efektiivsem ehitusloa menetlemise protsess aitab kaasa
ehitussektori tootlikkuse tõstmisele, mis on MKM ehitusvaldkonna arendustegevuste laiem eesmärk.
MKM EEO eestvedamisel on teostatud või teostamisel mitmed tööd digitaalehituse edendamiseks ning
EHR üleviimiseks mikroteenuste arhitektuurile. Sellesse EHR IT arenduste ökosüsteemi kuulub ka
käesolev arendus.
2. Eesmärk
Arendajal tuleb integreerida EHR menetluskeskkonda BIM-põhise loamenetluse tarkvara, eesmärgiga
võimaldada EHR kasutajatel BIM-põhiselt ehitusluba taotleda.
3. Nõuded
3.1 Ajakava
Tööde üleandmise lõpptähtaeg on 2,5 kuud pärast lepingu sõlmimist.
4
Töö tulemite üle andmine Tellijale toimub koheselt peale nende valmimist, et Tellijal oleks võimalik
neid testida, anda Arendajale vahetult tagasisidet ja võimalusel anda tarnitud komponendid
kasutajatele kasutamiseks.
Üleandmis-vastuvõtu aktide vormistamine ja tööde eest tasumine toimub kahes etapis:
Etapp Arendustöö Hiliseim tähtaeg
I BIM-mudelite üles laadimise liidestus (3.3.2) 28.12.2021
I BIM mudelist ekstraktitud andmete salvestamine (3.3.3) 28.12.2021
I BIM-põhise loamenetluse alustamise ja katkestamise 28.12.2021
funktsionaalsus (3.3.4)
I BIM API integratsioon ehitusloa taotluse dokumendile 28.12.2021
(3.3.1)
II Teenuse haldaja vaate liidestamine EHR-ga (3.3.6) 2,5 kuud pärast lepingu
sõlmimist
II Menetlejate, kooskõlastajate ja arvamuse avaldajate 2,5 kuud pärast lepingu
märkuste kuvamine BIM APIs (3.3.5) sõlmimist
II BIM API seisundite liidestamine EHR-ga (3.3.7) 2,5 kuud pärast lepingu
sõlmimist
II BIM API-st tulevate teavituste saatmine EHR kasutajale 2,5 kuud pärast lepingu
(3.3.8) sõlmimist
Arendaja koostab tööd alustades detailse kalendergraafiku täitmaks Tellija poolt antud etappe ning
kooskõlastab selle Tellijaga.
3.2 Üldised nõuded arendusprotsessile
a. Arendus peab vastama MKM Infosüsteemide arendustalituse poolt kindlaks määratud
nõuetele, mis on kirjeldatud järgmistes dokumentides:
Lisa 1 - e-ehituse platvormi tarkvaraline arhitektuur;
Lisa 2 - e-ehituse platvormi ristfunktsionaalsed nõuded (mittefunktsionaalsed nõuded);
Lisa 3 - EHR arendustööde läbiviimise ja testimise juhend;
Lisa 4 - e-ehituse platvormi stiiliraamat;
Lisa 5 - Ehitisregistri (EHR) rakenduse koodi haldamise ja tarnejuhend;
Lisa 6- EHR API teenuste nimetused ja teenuste kirjeldamine;
Lisa 7 - Ehitisregistri andmebaasid ja nende uuendamise juhend;
Lisa 8 – BIM API arhitektuuridokument.
b. Arendus tugineb agiilse tarkvaraarenduse põhimõtetele. Tööde järjekorra ja läbiviimise
planeerimisel tuleb püüelda üksikute kasutajale lisaväärtust loovate teenuste kasutajate kätte
andmiseks (tarnimine/deploy) võimalikult varakult (mitte tervikuna projekti lõpus).
c. Kui Tellija teekides on olemas UI komponendid või mikroteenused, mida saab otse või
mõistliku lisatööga käesoleva projekti ülesannete täitmiseks kasutada, kasutab Arendaja neid
(mitte ei arenda vastavaid komponente/mikroteenuseid uuesti või kasuta enda vastavaid
teeke) - väljaarvatud juhul, kui selles ei ole Tellijaga eelnevalt kirjalikult taasesitatavas vormis
kokku lepitud. Enne iga komponendi realiseerimist kooskõlastab Arendaja selle Tellijaga.
Kooskõlastamise eesmärk on kokku leppida ja dokumenteerida arendatavate komponentide
5
tehnilised detailid enne vastava komponendi realiseerimist. Kokkulepped (otsused)
dokumenteeritakse koosolekute käigus ning Arendaja poolsed tööd dokumenteeritakse
niimoodi, et on Tellija erialalisele spetsialistile arusaadavad.
d. Arendaja pakub töö teostamiseks välja sobiva metoodika, mis lepitakse kokku Tellijaga töö
alguses. Arendus toimub tihedas koostöös Arendaja ja Tellija vahel. Arendaja pakub töö käigus
jooksvalt välja omapoolseid lahendusi töö teostamiseks ning arutab need läbi töö Tellijaga.
e. Enne tarkvara integratsiooni realiseerimist koostab Arendaja kasutaja teekondade kaardistuse
(UX interaction flow).
f. Vajaduse ilmnemisel on Arendaja valmis asendama töölõike samaväärsetega, kui töö
teostamise käigus selgub, et vahetus aitab töö eesmärki paremini saavutada. Arendaja peab
arvestama, et hinnanguliselt 15% arendusmahu tundidest on ette nähtud käesoleva projekti
arendustöö käigus täpsustuvate nõuete teostamiseks.
g. Arendusprotsess ja selle lõpptulemused dokumenteeritakse vastavalt tarkvaraarenduse heale
tavale.
3.3. Nõuded BIM-põhise ehitusloa menetluse tarkvaralahenduse integratsioonile
EHR menetluskeskkonda.
Arendaja peab integreerima BIM API UI, UX ja teenused EHR menetluskeskkonda nii, et projekti
tulemusena on võimalik BIM-põhist ehitusloa menetlust läbi viia EHR-s. Tehtava integratsiooni
põhimõtted peavad olema teostatud niimoodi, et seda on võimalik rakendada ka järgnevate
loamenetluste (näiteks kasutusluba) alusena.
Nõuete täitmisel peab arvestama peamiselt järgmiste API-de koostoimimise vajadusega:
a. MKM bimworks API
b. EHR Proceeding API
c. EHR Notification API
Arvestama peab lisaks ka teiste e-ehituse API-dega mis on MKM Swaggeris
Integratsiooni teostamisel tuleb välja arendada järgmised funktsioonid:
3.3.1. BIM API integratsioon ehitusloa taotluse dokumendile
Arendustöö tulemus peab võimaldama BIM API integratsiooni ehitusloa taotluse dokumendile
vastavalt BIM API arhitektuuridokumendile (lisa 8), eelkõige punktidele 1-11 ja 17-19.
3.3.2. BIM-mudelite üles laadimise liidestus ehitusprojekti projektifailide API ning BIM API
vahel
a. Arendustöö tulemus peab võimaldama EHR-i üles laaditud IFC formaadis failide kuvamist BIM
moodulisse vastavalt BIM API arhitektuuridokumendile.
b. Arendustöö tulemusena peab olema võimalik EHR-i üles laaditud BIM mudelite IFC formaadis
failide sidumine ehitistega, et kasutaja saaks lisada nimetatud failidele EHR koodi. Ehitise
sidumine peab olema võimalik üks-ühele ning üks-kõigile seoste alusel ning lahendus
6
võimalikult kasutajasõbralik. Arendaja peab välja pakkuma sobiva UI ning UX lahenduse ning
realiseerima selle kooskõlastades lahenduse Tellijaga.
c. Kui BIM moodulis vajutatakse nuppe „Lisan faile“ või „Muudan faile“, edastatakse BIM API
poolt sündmus (event) requestForRedirectToFileUploadTab. Arendustöö tulemusena peab
selle sündmuse põhjal avanema Dokumendid vaheleht ehitusloa taotluse dokumendil.
„Muudan faile“ nupu lahendus BIM moodulis
Integratsiooni jaoks vajalik tehniline arhitektuur on täpsemalt kirjas punktis 12 BIM API
arhitektuuridokumendis (lisa 8).
3.3.3. BIM mudelist ekstraktitud andmete salvestamine ehitusloa taotluse vormil
BIM-põhise loamenetluse käigus BIM mudelist välja loetud ehitise tehnilised andmed peavad olema
arendustöö tulemusena kantud ehitusloa taotluse vormile.
Arendaja lepib koostöös Tellijaga kokku projekti käigus, missugused andmeväljad jäävad taotleja
poolt üle kirjutatavateks ning missugused andmeväljad lukustatakse, mis tähendab, et kasutatakse
ainsa tõe allikana BIM mudelist loetud informatsiooni.
Lukustussüsteem peab olema lahendatud niimoodi, et Tellija saab ise muuta vaba välja lukustuvaks
ning vastupidi. Samuti peab arendustöö tulemusena olema võimalik BIM mudelist välja loetavate
andmete hulga muutmisel kajastada ka muudetud andmeväljasid praegu eksisteerival loataotluse
vormil.
Integratsiooni jaoks vajalik BIM mooduli tehniline arhitektuur on täpsemalt kirjas punktis 15 BIM API
arhitektuuridokumendis (lisa 8).
3.3.4. BIM-põhise loamenetluse alustamise ja katkestamise funktsionaalsus
BIM-põhise loamenetluse eristamiseks tavapärasest menetlusest, peab Arendaja looma ehitusloa
taotluse dokumendile lisanupu, mis võimaldab loa taotlejal valida BIM-põhist loamenetlust. BIM
nupu kontseptsioonlahendust ning BIM menetluse valimisel tekkinud lisaakent akna „Ehitised“ ja
„Isikud“ vahel näeb allolevatelt joonistelt.
7
BIM nupu kontseptsioonlahendus
BIM nupust tingitud BIM mooduli avanemise kontseptsioonlahendus
Nupu vajutamisel taotleja poolt, peab arendustöö tulemusena olema tehniline lahendus võimalikult
sarnane selle alapeatüki punkti all olevale skeemile. Juhul, kui Arendaja näeb võimalust paremaks
lahenduseks, tuleb see kooskõlastada Tellijaga.
Nupu vajutamise tulemusena (või juhul, kui nuppu üleüldse ei vajutata) tekkinud seisundid
„BIM_menetlus=TRUE“ või „BIM_menetlus=FALSE“ tuleb kajastada ka RabbitMQ sõnumis, mis
edastatakse ehitise menetluse seisundi muutumisel ehitusloa menetluse protsessis. Nimetatud
sõnumi näidist on kajastatud BIM API arhitektuuridokumendis (lisa 8) peatükis 18. BIM moodulile
tuleb edastada ainult need sõnumid, kus „BIM_menetlus=TRUE“.
8
BIM-põhise loamenetluse eristamise põhimõtteline skeem
9
3.3.5. Menetlejate, kooskõlastajate ja arvamuse avaldajate märkuste kuvamine BIM moodulis
Integreerimise tulemusena peab EHR menetluskeskkonna märkuste lisamise mikroteenused ja UI
komponendid võimaldama ehitusloa menetlusprotsessis osalevatel menetlejatel, kooskõlastajatel ja
arvamuse avaldajatel lisada märkuseid BIM moodulis ning seal lisatud märkused peavad kajastuma
menetluskeskkonna märkuste koondtabelis. Täpsema kasutusloo lepib Arendaja kokku Tellijaga
projekti käigus ning teostab arenduse vastavalt Tellija soovidele.
Integreerimise jaoks vajalik tehniline arhitektuur on täpsemalt kirjas punktis 16 BIM API
arhitektuuridokumendis (lisa 8).
3.3.6. Teenuse haldaja vaate integreerimine EHR-ga
Teenuse haldaja vaade peab olema ligipääsetav ainult MKM organisatsiooni kasutajale. Haldaja vaate
täpse asukoha ning kuvamise kasutajaliideses selgitab Arendaja välja koostöös Tellijaga käesoleva
projekti käigus.
Integreerimise jaoks vajalik tehniline arhitektuur on täpsemalt kirjas punktis 21 BIM API
arhitektuuridokumendis (lisa 8).
3.3.7. BIM API seisundite integreerimine EHR-ga
Integreerimise tulemusena peavad olema BIM API seisundid seotud EHR menetluskeskkonnaga ning
kasutajal ei ole võimalik ehitusloa taotlust esitada, BIM-põhise menetluse valimisel, juhul kui BIM API
seisund seda ei võimalda. Esitamise proovimisel peab kasutajale kuvama täpsustava informatsiooni,
miks esitamine ei ole võimalik. Näiteks: BIM kontrollid ei ole teostatud
Integreerimise jaoks vajalik tehniline arhitektuur on täpsemalt kirjas punktis 14 BIM API
arhitektuuridokumendis (lisa 8).
3.3.8. BIM API-st tulevate teavituste saatmine EHR kasutajale
Integreerimise tulemusena peavad jõudma EHR kasutajani teavitused järgnevatel juhtudel:
a. Kõik BIM mudelid on üles laetud BIM.worksi ning kuvamiseks valmis BIM vahelehel
b. BIM kontrollid on lõpetatud ning tulemused on kasutajale kuvamiseks valmis
Integreerimise jaoks vajalik tehniline arhitektuur on täpsemalt kirjas punktis 13 BIM API
arhitektuuridokumendis (lisa 8).
10
KÄSKKIRJA LISA 1
Riigihanke „ BIM-põhise ehitusloa menetluse tarkvaralahenduse integreerimine EHR
menetluskeskkonda “ alusdokument.
Pakkujate hankemenetluselt kõrvaldamise alused, kvalifitseerimistingimused ja
kvalifikatsiooni tõendamise nõuded
1. Hankemenetluselt kõrvaldamise alused ja hankepassiga esitatav informatsioon
1.1. Hankija ei sõlmi hankelepingut ja kõrvaldab hankemenetlusest pakkuja, kellel
esineb RHS § 95 lõikes 1 nimetatud kõrvaldamise alus.
1.2. Hankija võib kõrvaldada hankemenetlusest pakkuja, kellel esineb RHS § 95
lõikes 4 nimetatud kõrvaldamise alus.
1.3. Hankepass peab sisaldama:
1.3.1. pakkuja kinnitust, et pakkuja ei vasta ühelegi RHS § 95 lõikes 1 või
lõikes 4 sätestatud tingimusele;
1.3.2. pakkuja kinnitust, et ta vastab kõikidele hanketeates pakkuja
kvalifitseerimiseks esitatud nõuetele;
1.3.3. märget selle kohta, milline ametiasutus või kolmas isik väljastab
vajaduse korral pakkuja kinnitustele vastavad andmed või dokumendid,
hankepassi allkirjastamisega pakkuja kinnitab, et tal on võimalik vajaduse
korral viivitamata need dokumendid hankijale esitada;
1.3.4. märget selle kohta, kas pakkuja kinnitustele vastavad andmed või
dokumendid on hankijale elektroonilises andmekogus olevate avalike
andmete põhjal oluliste kulutusteta kättesaadavad koos vastava veebilehe
aadressi, identifitseerimisandmete ja vajaduse korral pakkuja kinnitusega,
et ta on nõus oma andmete väljastamisega.
1.4. Pakkuja esitab kõrvaldamise aluste puudumise ja kvalifitseerimise tingimustele
vastavuse esialgse tõendina hankepassi Euroopa Komisjoni kehtestatud
standardvormil vastavalt RHS § 104 sätestatud tingimustele.
2. Pakkuja kvalifitseerimise nõuded:
2.1. Majanduslik ja finantsseis:
Netokäive on kahel viimasel riigihanke algamise ajaks lõppenud majandusaastal,
mille kohta on kinnitatud aruanded (2019 ja 2020; kui 2020. aasta aruanne on veel
kinnitamata, siis 2018 ja 2019), olnud vähemalt 80 000 eurot iga majandusaasta
kohta hanke esemega sarnases valdkonnas (CPV kategooria „Tarkvara
programmeerimis- ja nõustamisteenused“). Pakkuja esitab hankepassis andmed
netokäibe kohta.
2.2. Tehniline ja kutsealane pädevus:
Riigihanke algamisele eelneva 60 kuu jooksul on pakkuja täitnud ja tellijale üle
andnud vähemalt kaks (2) hanke objektiga sarnast tööd (teenusedisaini ja
kasutajakogemuse analüüsi sisaldava uuringu või arendusprojekti teostamine,
tarkvara/prototüübi arendus ja/või juurutamine) ning tellija on need vastu võtnud.
Täidetuks loetakse leping, mille täitmise tähtaeg on saabunud ning mille kohaselt
tellitud teenused on tellijale üle antud ja tellija poolt vastu võetud. Pakkuja esitab
hankepassis teabe eelnimetatud lepingute maksumuse, kuupäevade ja teiste
lepingupoolte kohta. Pakkuja esitab riigihanke viitenumbri juhul, kui on tegemist
täidetud riigihanke lepinguga.
KÄSKKIRJA LISA 2
Majandus- ja Kommunikatsiooniministeerium
BIM-põhise ehitusloa menetluse tarkvaralahenduse integreerimine EHR
menetluskeskkonda
Hankedokument
Riigihange
Tarkvara programmeerimis- ja nõustamisteenused
CPV kood 72200000-7
Tallinn 2021
SISUKORD
1. Üldandmed
2. Hankelepingu ese
3. Pakkumuse jõusoleku tähtaeg
4. Pakkumuse ettevalmistamise juhend ja pakkumuse esitamine
5. Pakkumuse koosseis
6. Pakkumuse maksumus
7. Kõikide pakkumuste tagasilükkamine
8. Nõuded pakkuja meeskonnale
9. Pakkumuste vastavuse kontrollimine
10. Pakkumuste hindamine ja hindamiskriteeriumid
11. Hankelepingu tingimused
Lisad
1. ÜLDANDMED
1.1. Hankija: Majandus- ja Kommunikatsiooniministeerium, registrikood 70003158,
asukoht Suur–Ameerika 1, Tallinn 10122, e-mail:
[email protected], tel. +372 625 6342
(edaspidi hankija).
1.2. Hankemenetluse liik: avatud hankemenetlus.
1.3. Hankemenetluse teostamise viis: e-menetlus riigihangete registris.
1.4. Riigihanke läbiviimise eest vastutav ametiisik: Majandus- ja
Kommunikatsiooniministeeriumi ehitus- ja elamuosakonna BIM-projektijuht
Christopher-Robin Raitviir, tel: +372 58586446, e-post:
[email protected].
1.5. Hankelepingu esemeks oleva töö etappide tulemused moodustavad loogilise ja
üksteisest sõltuva terviku, seetõttu ei jagata hanget ühe menetluse raames osadeks.
2. HANKELEPINGU ESE
2.1. Hankija kutsub esitama pakkumust „BIM-põhise ehitusloa menetluse
tarkvaralahenduse integreerimine EHR menetluskeskkonda“ (hankelepingu ese)
teostamiseks riigihanke alusdokumentides ja nende lisades sätestatud tingimustel.
2.2. Hankelepingu eseme detailne kirjeldus, selle eesmärk ja kontseptsioon on lahti
kirjutatud riigihanke alusdokumendis „Tehniline kirjeldus“ (Lisa 1).
2.3. Töö esitamise tähtpäev on 2,5 kuud alates lepingu sõlmimisest.
2.4. Pakkumuse esitamine tähendab pakkuja nõustumist kõikides riigihanke
alusdokumentides kehtestatud hanketingimuste ja reeglitega.
2.5. Pakkumus peab vastama riigihanke alusdokumentides esitatud tingimustele ja tuleb
esitada kogu riigihanke alusdokumentides nõutud mahus.
2.6. Alternatiivsete ja/või osaliste pakkumuste esitamine ei ole lubatud.
2.7. Hankija ei kompenseeri pakkujatele pakkumuse ettevalmistamisega seotud mistahes
kulusid, sh turu-uuringu läbiviimise ettevalmistamisega seotud kulusid.
3. PAKKUMUSE JÕUSOLEKU TÄHTAEG
3.1. Pakkumus peab olema jõus vähemalt 90 kalendripäeva. Pakkumuse jõusoleku
tähtaeg algab pakkumuse esitamise tähtpäevast.
3.2. Pakkuja esitab pakkumuses kinnituse pakkumuse jõusoleku kohta nimetatud tähtaja
jooksul.
3.3. Hankija pikendab vajadusel pakkumuste jõusoleku tähtaega kooskõlas RHS §-s 112
sätestatud reeglitega.
4. PAKKUMUSE ETTEVALMISTAMISE JUHEND JA PAK KUMUSE ESITAMINE
4.1. Hankemenetluses teavituste saamiseks peavad hankest huvitatud isikud hankijale
avaldama riigihangete registri e-keskkonnas oma kontaktandmed, registreerudes
hanke juurde „Hankes osalejad“ lehel. Hanke juurde registreerunud isikud saavad
automaatteavitusi riigihanke alusdokumendi tühistamise või muutmise kohta,
samuti toimub selgituste küsimine ja nendele vastamine e-riigihangete keskkonna
kaudu.
4.2. Pakkumuse esitamisega kinnitab Pakkuja kõigi riigihanke alusdokumentides esitatud
tingimuste ülevõtmist.
4.3. Pakkumus peab vastama riigihanke alusdokumentides esitatud tingimustele ja tuleb
esitada kogu riigihanke alusdokumentides nõutud mahus.
4.4. Pakkumus ja kõik pakkumuse juurde kuuluvad dokumendid peavad olema
vormistatud eesti keeles. Kõik muukeelsed dokumendid, kui neid on, peavad olema
tõlgitud eesti keelde, kusjuures tõlge peab vahetult järgnema originaalile. Erandiks
on ingliskeelsed reklaamialased trükised, mis võivad olla esitatud inglise keeles.
4.5. Pakkumus peab olema esitatud .pdf formaadis digitaalselt allkirjastatuna pakkuja
seadusjärgse või volitatud esindaja poolt.
4.6. Pakkuja võtab enda kanda pakkumuse ja pakkumuse tagasivõtmise teate hankijale
edastamise kogu riski, kaasa arvatud vääramatu jõu toime võimalus.
4.7. Pakkumused tuleb esitada hanketeates märgitud tähtpäeval ja kellaajal
elektroonselt riigihangete registri vahendusel: https://riigihanked.riik.ee.
Pakkumuse esitamise tähtpäev ja kellaaeg märgitakse e-riigihangete keskkonnas
hanke üldandmete lehele.
4.8. Juhul kui pakkumuse digiallkirjastamine ei ole võimalik (nt piiriülesed pakkujad) või
pakkumuse koosseisus on originaaldokumente, mida ei ole võimalik esitada
elektroonilisel kujul, esitatakse käsitsi allkirjastatud dokumendid skaneeritud
koopiatena e-riigihangete keskkonnas.
4.9. Pakkuja võib pakkumuse tagasi võtta enne pakkumuste esitamise tähtpäeva,
esitades hankijale pakkumusega samas vormis sellekohase teate läbi e-riigihangete
keskkonna.
4.10. Küsimused hanke alusdokumentide kohta tuleb esitada e-riigihangete keskkonna
kaudu. Küsimuste esitamiseks peab pakkuja end riigihanke juurde registreerima.
Hankija ei vastuta nimetatud keskkonna ja sidevahendite tehnilise toimimise eest.
4.11. Hankija vastab riigihanke alusdokumentidega seotud selgitustaotlustele kolme
tööpäeva jooksul asjakohase selgitustaotluse saamisest arvates. Hankija ei ole
kohustatud riigihanke alusdokumentidega seotud selgitustaotlusele vastama, kui
selgitustaotluse hankijale laekumise ja pakkumuse esitamise tähtaja vahele ei jää
vähemalt kuut päeva (RHS § 46 lg 2).
4.12. Pakkuja märgib pakkumuses selgelt eristataval viisil, milline teave on pakkuja
ärisaladus ning põhjendab ärisaladuseks määramist. Ärisaladusena ei ole lubatud
märkida pakkumuse maksumust, osamaksumusi ega muid pakkumuste hindamise
kriteeriumidele vastavaid pakkumust iseloomustavaid numbrilisi näitajaid (RHS
§ 111 lg 5). Hankija juhib tähelepanu, et eduka pakkuja pakkumus on avalik lähtuvalt
RHS § 110 lg 5, välja arvatud pakkuja poolt õigustatult ärisaladuseks määratletud
osas. Juhul kui pakkuja ei määratle pakkumuses arusaadavalt ärisaladust või ei
põhjenda asjakohaselt, miks on tegemist ärisaladusega, on Hankijal kohustus
teabenõude laekudes pakkumus täies ulatuses avalikustada.
5. PAKKUMUSE KOOSSEIS
5.1. Pakkuja esitab koos pakkumusega ajakohastatud kinnitusi sisaldava hankepassi
esialgse tõendina pakkuja suhtes kõrvaldamise aluste puudumise ning tema
kvalifitseerimise tingimustele vastamise kohta.
Pakkumuses tuleb esitada:
5.2. Tööde sisuline kirjeldus, mis võtab arvesse riigihanke alusdokumendis „Tehniline
kirjeldus“ (HD lisa 1, edaspidi tehniline kirjeldus) esitatud infot ja tingimusi ning mille
raames esitatakse:
5.2.1. Metoodika ja tulemuste kirjeldus vastavalt tehnilise kirjelduse p-le 5 (HD lisa 1);
5.2.2. Tegevuste loend ja kirjeldus, sealhulgas tulemuste saavutamiseks vajalike
täiendavate tegevuste (lisaks tehnilises kirjelduses nimetatule) kirjeldus ja
põhjendus;
5.2.3. Tegevuste ja tööde ajakava / projektiplaan koos ligikaudse eeldatud ajakuluga
olulisemate tegevuste lõikes;
5.2.4. Meeskonna koosseis ja nende valiku põhjendus;
5.2.5. Riskide loend koos nende realiseerumise tõenäosuse, mõju ja maandamise
viisidega.
5.3. Pakkumuse kogumaksumus, mis esitatakse riigihangete registri maksumuse vormil;
5.4. Projektis osalevate meeskonnaliikmete CV-d (HD lisas 3 esitatud vormil), mis on
meeskonnaliikme poolt allkirjastatud;
5.5. Vajadusel volikirjad, sh:
5.5.1. Juhul kui käesoleva dokumendi allkirjastab isik, kes tegutseb volikirja alusel,
tuleb lisada pakkumusele ka vastav seadusliku esindaja poolt allkirjastatud
volikiri;
5.5.2. Ühispakkujad peavad esitama volikirja, kus nimetavad riigihankega ning
hankelepingu sõlmimise ja täitmisega seotud toimingute tegemiseks endi seast
volitatud esindaja;
5.6. Ühispakkumuse korral esitavad ühispakkujad kinnituse, et vastutavad Hankija ees
hankelepingu täitmise eest solidaarselt;
5.7. Kui pakkumus sisaldab ärisaladust, tuleb pakkumusele lisada ärisaladuse teave (HD
lisas 4 esitatud vormil);
5.8. Muud kinnitused ja materjalid (vajadusel tõlked), mida pakkuja soovib pakkumusele
lisada.
6. PAKKUMUSE MAKSUMUS
6.1. Pakkumuse maksumus peab olema esitatud eurodes ilma käibemaksuta.
6.2. Pakkumuse eeldatav maksumus ilma käibemaksuta ei ületa 85 000 eurot.
6.3. Pakkumuse maksumus peab sisaldama kõiki töö läbiviimiseks, esitlemiseks ja üle
andmiseks (sh ettevalmistamine, läbiviimine, analüüs, intervjuud, töötoad,
tõlkimine, lähetused, tulemuste üleandmine ja esitlemine, kasutatava tarkvara
litsentsid jms) vajalikke kulusid, maksusid ja makseid. Hankija maksab hankelepingu
täitmise käigus Töö teostajale vastavalt riigihanke alusdokumentides määratud
etappidele (pärast vastavas etapis teostatud töö vastuvõtmist) ning täiendavaid
makseid ei tee.
7. KÕIKIDE PAKKUMUSTE T AGASILÜKKAMINE
7.1. Hankija võib teha põhjendatud kirjaliku otsuse kõigi pakkumuste tagasilükkamise
kohta, kui:
7.1.1. kõigi vastavaks tunnistatud pakkumuste maksumused ületavad punktis 6.2
nimetatud eeldatavat maksumust.
7.1.2. hankemenetluse läbiviimise ajal on hankijale saanud teatavaks uued asjaolud,
mis välistavad või muudavad hankijale ebaotstarbekaks hankemenetluse lõpule
viimise riigihanke alusdokumentides sätestatud tingimustel.
7.2. Hankija ei kanna vastutust pakkuja ees, kui kõigi pakkumuste tagasilükkamine on
toimunud käesolevas dokumendis sätestatud tingimustel.
8. NÕUDED PAKKUJA MEESK ONNALE
8.1. Pakkuja meeskonnas peavad olema esindatud vähemalt järgnevad rollid:
8.1.1. IT-arhitekt (andmearhitekt)
8.1.2. IT-arhitekt (teenusplatvormi arhitekt)
Andmearhitekti rolli täitev meeskonnaliige peab olema osalenud viimase 5 aasta
jooksul vähemalt ühes (1) suuremahulises projektis (projekti kogumaksumus
vähemalt 100 000 eurot), mis on tegelenud suuremahulistest heterogeensetest
andmekogudest pärineva andmestiku kaardistamise, koondamise ja andmemudelite
koostamisega. Ta peab omama kogemust erineva üldistustasemega (sh semantilist
aspekti arvestavate) andmemudelite väljatöötamises.
Teenusplatvormi arhitekti rolli täitev meeskonnaliige peab olema osalenud viimase
5 aasta jooksul vähemalt ühes (1) suuremahulises projektis (projekti kogumaksumus
vähemalt 100 000 eurot), mis on tegelenud e-teenuste kaardistamisega ning
erinevate infosüsteemide, andmebaaside ning e-teenuste liidestamisega
teenuspõhise arhitektuuriga integratsiooniplatvormidele.
8.2. Pakkuja nimetab oma meeskonnas ühe liikme projektijuhiks. Muus osas on Pakkujal
meeskonna komplekteerimisel vabad käed. Meeskonna liikmed ja nende
kogemus/CV tuleb lisada Pakkumusele ette nähtud korras.
8.3. Pakkumuses loetletud spetsialistide vahetamine on lubatud vaid Hankija/Tellija
eelneval kirjalikul loal. Kui pakkumuses nimetatud spetsialist vahetatakse teise
spetsialisti vastu, siis peab see olema vähemalt samaväärse kvalifikatsiooniga
spetsialist.
8.4. Pakkujal on õigus tööde tegemise käigus kaasata täiendavaid eksperte. Pakkuja peab
Hankijat/Tellijat informeerima kaasatud täiendavast eksperdist.
9. PAKKUMUSTE VASTAVUSE KONTROLLIMINE
9.1. Hankija kontrollib pakkumuse vastavust RHS §-s 114 sätestatud korras.
9.2. Pakkumus peab vastama kõikidele riigihanke alusdokumentides esitatud
tingimustele ja sisaldama käesoleva dokumendi punktides 5 ja 6 nõutud
informatsiooni.
9.3. Hankija lükkab pakkumuse tagasi, kui see ei vasta riigihanke alusdokumentides
esitatud tingimustele.
9.4. Hankija võib tunnistada pakkumuse vastavaks, kui selles ei esine sisulisi
kõrvalekaldeid riigihanke alusdokumentides esitatud tingimustest.
10. PAKKUMUSTE HINDAMINE JA HINDAMISKRITEERIU MID
10.1. Majanduslikult soodsaima pakkumuse väljaselgitamisel ei arvestata olelusringi
kulusid, sest riigihanke objektiks olevad tööd ei tekita kulusid kolmandatele isikutele,
kasutamisjärgseid kulusid ega keskkonnaalaste välismõjudega seonduvaid
kindlaksmääratavaid ja rahaliselt mõõdetavaid kulusid.
10.2. Edukaks pakkumuseks tunnistatakse pakkumus, mille punktide summa on suurim.
Hindamistäpsus on kaks kohta pärast koma.
10.3. Hankekomisjoni hindamiskriteeriumitele antud punktid summeeritakse.
Hankekomisjon annab punkte ühiselt, konsensuse alusel. Konsensuse
mittesaavutamisel võetakse vaidlusaluses küsimuses komisjoni liikmete hinnete
aritmeetiline keskmine.
10.4. Pakkumuse sisukriteeriumite (10.7.1, 10.7.2. ning 10.7.3)) ja maksumuse (10.7.4)
eest antud punktid summeeritakse.
10.5. Võrdse arvu punkte kogunud pakkumuste puhul tunnistatakse edukaks pakkumus,
mis sai rohkem sisupunkte. Kui ka siis esineb pakkumustel võrdsel arvul punkte,
otsustatakse võitja liisu heitmise teel.
10.6. Edukaks ei tunnistata pakkumust, mis sai vähemalt ühe hindamiskriteeriumi eest 0
punkti.
10.7. Pakkumuste hindamisel selgitatakse majanduslikult soodsaim pakkumus välja
hindamiskriteeriumite alusel:
10.7.1. I hindamiskriteerium - meetodi valik ja tulemite saavutamise kava (kuni 30
punkti, alamkriteeriumite kaal on võrdne, punktid summeeritakse);
10.7.2. II hindamiskriteerium - tulemite ja Tellija vajaduste mõistmine (kuni 30
punkti, alamkriteeriumite kaal on võrdne, punktid summeeritakse);
10.7.3. III hindamiskriteerium - riskide maandamine (kuni 10 punkti,
alamkriteeriumide kaal on võrdne, alamkriteeriumite kaal on võrdne,
punktid summeeritakse);;
10.7.4. IV hindamiskriteerium - pakkumuse maksumus (kuni 30 punkti).
11.7.1 Meetodi valik ja tulemuste saavutamise kava (kuni 30 punkti).
Suurepärane Hea Rahuldav Ebapiisav
30 punkti 25 punkti 15 punkti 0 punkti
Meetod Eesmärgipärane, Eesmärgipärane, Üldiselt
selgelt ja arusaadavalt põhjendatus ei ole eesmärgipärane,
põhjendatud väga selge nõrgalt põhjendatud
Tegevused Loendatud tegevused Loendatud tegevused Loendatud tegevused
on teostatavad, on piisavad töö on üldjoontes
piisavad ja tarvilikud teostamiseks. 1-2 piisavad töö
töö teostamiseks, tegevuse kirjeldus on teostamiseks.
piisavalt kirjeldatud ebaselge või
ning põhjendatud. teostatavus või
tarvilikkus tekitab
üksikuid küsimusi.
Tegevuste Loogiliselt järjestatud, Loogiliselt järjestatud Põhimõtteliselt töö
Ebapiisav
järjekord selgelt ja arusaadavalt ja tööde tähtaegset teostamist
„Rahuldava“
põhjendatud, tööde teostamist võimaldav, kuid
tulemuse
tähtajalist teostamist võimaldav, kuid tööde järjestuses või
saavutamiseks
võimaldav, optimaalne. tööde järjestuse või ajakavas on mitmeid
ajakava suhtes on (rohkem kui 2)
mõningaid (kuni 2) küsitavusi
küsitavusi
Meeskond Kogemus (osalenud Kogemus (osalenud Kogemus (osalenud
vähemalt 5-s sarnases vähemalt 3-s vähemalt 2-s
projektis) ja suurus sarnases projektis) ja sarnases projektis) ja
toetab suurepärase suurus toetab suurus toetab
tulemuse saavutamist tulemuse tulemuse
saavutamist saavutamist
Vormistus Piisavalt detailne, Piisavalt detailne, Detailne, kuid
lakooniline, visuaalselt visuaalselt haaratav raskesti haaratav
kergesti haaratav
11.7.2. Tulemused ja Tellija vajaduste mõistmine (kuni 30 punkti).
Suurepärane Hea Rahuldav Ebapiisav
30 punkti 25 punkti 15 punkti 0 punkti
Tulemuste Näitab Tellija vajaduste Näitab Tellija Näitab Tellija
kirjeldus mõistmist ja kaasa vajaduste vajaduste osalist
mõtlemist (lisatud ka mõistmist mõistmist
omapoolsed ettepanekud) kooskõlas hanke kooskõlas hanke
kooskõlas hanke eseme objekti tehnilise objekti tehnilise
tehnilise kirjeldusega (vt kirjeldusega. kirjeldusega. Ebapiisav
HD Lisa 1 – Tehniline „Rahuldava“
kirjeldus). tulemuse
saavutamiseks
Tulemuste Eesmärgile suurepäraselt Eesmärgile hästi Eesmärgile vastav
formaadi vastav, detailselt vastav, selge ja ja kasutatav, kuid
kirjeldus kirjeldatud, selge ja hästi hästi kasutatav. võiks olla oluliselt
kasutatav Võiks olla mõnes detailsem või
aspektis detailsem
või selgemini selgemini
kirjeldatud. kirjeldatud
Vormistus Piisavalt detailne, Piisavalt detailne, Detailne, kuid
lakooniline, visuaalselt visuaalselt haaratav raskesti haaratav
kergesti haaratav
11.7.3. Riskide maandamine (kuni 10 punkti).
Suurepärane Hea Rahuldav Ebapiisav
10 punkti 7 punkti 4 punkti 0 punkti
Riskide Loetletud vaid kõik Loetletud kõik Enamik olulisi riske
loetelu olulised riskid olulised riskid, kuid loetletud
on esitatud ka
ebaolulisi
Riskide mõju Kõik hinnangud on Hinnangud Hinnangud on
ja tõenäosus põhjendatult realistlikud ja realistlikud ja antud, kuid nende
hinnatud mõistetavad mõistetavad, võib realistlikkuses või
esineda üksikuid mõistetavuses on Ebapiisav
küsitavusi. küsitavusi „Rahuldava“
tulemuse
Maandamise Maandamise meetodid Maandamise Maandamise saavutamiseks
meetodid hästi põhjendatud, meetodid hästi meetodid üldiselt
proportsionaalsed riski põhjendatud ja kirjeldatud ja
esinemise tõenäosusele ja Pakkuja poolt põhjendatud.
Pakkuja poolt reaalselt reaalselt
kasutatavad. kasutatavad.
Vormistus Piisavalt detailne, Piisavalt detailne Üldine
lakooniline
11.7.4.Pakkumise maksumus (kuni 30 punkti).
Pakkumuse maksumuse väärtuspunktide määramisel saavutab maksimaalsed
väärtuspunktid kõige odavama pakkumuse maksumus.
Väärtuspunktid arvutatakse järgmise valemi kohaselt: “punktimäär” = “kõige
odavam pakkumuse maksumus” / “hinnatava pakkumuse maksumus” × 30.
Arvutuste tulemused ümardatakse kahe komakoha täpsusega.
11. HANKELEPINGU TINGIMU SED
11.1. Pakkujaga sõlmitava lepingu projekt on hankedokumendi HD lisa 2.
LISAD
HD Lisa 1 – Tehniline kirjeldus
HD Lisa 2 – Hankelepingu eritingimuste projekt
HD Lisa 3 – Eksperdi ja projektijuhi CV-vorm
HD Lisa 4 – Ärisaladuse teabe esitamise vorm
HD Lisa 5 – Töö üleandmise ja vastuvõtmise akti vorm
Lepingu Lisa 1 „Töö üleandmise-vastuvõtmise akt“ (vorm)
Majandus- ja Kommunikatsiooniministeeriumi
ja XXX vahel sõlmitud
Lepingu nr XXX juurde
Töö üleandmise-vastuvõtmise akt
Käesolev Töö üleandmise-vastuvõtmise akt (edaspidi akt) on koostatud XXX (edaspidi: Täitja) … poolt
ja esitatud Majandus- ja Kommunikatsiooniministeeriumi digitaalehituse valdkonna juhile Jaan Saar
(edaspidi: Tellija), tõendamaks, et Täitja andis üle Poolte vahel XXX sõlmitud Lepingu „BIM-põhise
ehitusloa menetluse tarkvaralahenduse integreerimine EHR menetluskeskkonda” nr XXX alusel
osutatud Töö alljärgnevalt:
1. … (üleantava Töö nimetus, detailne kirjeldus (kas on lõpparuanne või vahearuanne ning
mida üleantav Töö hõlmab), ajavahemik, maht, täidetud tingimused, vajadusel viited
Lepingu punktidele vms).
2. Tellija on Töö osutamise tulemustega tutvunud ning kiidab Töö osutamise tulemused
heaks, millega ühtlasi loetakse Täitja poolt üle antud Töö vastuvõetuks.
Akt on aluseks Täitja poolt Tellijale kooskõlas Lepingu eritingimuste punktiga 3. ja üldtingimuste
punktiga 2.4 ja 2.5. arve esitamiseks summas … (summa sõnades) eurot.
Akt omab digitaalselt allkirjastatuna juriidilist jõudu ning edastatakse elektrooniliselt mõlemale
Poolele.
Täitja Tellija
/allkirjastatud digitaalselt/ /allkirjastatud digitaalselt/