dokumendiregister.ee
OtsingAsutusedMCP
Otsing›Majandus- ja Kommunikatsiooniministeerium
KäskkiriAvalik

Käskkiri

Majandus- ja Kommunikatsiooniministeerium · 12. november 2021
Viit
90
Registreeritud
12. november 2021
Dokumendi liik
Käskkiri
Funktsioon
1.1/S Ministeeriumi juhtimine
Sari
1.1-2/S Kantsleri käskkirjad (Arhiiviväärtuslik)
Toimik
1.1-2/2021
Vastutaja
Krista Hinno (Majandus- ja Kommunikatsiooniministeerium, Kantsleri valdkond, Ehituse valdkond, Ehitus- ja elamuosakond, Ehitisregistri talitus)

Failid

  • 📎90 12.11.2021 Käskkiri.asice7465 KB

Sisu (failidest)

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/
Allikas: Majandus- ja Kommunikatsiooniministeerium dokumendiregister →
dokumendiregister.eeAsutusedEesti avalike dokumendiregistrite otsing · nimistu.ee andmetel