NSILM

PM: API: DevelopmentPlan: POST /planning-api/development-plans/{developmentPlanId}/pdf-versions

Muutja: Natalja Selivjorstova · 2025-08-07

Üldkirjeldus

Teenus võimaldab genereerida PDF-failina jagatav arengukava versioon. Versioon luuakse asutuse / ametikoha muudetava arengukava hetkeandmete põhjal ning ainult juhul, kui arengukavale on määratud periood.  

Seotud andmeobjektid:

Seotud Jira taskid

NSIL-1115 - Getting issue details... STATUS

Eeltingimused ja kasutusõigused

  • Kui tegemist on asutusepõhise arengukavaga (developmentPlanScope = INSTITUTIONAL):
    • Kasutajal peab olema seos arengukava asutusega ning tal peab olema ka selle asutuse juures arengukava lisamise ja muutmise õigus.
      • DevelopmentPlan.institution.id = kasutaja valitud rolliga seotud asutus,
      • Õigust reguleerib privileeg: HSILM_PLANNING_DEV_PLAN_MANAGE.
  • Kui tegemist on isikupõhise arengukavaga (developmentPlanScope = INDIVIDUAL):
    • Kasutaja peab olema arengukava omanik.
      • DevelopmentPlan.personalCode = kasutaja isikukood
    • Eraldi privileegi ei ole vaja - õiguse luua enda kehtiva ametikoha kohta uusi arengukava PDF-versioone annab kasutajale tema isikukood.
  • Planeerimise meeskonnaliikme rolli valinud kasutajad ei saa arengukava versioone luua.

Planeerimise mooduli kasutusrollide ja õiguste kohta saab täpsemalt infot leida lehelt Kasutusõigused ja rollid.

Sisendid

AtribuutKohustuslikkus, mitmesusTüüpVaikeväärtus, valideerimineKirjeldus, täiendav info
developmentPlanId1String
  • Peab eksisteerima, olema muudetav ning sellele peab olema määratud periood.
    • developmentPlanId = DevelopmentPlan.id, mille editable = true, startDate != NULL ja endDate != NULL

Viide arengukavale, millele uus PDF-failina jagatav versioon luuakse.

Väljundid

AtribuutKohustuslikkus, mitmesusTüüpKirjeldus, täiendav info
Samad nagu teenusel PM: API: DevelopmentPlan: POST /planning-api/development-plans/{developmentPlanId}/url-versions.

Ärireeglid

  1. PDF-ina jagatavat versiooni saab luua ainult muudetava (editable = true) arengukava põhjal.
  2. Versiooni loomisel salvestatakse kõik muudetava arengukava andmed PDF-failina vastavalt loomise hetke seisule.
    • PDF-faili ei lisata sektsioone, millel on märge "Peida dokumendis" (hidden = true), ega nende alla kuuluvaid vormielemente. 
    • PDF-faili lisatakse aktiivsed eesmärgid, mis loomise hetkel kattuvad vähemalt osaliselt arengukava perioodiga.
      • Eesmärkide valimisel võetakse arvesse järgmine reegel: 
        1. Kui mõnel tegevusel puudub startDate, loetakse selle alguskuupäevaks endDate. Sellisel juhul käsitletakse tegevust kui ühepäevast, mis toimub endDate kuupäeval. 
    • Selgitus: Arengukava andmete koopia salvestatakse andmebaasi ainult juhul, kui luuakse URL-versioon. PDF-versiooni puhul salvestatakse süsteemi üksnes loodud PDF-fail.

