Indholdsfortegnelse
Monitoreringssnitflade
Importeren udstiller en enkelt monitoreringssnitflade, som returnerer en simpel plan tekst side. Siden kan findes her:
http://localhost/sor2importer/status
Status siden returnerer to linier der fortæller om importerens status. Første linie har hvilken tilstand importeren er i. For eksempel om den er ok, om den kører på nuværende tidspunkt, eller om den er låst og hvad årsagen er. Anden linie er status for sidste import. Imellem hvilket tidsrum den kørte, hvor lang tid at det tog, og hvad resultatet var af den import. Ud over disse linier, så returneres også HTTP status kode 200 hvis importeren er ok, eller 500 hvis noget er galt.
Et eksempel på indholdet af status siden, lige efter at importeren er startet op:
OK Last import: Never run
Et eksempel på indholdet af status siden, når importeren har fejlet:
Inbox is locked: Inbox[/pack/wildfly8/standalone/data/sdm4/sor2importer] Last import started at: 2018-12-14T11:09:49.000+01:00 and ended at: 2018-12-14T11:11:00.000+01:00. Processing took 71 seconds. Outcome was FAILURE
Modus operandi
Når importeren bliver sat i gang med at køre, så kigger den på alle filer som ligger tilgængelige. Importeren vil processere filerne i rækkefølge sorteret efter navn.
Navngivningen af filerne, har betydning for funktionaliteten i importeren.
- Filens navn starter med: transactional - hvis filnavnet starter med transactional, bliver indlæsningen delt op i mindre transaktioner. Antallet af opdateringer i hver transaktion bestemmes af propertien transaction.chunksize i config.properties. Eksempel på filnavn: transactional_nspsor.zip
- Filens navn starter med: cleandb - hvis filnavnet starter med cleandb, bliver alle rækker slettet i tabellerne: SOR2SorEntity, SOR2EanLocationCode, SOR2EanLocationCodeEdiType, SOR2EdiTypes, SOR2GeoLocalisation, SOR2SorClassifications, SOR2SorReplacedByEntities og SOR2SorShakMap. Sletningen foretages kun hvis propertien clean.db.enabled i config.properties er sat til true. Eksempel på filnavn: cleandb_nspsor.cdb - filen må gerne være tom, indholdet anvendes ikke.
- Filens navn starter med alt andet - når filnavnet ikke starter med transactional og cleandb, bliver hele filen læst ind i én transaktion.
For hver zip fil den processerer, der checker den at alle forventede CSV filer er indeholdt, før at den fortsætter. For hver at disse CSV filer, så checker den at alle forventede headers er tilgængelige i filen, før at den går igang med rent faktisk at parse en fil. Når en CSV fil er parsed, så skriver den alt data til databasen, før at den fortsætter til den næste CSV fil i zip filen.
Når der skrives til databasen, så holder importeren øje med, om den entitet allerede eksisterer i databasen. Hvis den er, så vil den lukke den gamle række først, før at den skriver den nye række. Hvis en entitet ikke er blevet opdateret under kørslen, så vil den blive lukket. Dette sker fordi at importeren forventer, at det er et fuldt udtræk af den nuværende status på entiteterne i SOR, og derved vil CSV fileren indeholde alle nuværende og fremtidige aktive entiteter. Optræder de ikke i CSV filen, så er enheden ikke længere aktiv, og skal derfor lukkes.
Fejlsituationer
Der er en række fejl som kan optræde, i forbindelse med eksekveringen af importeren. Her er en liste over de forskellige fejl muligheder, og hvordan de kan løses.
| Fejl | Type | Beskrivelse | Løsning |
|---|---|---|---|
| Zip fil kan ikke læses | Hård | Zip filen med alle CSV filer der skal importeres, kan ikke læses. Enten er filen korrupt (fejl i overførelsen), eller også har importeren ikke tilladelse til at læse filen. | Hvis filen er korrupt, så skal den enten overføres på ny, eller også skal den genereres på ny. I begge tilfælde skal fejlen nok løses i backenden der leverer zip filen. Hvis det er manglende rettigheder, så skal der tildeles læse rettigheder til filen. |
| Ukendt fil i zip filen | Blød | Der er en ekstra fil i zip filen, som importeren ikke forventer. Dette kan skyldes at backenden ved en fejl pakker ekstra filer med i zip filen, eller måske er det en fil som skal importeres, men som importeren ikke kender til endnu. | Importeren fortsætte som om at den ekstra fil ikke eksisterede. Det bør dog stadig undersøges, hvad det er for en ekstra fil som er blevet inkluderet. Hvis filen ikke bør være der til at starte med, så kan fejlen ignoreres, og backenden skal rettes så den ikke længere sender filen med. Hvis det er meningen at importeren skal kende til den nye fil, så er versionen af importer og backend ude af sync, og importeren bør opdateres hurtigst muligt. |
| Manglende fil i zip fil | Hård | Der mangler en eller flere filer i zip filen. Dette kan skyldes en fejl i backenden, at en fil er blevet misset i genereringen og pakningen af filer, eller også er det en fil type som helt er udgået. | Hvis det er er en fil som burde være inkluderet, så skal fejlen rettes i backenden hurtigst muligt, således at alle filer bliver sendt med. Hvis det er en fil som er udgået, så er versionen af importer og backend ude af sync, og importeren bør opdateres hurtigst muligt. |
| CSV fil kan ikke læses | Hård | En CSV fil kan ikke læses, hvilket der kan være mange årsager til. Det kan skyldes encoding af filen (der forventes UTF-8 BOM), filen er korrupt, og andre I/O relaterede fejl. | Det bør undersøges, hvorfor at filen ikke kunne læses. Hvis filen er korrupt, skal fejlen nok findes og rettes i backenden, før at en ny import kan foretages. Er filen i en anden encoding, kan dette rettes manuelt med forhåndenværende værktøjer, og importen kan genstartes. |
| CSV fil mangler headers | Hård | En CSV fil indeholder ikke alle de headers som importeren forventer. | Hvis det er et felt som er udgået, så skal importeren opdateres hurtigst muligt for ikke længere at forvente feltet. Hvis ikke, så skal backenden opdateres hurtigst muligt, således at det manglende felt kommer med over i fremtidige kørsler. |
| CSV fil har for mange headers | Blød | En CSV fil indeholder flere headers end importeren forventer. | Hvis det er felter som importeren er forventet at kende til, så skal importeren opdateres hurtigst muligt. Det kunne type på at versionerne af importer og backend er kommet ud af sync. Ellers kan det være felter som er udgået/unødvendige, og fejlen kan ignoreres. |
| Felt i CSV fil kunne ikke parses, og fejlhåndteringen er sat til at give exception | Hård | Den originale værdi for feltet kunne ikke parses, og fejlhåndteringen for feltet er sat til at give en exception. Feltet er obligatorisk for filen, og ikke må mangle. | Fejlen vil typisk komme fra backenden, enten ved at den får skrevet data i et forkert format, skrevet generelt forkert, eller hvis dens kilde data er mangelfuld. Hvis feltet bare er i et forkert format (så som tidsstempler ikke er i ISO-8601 format), så kan dette muligvis rettes i hånden, og importen genstartes. Ellers skal fejlen rettes i backend hurtigst muligt, så en ny fil kan genereres til importeren. |
| Felt i CSV fil er ikke sat, og fejlhåndteringen er til at give exception | Hård | Den originale værdi for feltet er tomt/null, og fejlhåndteringen for feltet er sat til at give en exception. Feltet er obligatorisk for filen, og ikke må mangle. | Fejlen vil typisk komme fra backenden, og tyder nok mest på mangelfuld kilde data. Fejlen kan nok ikke rettes i hånden, men i backenden hurtigst muligt. |
| Felt i CSV filen kunne ikke parses, og fejlhåndteringen er sat til at erstatte med standard værdi | Blød | Den originale værdi for feltet kunne ikke parses, og fejlhåndteringen for feltet var sat til at erstatte med en standard værdi fra config filen. | Fejlen vil typisk komme fra backenden, og tyder nok mest på forkert formattering af feltets værdi (så som at et tidsstempel ikke er i ISO-8601 format). Hvis værdien kan rettes til noget validt, kan importeren køres igen. Ellers skal fejlen rettes i backenden. Den forkerte værdi er erstattet af en standard værdi fra config filen, og feltet er markeret som være upålideligt. |
| Felt i CSV filen kunne ikke parses, og fejlhåndteringen er sat til at lade det være tomt/null | Blød | Den originale værdi for feltet kunne ikke parses, og fejlhåndteringen for feltet var sat til at erstatte med tomt/null. | Fejlen vil typisk komme fra backenden, og tyder nok mest på forkert formattering af feltets værdi (så som at et tidsstempel ikke er i ISO-8601 format). Hvis værdien kan rettes til noget validt, kan importeren køres igen, ellers skal fejlen rettes i backenden. Den forkerte værdi er erstattet med tomt/null, og feltet er markeret som være upålideligt. |
| Felt i CSV filen er ikke sat, og fejlhåndteringen er sat til at erstatte med standard værdi | Blød | Den originale værdi for feltet vaar tomt/null, og fejlhåndteringen for feltet var sat til at erstatte med en standard værdi fra config filen. | Fejlen vil typisk komme fra backenden, og tyder nok mest på mangelfuldt kilde data. Den forkerte værdi er erstattet af en standard værdi fra config filen, og feltet er markeret som være upålideligt. |
| Erstatning værdi for et felt i CSV filen indeholder invalidt data | Hård | Den originale værdi for feltet kunne ikke parses, og fejlhåndteringen for feltet var sat til at erstatte det med en standard værdi fra config filen. Denne værdi kunne dog heller ikke parses. | Ret standard værdien i config filen, således at den overholder det forventede format af data typen. Derefter prøv at importere igen. |
| SQL query kunne ikke udføres | Hård | Der skete en fejl under select/insert/update af rækker i Stamdata Kopi Register Service databasen. | Undersøg forbindelsen til databasen, at den er tilgængelig og funktionel. Derefter prøv at importere igen. |
| Sletning af alle rækker i databasen kan ikke udføres. | Blød | Der er fundet en cleandb* fil - men rensning af databasen er ikke tilladt. | Hvis det skal være muligt at rense tabellerne, skal propertien clean.db.enabled sættes til true. |
Hårde fejl får importeren til at stoppe, og manuel udregning er nødvendigt. Bløde fejl kræver ingen udregning, men det bør undersøges om noget eventuelt skulle gøres. Begge fejl typer bliver noteret i loggen for videre undersøgelser.
Logning
Importeren bruger to forskellige logs.
SLA log
SLA logning benytter nsp-util biblioteket, og skriver til sor2importer-sla.log i logs/ mappen. Der bliver startet et nyt SLA log objekt når en import starter, og den vil have log pointed "sor2importer.process" og ID'et "SDM4.sor2importer.process".
Applikation log
Applikation loggen styres af log4j.properties, og denne afhænger af hvad der er blevet sat op.
I denne log kommer der nogle status beskeder, hvor langt en import er nået, samt logning af diverse udfordringer under kørslen (ekstra filer i zip filen, som den ikke kender til, og derved springer over; for mange felter i filerne, som ikke bliver mapped til et felt i databasen, og derved springer over; felter i filerne, som ikke indeholde forventet type af data, og derved ikke blev parsed som forventet). Fejl under en import bliver også logged, sammen med deres stacktrace, for lettere debugging.