Särmä arkisto integraatio - espoon-voltti/evaka GitHub Wiki

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:

  • Prosessitunnus (processDefinitionNumber)
  • Arkistointiaika kuukausissa (archiveDurationMonths)
  • Asiakirja arkistoitavissa ulkoiseen arkistoon (archiveExternally)

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

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

Arkistointipainikkeen kautta asiakirja merkitään arkistoitavaksi, minkä jälkeen arkistointi tapahtuu asynkronisesti taustaprosessina.

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- ja salassapitosää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
  • Asiakirjan tyyppi ja kieli
  • Lapsen nimi, henkilötunnus ja syntymäaika
  • Asiakirjan salassapitosäännöt ja -aika: Poimitaan lomakepohjan 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

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.

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:sesta
  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.