Tegevused

  1. Süsteem kontrollib, kas kasutajal on õigust päringut teostada.
    1. Kui kasutajal ei ole õigust, lõpetatakse päringu töötlemine ja tagastatakse http veakood.
  2. Süsteem kontrollib, kas sisendandmed vastavad nõuetele.
    1. Kui andmed ei vasta nõuetele, lõpetatakse päringu töötlemine ja tagastatakse http veakood.

  3. Süsteem kontrollib, kas sisendis esitatud arengukava (developmentPlanId) eksisteerib ja on muudetav:

    1. Otsitakse Objektid#DevelopmentPlan objekti, mille:
      1. id =  sisendis esitatud developmentPlanId väärtus
      2. editable = true
    2. Kui tingimustele vastavat arengukava ei leita, lõpetatakse päringu töötlemine ja tagastatakse http veakood.
  4. Süsteem kontrollib versiooni loomise eeltingimuste täitmist:
    1. Kontrollitakse, kas olemasolevate arengukava PDF-versioonide arv ei ületa kehtestatud piirmäära (20 versiooni): 
      1. Selleks otsitakse olemasolevaid arengukava PDF-versioone:
        1. Otsitakse Objektid#DevelopmentPlanVersion, mille:
          1. versionType = "PDF"
          2. fileId != NULL.
          3. developmentPlanId = Objektid#DevelopmentPlan.id, mille:
            1. developmentPlanScope = Objektid#DevelopmentPlan.developmentPlanScope, mille id = sisendis esitatud developmentPlanId väärtus
            2. institution.id = Objektid#DevelopmentPlan.institution.id, mille id = sisendis esitatud developmentPlanId väärtus
            3. personalCode = Objektid#DevelopmentPlan.personalCode, mille id = sisendis esitatud developmentPlanId väärtus
            4. jobsite = Objektid#DevelopmentPlan.jobsite, mille id = sisendis esitatud developmentPlanId väärtus
            5. editable = false
        2. Kui ühtegi tingimustele vastavat arengukava ei leita, jätkub protsess sammust 5 (asutusel / ametikohal ei ole ühtegi PDF-failina jagatud arengukava versiooni). 
        3. Kui leitud versioone on 20 või rohkem, lõpetatakse päringu töötlemine ja tagastatakse http veakood. (Arengukava PDF-versioonide arvu piirmäär on saavutatud.) 
  5. Süsteem loob sisendis esitatud arengukava (developmentPlanId) hetkeseisu andmetest lähtudes PDF-faili. 
    1. Kui arengukavale on lisatud logo (Objektid#DevelopmentPlan.logoFileId != NULL), laaditakse vastav fail failihoidlast alla:
      1. Otsitakse logo faili metaandmeid: 
        1. Otsitakse Objektid#File objekti, mille:
          1. id = sisendis esitatud arengukava Objektid#DevelopmentPlan.logoFileId väärtus
        2. Kui vastavat objekti ei leita, liigub süsteem sammu 5.b juurde.
      2. Leitud metaandmete alusel leitakse fail failihoidlast:
        1. Otsitakse failisüsteemist fail, mille:
          1. id = leitud Objektid#File.fileSystemId väärtus.
        2. Kui vastavat faili ei leita, liigub süsteem sammu 5.b juurde.
      3. Leitud fail laaditakse alla.
    2. Seejärel leitakse arengukava sektsioonid ja vormielemendid.
      1. Otsitakse sisendis esitatud arengukava (developmentPlanId) sektsioone:
        1. Otsitakse Objektid#DevelopmentPlanSection objekte, mille:
          1. developmentPlanId = sisendis esitatud developmentPlanId väärtus
        2. Kui ühtegi sektsiooni ei leita, jätkub protsess sammust 5.c.
      2. Leitud sektsioonid järjestatakse previousSectionId alusel. 
      3. Nimekirjast eemaldatakse sektsioonid, mille hidden = true.
        1. Iga eemaldamise järel uuendatakse sellele sektsioonile järgneva sektsiooni previousSectionId väärtus. 
      4. Iga järelejäänud Objektid#DevelopmentPlanSection objekti puhul:
        1. Otsitakse sektsiooni vormielemente:
          1. Otsitakse Objektid#DevelopmentPlanElement objekte, mille:
            1. developmentPlanSectionId = töödeldava sektsiooni ID (Objektid#DevelopmentPlanSection.id). 
            2. Kui ühtegi elementi ei leita, jätkub protsess sammust 5.c.
          2. Iga leitud Objektid#DevelopmentPlanElement objekti puhul:
            1.  Kui Objektid#DevelopmentPlanElement.inputType = IMAGE, laaditakse alla sellega seotud fail failihoidlast:
              1. Otsitakse pildi faili metaandmeid: 
                1. Otsitakse Objektid#File objekti, mille:
                  1. id = töödeldava vormielemendiga seotud faili ID (Objektid#DevelopmentPlanElement.file.id).
                2. Kui vastavat objekti ei leita, jätkub protsess sammust 5.b.v.
              2. Leitud metaandmete alusel leitakse fail failihoidlast:
                1. Otsitakse failisüsteemist fail, mille:
                  1. id = leitud Objektid#File.fileSystemId väärtus
                2. Kui vastavat faili ei leita, jätkub protsess sammust 5.b.v.
              3. Leitud fail laaditakse alla. 
            2. Kui Objektid#DevelopmentPlanElement.inputType = REPORT, luuakse pildid kõigist vormielemendiga seotud PBI-aruannetest.
              1.  Iga report.selectedReports puhul:
                1. Leitakse seotud PBI aruanne järgmiste parameetrite alusel:
                  1. Objektid#DevelopmentPlanElement.report.selectedReports.workspaceId
                  2. Objektid#DevelopmentPlanElement.report.selectedReports.reportId
                  3. Objektid#DevelopmentPlanElement.report.selectedReports.bookmark
                2. Leitud aruandest tehakse pilt. 
                3. Loodud pilt laaditakse alla. 
              2. Süsteem kordab neid tegevusi, kuni kõigist töödeldava vormielemendiga seotud PBI aruannetest on pildid loodud ja alla laetud. 
          3. Süsteem kordab neid tegevusi seni, kuni kõik töödeldava sektsiooni vormielementide andmed on leitud ja nendega soetud pildid on alla laetud. 
      5. Süsteem kordab neid tegevusi, kuni kõigi sektsioonide ja nendega seotud vormielementide andmed on leitud.
    3. Leitakse arengukava perioodile vastavad aktiivsed eesmärgid.
      1. Otsitakse kõik Objektid#Goal objektid, mille:
        1. goalScope = sisendis esitatud arengukava Objektid#DevelopmentPlan.developmentPlanScope väärtus
        2. institution.id = sisendis esitatud arengukava Objektid#DevelopmentPlan.institution.id väärtus
        3. personalCode = sisendis esitatud arengukava Objektid#DevelopmentPlan.personalCode väärtus
        4. jobsite = sisendis esitatud arengukava Objektid#DevelopmentPlan.jobsite väärtus
        5. archived = false
      2. Kui eesmärke ei leita, jätkub protsess sammust 6.
      3. Leitud eesmärgid järjestatakse previousGoalId alusel. 
      4. Nimekirjast eemaldatakse pooleliolevad eesmärgid.
        1. Iga eesmärgi puhul kontrollitakse, kas:
          1. Objektid#Goal.name != NULL
          2. Objektid#Goal.description != NULL
          3. Eesmärgil on vähemalt üks seotud tegevus:
            1. Leidub vähemalt üks Objektid#GoalActivity objekt, mille goalId = töödeldava eesmärgi ID.
        2. Kui mõni tingimus ei ole täidetud, eemaldatakse eesmärk nimekirjast.
        3. Süsteem kordab neid tegevusi, kuni kõik eesmärgid on töödeldud. 
      5. Järgmisena eemaldatakse nimekirjast eesmärgid, mille tegevuste periood ei kattu arengukava perioodiga vähemalt osaliselt.
        1. Iga eesmärgi puhul kontrollitakse:
          1. Kas eesmärgi perioodi alguskuupäev (st varaseima seotud tegevuse startDate) ei ole hilisem kui arengukava lõpukuupäev (endDate):  
            1. Otsitakse Objektid#GoalActivity objekte, mille:
              1. goalId = töödeldava eesmärgi ID (Objektid#Goal.id)
            2. Leitud tegevuste puhul kontrollitakse, kas leidub selline, mille:
              1. startDate (kui mõne tegevuse startDate = NULL, siis kasutatakse selle endDate väärtust):
                1. on kõige varasem kõigi selle eesmärgiga seotud tegevuste seas, ja
                2. ei ole hilisem kui arengukava Objektid#DevelopmentPlan.endDate.
            3. Kui tingimus ei ole täidetud:
              1. Eesmärk eemaldatakse nimekirjast.
              2. Uuendatakse eemaldatud eesmärgile järgneva eesmärgi previousGoalId väärtus. 
              3. Liigutakse järgmise eesmärgi juurde.
          2. Kas eesmärgi perioodi lõpukuupäev (st hiliseima seotud tegevuse endDate) ei ole varasem kui arengukava alguskuupäev (startDate):  
            1. Kontrollitakse, kas eelnevalt leitud Objektid#GoalActivity objektide hulgas on selline, mille:
              1. endDate:
                1. on kõige hilisem kõigi selle eesmärgiga seotud tegevuste seas, ja
                2. ei ole varasem kui arengukava Objektid#DevelopmentPlan.startDate.
            2. Kui tingimus ei ole täidetud:
              1. Eesmärk eemaldatakse nimekirjast.
              2. Uuendatakse eemaldatud eesmärgile järgneva eesmärgi previousGoalId väärtus.  
              3. Liigutakse järgmise eesmärgi juurde.
          3. Süsteem kordab neid samme, kuni kõigi eesmärkide vastavus tingimustele on valideeritud. 
      6.  Järelejäänud Objektid#Goal objekti kohta otsitakse seotud mõõdikuid ja tegevusi:
        1. Otsitakse kõiki Objektid#GoalMetrics objekte, mille goalId = töödeldava eesmärgi ID.
        2. Otsitakse kõiki Objektid#GoalActivity objekte, mille goalId = töödeldava eesmärgi ID.
    4. Kogutud andmete põhjal genereeritakse PDF-fail vastavalt dokumendi PM: UC: Arengukava PDF-i genereerimine peatükis "Andmed" toodud kirjeldusele.
    5. Kui PDF-fail luuakse edukalt, siis: 
      1. See salvestatakse failisüsteemi.
      2. Salvestatakse PDF-faili metaandmed:
        1. Süsteem loob Objektid#File objekti järgmiste andmetega:
          1. id = UUID
          2. fileSystemId = Faili asukoha andmestik failisüsteemis 
          3. fileName = Faili nimetus koos faililaiendiga. Nimetus määratakse järgmiselt:
            1. Kui sisendis esitatud arengukava Objektid#DevelopmentPlan.developmentPlanScope = "INSTITUTIONAL", siis faili nimetuseks määratakse: "Asutuse nimi" + faili genereerimise aeg sekundi täpsusega.
              1. Asutuse nimi =  sisendis esitatud arengukava Objektid#DevelopmentPlan.institution.name väärtus
              2. Näide: Leiutajate külakool_2025-07-09T14-22-57.pdf
            2. Kui sisendis esitatud arengukava Objektid#DevelopmentPlan.developmentPlanScope = "INDIVIDUAL", siis faili nimetuseks määratakse "Isiku nimi ja ametikoht koos asutuse nimega" + faili genereerimise aeg sekundi täpsusega.
              1. Isiku nimi =  kasutaja ees- ja perenimi
              2. Ametikoht = sisendis esitatud arengukava Objektid#DevelopmentPlan.jobsite väärtus
              3. Asutuse nimi =  sisendis esitatud arengukava Objektid#DevelopmentPlan.institution.name väärtus
              4. Näide: Mari Maasikas_Direktor_Leiutajate külakool_2025-07-09T14-22-57.pdf
          4. mimeType = Faili mime tüüp (nt. "application/pdf")
          5. size = Faili suurus baitides
          6. audit (loomine) = audit (loomine)
  6. Versiooni genereerinud kasutajale määratakse profiilivärv järgmise loogika alusel:
    1. Süsteem kontrollib, kas päringu käivitanud kasutajal on meeskonnaliikme kirje arengukava asutuse / ametikoha piires. 
      1. Otsitakse Objektid#GoalTeamMember objekte, mille:
        1. personalCode = päringu käivitanud kasutaja isikukood
      2. Kui sobivat meeskonnaliikme kirjet ei leita, liigub süsteem edasi sammu 6.b juurde.
      3. Kui leitakse sobiv meeskonnaliikme kirje, otsitakse Objektid#Goal objekte, mille:
        1. goalScope = sisendis esitatud arengukava Objektid#DevelopmentPlan.developmentPlanScope väärtus
        2. institution.id = sisendis esitatud arengukava Objektid#DevelopmentPlan.institution.id väärtus
        3. personalCode = sisendis esitatud arengukava Objektid#DevelopmentPlan.personalCode väärtus
        4. jobsite = sisendis esitatud arengukava Objektid#DevelopmentPlan.jobsite väärtus
        5. teamMembers.id = üks eelnevalt leitud Objektid#GoalTeamMember.id väärtustest
      4. Kui leitakse vähemalt üks sobiv eesmärk, määratakse kasutajale sama profiilivärv, mis on meeskonnliikmel, kelle ID-ga see eesmärk seotud on. 
    2. Kui meeskonnaliikme kirjet ei leita:
      1. Süsteem kontrollib, kas kasutajaga on seotud mõni varem loodud arengukava versioon. 
        1. Süsteem otsib Objektid#DevelopmentPlanVersion objekte, mille:
          1. generator.personalCode = kasutaja isikukood
        2. Kui leitakse sobiv versioon, määratakse kasutajale sama profiilivärv, mis selle versiooni genereerijal.
          1. Kasutaja profiilivärv = leitud versiooni Objektid#DevelopmentPlanVersion.generator.profileColor väärtus 
      2. Kui varasemat versiooni ei leita, valitakse kasutaja profiilivärviks üks HS visualiseerimise põhimõtete primaarse värvipaletti hulgast.
        1. Värvi määramise loogika: 
          1. Eelistatult määratakse kasutajale värv, mida ei ole veel kasutatud ühegi teise sama asutuse/ametikoha eesmärkide meeskonnaliikme ega arengukava versioone genereerija puhul. 
          2. Kui kõik unikaalsed värvid on juba kasutuses, siis valitakse värv, mida on kasutatud kõige vähem sama asutuse/ametikoha eesmärkide ja arengukavade raames.
          3. Kasutatavad värvid:
            • #14AAAD - teal
            • #468CDF - sinine
            • #9467BD - lilla
            • #E377C2 - roosa
            • #FF7F0E - oranž
            • #E6BC05 - kollane
            • #2CA02C - roheline
            • #7F7F7F - hall
            • #8C564B - pruun
            • #D62728 - punane
            • #B44FB0 - soe lilla
            • #1F77B4 - soe sinine
            • #BCBD22 - soe roheline
            • #D17805 - ooker
  7. Süsteem loob uue arengukava versiooni:
    1. Luuakse uus Objektid#DevelopmentPlanVersion objekt järgmiste väärtustega:  
      1. id = UUID
      2. developmentPlanId = NULL
      3. institution.id = sisendis esitatud arengukava Objektid#DevelopmentPlan.institution.id väärtus
      4. institution.regCode = sisendis esitatud arengukava Objektid#DevelopmentPlan.institution.regCode väärtus
      5. personalCode = sisendis esitatud arengukava Objektid#DevelopmentPlan.personalCode väärtus
      6. jobsite = sisendis esitatud arengukava Objektid#DevelopmentPlan.jobsite väärtus
      7. versionType = "PDF"
      8. urlPublic = NULL
      9. publicUrlAlias = NULL
      10. fileId = loodud PDF-faili metaandmete kirje ID (Objektid#File.id)
      11. generator.personalCode = kasutaja isikukood
      12. generator.firstName = kasutaja eesnimi
      13. generator.lastName = kasutaja perenimi
      14. generator.profileColor = eelmises sammus kasutajale määratud profiilivärv
      15. validFrom = jooksev kuupäeva ja kellaaeg
  8. Süsteem tagastab loodud arengukava versiooni andmed.