Särmä arkisto integraatio

Yleiskuvaus

eVaka-järjestelmä voidaan asettaa arkistoimaan lapsen asiakirjoja Espoon Särmä-arkistoon. Ulkoiseen arkistoon siirrettäviä lapsen asiakirjoja ovat lomakepohjista täytetyt pedagogiset asiakirjat: Vasu (Varhaiskasvatussuunnitelma), Leops (Lapsen esiopetuksen oppimissuunnitelma), ja Hojks (Henkilökohtaisen opetuksen järjestämistä koskeva suunnitelma) sekä pedagoginen arvio ja selvitys. Arkistoon vienti tapahtuu asynkronisesti taustapalvelun kautta. Arkistoitavat asiakirjat ovat PDF-muodossa ja niiden mukana lähetetään metadata XML-muodossa.

Arkistointi käyttöliittymässä

Asiakirjan ulkoiseen arkistointiin voi vaikuttaa dokumenttipohjan luonnin ja muokkauksen yhteydessä. Dokumenttipohjaan voidaan asettaa seuraavat arkistointiin vaikuttavat kentät:

• Siirrettävä ulkoiseen arkistoon ennen poistoa (archiveExternally)
• Asiakirjan tyyppi. Tästä johdetaan Särmään tallannettava asiakirjan tyyppi ja säilytyssääntö
• Prosessitunnus (processDefinitionNumber)
• Arkistointiaika kuukausissa (archiveDurationMonths)
• Salassapitosäännöt

Kun lomakepohja on luotu "Siirrettävä ulkoiseen arkistoon ennen poistoa" -asetuksella, sillä luodut asiakirjat arkistoidaan Särmä-arkistoon ennen niiden poistamista järjestelmästä. Asiakirjojen poistamistoimintoa ei ole vielä toteutettu.

Työntekijäkäyttöliittymässä arkistointitoiminto näkyy asiakirjan lukutilassa "Arkistoi"-painikkeena, kun:

1. Front-endin feature flag archiveIntegrationEnabled on asetettu käyttöön
2. Käyttäjällä on oikeus arkistoida kyseinen asiakirja (ARCHIVE-oikeus)
3. Asiakirjaa ei ole jo arkistoitu
4. Asiakirja on merkattu ulkoisesti arkistoitavaksi "Siirrettävä ulkoiseen arkistoon ennen poistoa"

Arkistointipainikkeen kautta asiakirja merkitään arkistoitavaksi, minkä jälkeen arkistointi tapahtuu asynkronisesti taustaprosessina. Kun asiakirja on onnistuneesti arkistoitu, "Arkistoi"-painikkeen yhteydessä näytetään arkistoonvientiaika. Jos arkistointi epäonnistuu, virheen yksityiskohdat löytyvät eVaka servicen logeilta.

Java-luokkien generointi Särmä-skeemasta

Särmä-arkiston XML-skeemat (XSD) sijaitsevat sarmamodel-moduulissa. Näistä skeemoista generoidaan Java-luokat käyttämällä JAXB (Java Architecture for XML Binding) teknologiaa. Luokkien generointi on määritelty moduulin build.gradle.kts-tiedostossa.

Generointiprosessi toimii seuraavasti:

1. Projektin käännöksen yhteydessä suoritetaan generateJaxb-tehtävä, joka on määritelty riippuvaiseksi Java-luokkien käännöksestä.
2. Tehtävä käyttää xjc-työkalua (XML-to-Java Compiler), joka tuottaa Java-luokat XSD-skeematiedostoista.
3. Generoitavat luokat sijoitetaan hakemistoon build/generated/sources/java/main ja ne kuuluvat paketiin fi.espoo.evaka.sarma.model.
4. Generoidut luokat sisältävät tarvittavat JAXB-annotaatiot XML-tiedostojen serialisointia varten.

Tämä JAXB-generointi mahdollistaa sen, että Evaka-järjestelmässä voidaan käsitellä Särmän vaatimia XML-rakenteita ohjelmallisesti käyttämällä Java-luokkia. Tämä varmistaa, että luodut XML-dokumentit noudattavat Särmän vaatimaa skeemaa.

Metadata XML

Särmä-järjestelmään lähetettävä metadata noudattaa Särmä-arkiston määrittämää XML-skeemaa. Metadatan muodostus tapahtuu osana arkistointiprosessia.

Metatietojen päärakenne on seuraava:

• RecordMetadataInstance
  • StandardMetadata
    • MetadataMasterVersion
    • VirtualArchiveId
    • RecordIdentifiers
    • DocumentDescription (sisältää asiakirjan ja lapsen perustiedot)
    • Format (tiedostomuoto, PDF)
    • Creation (asiakirjan luontitiedot)
    • Policies (säilytys-, salassapito-, turvallisuus- ja suojelusäännöt)
    • CaseFile (prosessitiedot)

Metatiedot sisältävät mm. seuraavat tiedot:

• Asiakirjan yksilöivät tunnisteet: uniikki tehtävänumero ja eVakan sisäinen asiakirjan UUID
• Tehtäväluokitustunnus: poimitaan lomakepohjan tiedoista
• Asiakirjan tyyppi ja kieli
• Lapsen nimi, henkilötunnus ja syntymäaika
• Asiakirjan salassapitosäännöt ja -aika: poimitaan lomakepohjalle kirjatuista tiedoista
• Asiakirjan luonti- ja valmistumisaika: poimitaan asiakirjan created aikaleimasta sekä prosessihistorian valmistumismerkinnästä. Mikäli valmistumismerkintää ei löydy, poimitaan joko lomakepohjan viimeinen voimassaolopäivä tai ensimmäinen 31.7. päivämäärä joka on created aikaleman jälkeen.
• Prosessitunnus: Poimitaan lomakepohjan tiedoista
• Asiakirjan käsittelijät: Poimitaan tilahistoriasta
• Säilytyssääntö: määräytyy asiakirjan tyypin mukaan
• Turvallisuussääntö ja suojeluluokka: kiinteät arvot

Metadatan XML-muuntamiseen käytetään JAXB työkaluja: marshalMetadata-funktio käyttää JAXBContextia muuttamaan Java-objektit XML-muotoon. Tässä hyödynnetään sarmamodel-moduulissa generoituja luokkia, kuten RecordMetadataInstance, StandardMetadataType, PolicyConfiguration, jne.

Asiakirjan tyypin ja säilytyssäännön valinta asiakirjatyypeittäin

Arkistoon vietävän asiakirjan tyyppi ja säilytyssääntö määräytyy lomakepohjan tyypin perusteella ChildDocumentType.

• Asiakirjan tyyppi (asiakirjatyyppi documentType / asiakirjatyypin tarkenne documentTypeSpecifier):

  • VASU, MIGRATED_VASU: "Suunnitelma" / "Varhaiskasvatussuunnitelma"
  • LEOPS, MIGRATED_LEOPS: "Suunnitelma" / "Lapsen esiopetuksen oppimissuunnitelma LEOPS"
  • HOJKS: "Suunnitelma" / "Henkilökohtaisen opetuksen järjestämistä koskeva suunnitelma HOJKS"
  • PEDAGOGICAL_ASSESSMENT: "Arvio" / "Pedagoginen arvio"
  • PEDAGOGICAL_REPORT: "Selvitys" / "Pedagoginen selvitys"

• Säilytyssääntö RetentionPolicy:

  • PEDAGOGICAL_ASSESSMENT, PEDAGOGICAL_REPORT: säilytysaika 28 vuotta lapsen syntymästä, trigger "YearsFromCustomerBirthDate", säilytysajan peruste annotation "Perusopetuslaki (628/1998) 16 a §"
  • Muut asiakirjatyypit: säilytysaika "InPerpetuity", säilytysajan peruste annotation "KA/13089/07.01.01.03.01/2018"

Arkistointiprosessi

Kun valmis asiakirja merkitään ulkoiseen arkistoon vietäväksi, järjestelmä luo asynkronisen tehtävän (AsyncJob.ArchiveChildDocument), joka hoitaa asiakirjan arkistoinnin Särmä-järjestelmään. Arkistointiprosessi sisältää seuraavat vaiheet:

1. Haetaan asiakirjan tiedot tietokannasta
2. Tarkistetaan, että asiakirja on arkistoitavissa (template.archiveExternally = true)
3. Haetaan asiakirjaan liittyvät metatiedot ja lapsen tiedot
4. Haetaan asiakirjan PDF-tiedosto S3:sta
5. Muodostetaan XML-muotoinen metatieto
6. Lähetetään asiakirja ja metatieto Särmä-järjestelmään
7. Merkitään asiakirja arkistoiduksi asettamalla aikaleima tietokannan child_document.archived_at -kenttään, mikäli arkistointi onnistui

Särmä API -kutsut

Integraatio käyttää Särmä-järjestelmän HTTP API:a asiakirjojen arkistointiin. API-kutsu tehdään SärmäHttpClient-luokan kautta.

HTTP POST-kutsu (operation_id PUT)

Asiakirjan arkistointiin käytetään HTTP POST-metodia, joka lähetetään multipart/form-data -muodossa seuraavilla parametreilla:

• protocol_version: "1.0"
• operation_id: "PUT"
• response_format: "URL-ENCODED"
• user_id: Käyttäjätunnus (konfiguraatiosta)
• user_role: Käyttäjärooli (konfiguraatiosta)
• nr_of_instances: "1"
• instance_1_md_model_id: "standard"
• instance_1_md_model_version: "1.0"
• instance_1_md_master_id: Master ID (yleensä "yleinen")
• instance_1_md_master_version: "1.0"
• instance_1_class_id: Luokkatunnus (esim. "12.06.01.SL1.RT34")
• instance_1_virtual_archive_id: Virtuaaliarkiston tunnus (esim. "YLEINEN")
• instance_1_record_payload_location: "SELF_CONTAINED"
• instance_1_md_instance: XML-muotoinen metatieto
• instance_1_record_payload_content_size: Tiedoston koko tavuina
• instance_1_record_payload_data: PDF-tiedoston sisältö

Vastauksen käsittely

Särmä API palauttaa vastauksen URL-encoded muodossa, joka sisältää kentät:

• status_code: Tilakoodi (200 = onnistunut)
• status_message: Tilailmoitus
• transaction_id: Tapahtuman tunniste
• instance_ids: Arkistoidun asiakirjan tunniste Särmä-järjestelmässä

Vastauksen käsittelyssä tarkistetaan tilakoodi ja poimitaan instance_id lokitusta varten. Jos tilakoodi on 200, asiakirja merkitään arkistoiduksi tietokantaan.

Konfigurointi

Särmä-integraatio otetaan käyttöön eVaka servicen ympäristömuuttujalla:

Ympäristömuuttuja	Kuvaus
evaka.särmä_enabled	Onko Särmä-integraatio käytössä (true/false)

Särmä-integraatio konfiguroidaan seuraavien ympäristömuuttujien avulla:

Ympäristömuuttuja	Kuvaus	Pakollinen
evaka.integration.sarma.url	Särmä-palvelun URL-osoite	Kyllä
evaka.integration.sarma.use_mock_client	Käytetäänkö mock-toteutusta (true/false)	Ei (oletusarvo: false)
evaka.integration.sarma.user_id	Käyttäjätunnus Särmä-palveluun	Kyllä
evaka.integration.sarma.user_role	Käyttäjärooli Särmä-palveluun	Kyllä

Feature Flag

Frontendissä arkistointiominaisuus otetaan käyttöön asettamalla feature flag archiveIntegrationEnabled päälle. Tämä flag kontrolloi arkistointipainikkeen näkyvyyttä käyttöliittymässä.

Virhetilanteet

Arkistointiprosessissa voi tapahtua virhetilanteita monessa eri vaiheessa:

• Asiakirjaa ei löydy tietokannasta
• Asiakirja ei ole arkistoitavissa
• Asiakirjan metadatan muodostuksessa tapahtuu virhe
• Särmä-järjestelmään ei saada yhteyttä
• Särmä-järjestelmä palauttaa virheen

Virhetilanteissa arkistointiprosessi keskeytyy ja virhe lokitetaan. Arkistointia voidaan yrittää myöhemmin uudelleen. Kun arkistointiprosessi myöhemmin automatisoidaan ScheduledTask pohjaiseksi, se käynnistää AsyncJobit niin, että niissä on määritelty retryCount-parametri, jolloin arkistoon viemistä koitetaan uudestaan.

Toteutuksen yksityiskohdat

• Arkistointiprosessi on toteutettu palveluluokassa ArchiveChildDocumentService, joka rekisteröi asynkronisen handlerin AsyncJobRunneriin.
• Varsinainen arkistointilogiikka on funktiossa uploadToArchive, joka hakee tarvittavat tiedot, muodostaa metadatan ja lähettää asiakirjan Särmä-arkistoon.
• Metadatan muodostus tapahtuu createDocumentMetadata-funktiolla, joka hyödyntää useita apufunktioita mm. salassapito-, säilytys- ja turvallisuussääntöjen muodostukseen.
• Metadatan serialisointi XML:ksi tehdään marshalMetadata-funktiolla.
• Virhetilanteissa prosessi keskeytyy ja virheestä heitetään poikkeus sekä kirjataan lokiin.
• Onnistuneen arkistoinnin jälkeen asiakirja merkitään arkistoiduksi tietokantaan.

Lisätietoja ja skeemakuvaukset löytyvät sarmamodel-moduulista ja sen XSD-tiedostoista.