Kravspecifikation UND-07-T-06 DB03 Funktionalitet för att upptäcka fel i databasen 2015-06-10 Version: Beteckning: Status: 0.09 UND-07-T-06
Ändringshistorik Revision Datum Av Kommentar Granskare Godkännare 0.01 2007-10-09 Markus Umefjord Första utkast - - 0.02 2007-10-11 Markus Umefjord Revidering av nomenklatur, innehåll och krav. 0.03 2007-10-15 Markus Umefjord Kompletterande screenshots, ändringar utifrån synpunkter från Daniel Lind och Torgny Fridlund 0.04 2007-10-22 Markus Umefjord Korrigering av XSD-format. Uppdatering av Nouveaurelaterade krav. 0.05 2007-11-05 Markus Umefjord Nya krav: Zip-fil och versionsnummerkontroll nytt styrfilsformat 0.06 2007-11-08 Markus Umefjord Rättningar och ändringar utifrån kommentarer från Torgny Fridlund 0.07 2007-11-09 Markus Umefjord Rättningar och ändringar utifrån kommentarer från Sven Hedqvist 0.08 2007-11-14 Markus Umefjord Ändring i krav: Krav 6 har bytt namn, separatorsträng är ~#~ istället för ~, efter önskemål från Thomas Dahlberg och Daniel Lind 0.09 2007-11-28 Markus Umefjord Ändrad nomenklatur. Begreppet styrfil utgår till förmån för regelfil enligt önskemål från Ladokenheten och konsensus på projektmöte. 2014-01-21 Magnus Böhlin LADOK-18407 Hantera filer med INSERT,DELETE,UPDATE. 2014-01-23 Erik Adamsson LADOK-18293 2014-08-08 Thom Jönsson LADOK-17959. Hantera regelfiler med SELECT DISTINCT. 2015-06-10 Magnus Böhlin Ladok-19580, Sortering av Sammanställning + regelfiler som resulterar i 0-hittade poster skrivs ej till zip-fil. - - - - - - - - - - - - - - - -
Markus Umefjord 2014-08-23 UND-07-T-06 3 (30) Innehållsförteckning 1 INLEDNING... 5 1.1 SYFTE... 5 1.2 AKTÖRER... 5 1.3 BESKRIVNING... 5 1.3.1 Deltjänster... 5 1.3.2 Flödesbeskrivning... 6 2 BATCHSTART... 7 2.1 SYFTE... 7 2.2 BESKRIVNING... 7 2.2.1 Startformulär... 7 2.2.2 Villkorsformulär... 8 2.3 ÖVRIG INFORMATION... 10 2.3.1 Ingen regelfil anges... 10 2.3.2 Välj typ - Uppdateringsskript... 10 2.3.3 BATVILL... 10 3 REGELFILFORMAT... 11 3.1 SYFTE... 11 3.2 BESKRIVNING... 11 4 TOLKNING... 14 4.1 SYFTE... 14 4.2 BESKRIVNING... 14 4.2.1 Delflöde... 14 4.3 KRAV FÖR DELSYSTEM TOLKNING... 14 4.3.1 Felhantering... 15 5 UTSÖKNING GÄLLER ENDAST SELECT-FILER... 16 5.1 SYFTE... 16 5.2 BESKRIVNING... 16 5.2.1 Delflöde... 16 5.3 KRAV FÖR DELSYSTEM UTSÖKNING... 16 5.3.1 Felhantering... 17 5.4 SELECT DISTINCT... 17 6 ÄNDRING GÄLLER ENDAST INSERT-, UPDATE OCH DELETE-FILER... 18 6.1 SYFTE... 18 6.2 BESKRIVNING... 18 6.2.1 Delflöde... 18 6.3 KRAV FÖR DELSYSTEM ÄNDRING... 18 6.3.1 Validering av databasversion... 18 6.3.2 Felhantering... 18 7 RAPPORTERING... 19 7.1 SYFTE... 19 7.2 BESKRIVNING... 19 7.2.1 Delflöde skapa strängseparerad rapportfil vid utsökning... 19 7.2.2 Delflöde skapa rapportfil med SELECT-satser vid utsökning... 20
Markus Umefjord 2014-08-23 UND-07-T-06 4 (30) 7.2.3 Delflöde skapa zipfil... 20 7.2.4 Delflöde skapa rapportsammanställning... 20 7.3 KRAV I DELSSYSTEM RAPPORTERING... 21 7.3.1 Felhantering... 25 8 KONFIGURERBARA VÄRDEN... 26 8.1 SYFTE... 26 8.2 BESKRIVNING... 26 8.2.2 Felhantering... 28 9 UPPFÖLJNING... 29 9.1 SYFTE... 29 9.2 BESKRIVNING... 29 9.2.1 Delflöde... 29 10 ICKE FUNKTIONELLA KRAV... 30 10.1 ANVÄNDBARHET... 30 10.2 PRESTANDA... 30 10.3 SÄKERHET... 30 10.4 STABILITET... 30
Markus Umefjord 2014-08-23 UND-07-T-06 5 (30) 1 Inledning 1.1 Syfte Syftet med projektet är att implementera en funktion som gör det möjligt för ladokansvariga och driftspersonal att via ett batchförfarande identifiera/korrigera felaktigheter i databasen. 1.2 Aktörer Ladokansvarig Person på lärosätet med verksamhetsansvar för ladoksystemet. Driftspersonal Person/personer på driftscentralen som är ansvarig för den dagliga driften av ladoksystemet. Ladokpersonal Person/personer på Ladokenheten som är ansvariga för utvecklingen av ladoksystemet inklusive funktionen detta dokument avser. 1.3 Beskrivning Funktionen ska analysera ladok-databasen och identifiera fel med utgångspunkt från konfigurerbara regler som ska tillhandahållas av ladokpersonal men aktiveras av driftspersonal eller ladokansvariga. Reglerna identifierar de poster som ska identifieras vid utsökningen. Utsökningen görs i ett batchförfarande och genererar data till en rapport som sammanställs. Batchen genererar upp till två rapportfiler per regel som är aktiv vid körningen. Rapporterna kan användas av driftspersonal för att manuellt rätta databasen från de fel som identifierats. Det är även möjligt att via regelfiler som innehåller INSERT, DELETE eller UPDATE, att maskinellt rätta databasen. De regelfiler som innehåller INSERT, DELETE eller UPDATE skriver endast till rapportsammanställningen. Den enda rapportfil som genereras är eventuell felrapport. I dokumentet förekommer referenser till konfigurerbara värden. Dessa värden kännetecknas av följande syntax: ${NAMN}, där NAMN motsvarar det konfigurerbara värdets namn. 1.3.1 Deltjänster 1. Batchstart 2. Regelfilformat 3. Tolkning 4. Utsökning 5. Rapportering 6. Konfigurerbara värden
Markus Umefjord 2014-08-23 UND-07-T-06 6 (30) 7. Uppföljning 1.3.2 Flödesbeskrivning 1. Ladokansvarig eller driftspersonal identifierar behovet av att köra en utsökning av felaktiga poster. 2. Ladokansvarig öppnar Nouveau-funktionen för batchen (DB03) och anger när batchen ska startas samt villkor. 3. När tidpunkten för batchstart infaller startas batchen. 4. Batchen tolkar reglerna och avbryter om någon regel inte kan tolkas. 5. För varje SELECT-regel upprepa a. Batchen applicerar regeln. b. Batchen startar utsökning av poster som matchar regeln c. Om fel påträffas, generera felrapport och fortsätt med nästa regel. d. Batchen tolkar det utsökta resultatet. e. Batchen genererar en rapport som innehåller de poster som identifierats av utsökningen. 6. För övriga regler (DELETE, INSERT, UPDATE) upprepa a. Batchen applicerar regeln. b. Om fel påträffas, generera felrapport och fortsätt med nästa regel. 7. Batchmotorn skapar en sammanställning som innehåller övergripande information. 8. Batchmotorn skapar en notifiering (e-postmeddelande) som skickas till den adress som angetts i inställningssidan i Nouveau, normalt kommer den Ladokansvarige vara mottagaren. 9. När ladokansvarig mottagit notifieringen kan han/hon via Nouveau-gränssnittet följa upp genom att titta på de genererade filerna.
Markus Umefjord 2014-08-23 UND-07-T-06 7 (30) 2 Batchstart 2.1 Syfte Beskriver hur man via Nouveau-gränssnittet startar batchen DB03. 2.2 Beskrivning Batchen ska startas via Nouveau via standardgränssnittet för start av java-batchar. Detta innebär att man ska återanvända utseende och funktion som beskrivs i detalj för funktionen GB01 (generellt batchbeställningsformulär). I korthet innebär det följande funktionalitet; I startformuläret i Nouveau ska man ange när batchen ska starta samt göra en avgränsning av vilka regelfiler som ska ingå i körningen. Detta görs genom att välja regelfiler i villkorsformuläret. All utveckling i Nouveau, det vill säga formulär och utskrifter, ska följa Standard & Guidelines (S&G) som gäller för Uniface-utveckling. 2.2.1 Startformulär Startformuläret ska återanvända funktionaliteten från GB01. Man ska kunna ange inställningar och villkor enligt standardförfarandet.
Markus Umefjord 2014-08-23 UND-07-T-06 8 (30) Startformuläret ska ha samma struktur som formuläret för SB01 ovan, se GB01 för detaljer. 2.2.2 Villkorsformulär - Om radioknappen Ladok eller Alla skript är vald ska radioknapparna för typ vara dimmad och uppdateringsfiler vara avbockad. - Om man ändrar i radioknapparna töms automatiskt den högra listboxen med de filer som valts. - Benämningen för alla utsökningsfiler för Ladok3 inleds alltid med L3_H. - Benämningen för alla uppdateringsfiler inleds alltid med L3_UPDATE. - Java batch delen är förberedd för att det kan finnas filer som heter L3_INSERT och L3_DELETE
Markus Umefjord 2014-08-23 UND-07-T-06 9 (30)
Markus Umefjord 2014-08-23 UND-07-T-06 10 (30) 2.3 Övrig information 2.3.1 Ingen regelfil anges Användaren väljer inga filer och trycker Uppdatera. Användaren ser ett informationsfönster. Varning som ska visas när man inte valt regelfil. 2.3.2 Välj typ - Uppdateringsskript Varning visas om man väljer alternativ för att se uppdateringsskript. Problem kan uppstå om uppdateringsskripten görs mot samma tabell eftersom körordning inte kan garanteras på skripten. 2.3.3 BATVILL För varje regelfil som användaren väljer ska man skriva en post till tabellen BATVILL.
Markus Umefjord 2014-08-23 UND-07-T-06 11 (30) 3 Regelfilformat 3.1 Syfte Regelfilformatet är den notation som används för att tala om för batchen vilka regler som ska tillämpas vid utsökningen. 3.2 Beskrivning Regelfilformatet utgör den primära konfigurationsmöjligheten för batchen. Ladokpersonal skapar regelfiler som skickas till driftscentralerna i samband med ordinarie utskick, eller mellan två utskick som en del av en specialbeställning från driftscentralerna. Definition av rutiner för detta ligger utanför scopet av detta projekt. Krav 1 Regelfilformat Prioritet: 0 För att tolkningen ska kunna implementeras måste man definiera ett regelspråk som är tillräckligt kraftfullt för att kunna representera komplicerade förhållanden i databasen. Denna notation benämns vidare som regelfilformatet. Regelfilformatet är i grunden ren SQL men som tillsammans med kompletterande information är sammansatt i ett XML-format. Regelfilformatet är XML-baserat och underordnat följande XSD-beskrivning: <?xml version="1.0" encoding="iso-8859-1"?> <xs:schema xmlns:xs="http://www.w3.org/2001/xmlschema" elementformdefault="qualified" targetnamespace="http://batch.ladok.se/db03/regelfil/1.0.0" xmlns="http://batch.ladok.se/db03/regelfil/1.0.0"> <xs:element name="controlfile" type="model"> <xs:annotation> <xs:documentation source="version">1.0.0+</xs:documentation> <xs:documentation source="description"> Taggen &controlfile& är rot-taggen i regelfilen. </xs:documentation> </xs:annotation> </xs:element> <xs:complextype name="model"> <xs:annotation> <xs:documentation source="version">1.0.0+</xs:documentation> <xs:documentation source="description"> Taggen &controlfile& är rot-taggen i regelfilen. </xs:documentation> </xs:annotation> <xs:all> <xs:element name="rulename" minoccurs="0"> <xs:annotation>
Markus Umefjord 2014-08-23 UND-07-T-06 12 (30) <xs:documentation source="version"> 1.0.0 </xs:documentation> <xs:documentation source="description"> Namnet på denna regel. Fritextfält. </xs:documentation> </xs:annotation> <xs:simpletype> <xs:restriction base="xs:string"> <xs:maxlength value="60" /> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="description" minoccurs="0" type="xs:string"> <xs:annotation> <xs:documentation source="version"> 1.0.0 </xs:documentation> <xs:documentation source="description"> En beskrivning av denna regel. Här ska framgå syftet med regeln och ge användaren tillräcklig information för att förstå vilken information som söks ut och varför man vill söka ut informationen. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="databaseversion" minoccurs="0" type="xs:string"> <xs:annotation> <xs:documentation source="version"> 1.0.0 </xs:documentation> <xs:documentation source="description"> Datum på formatet 'yyyy-mm-dd'. Om detta element anges kommer regelfilen att kontrolleras mot värdet i VERSION.UTSKICK. Syftet är att kunna kräva en viss version på databasen för att en regelfil ska köras. När databasen inte har minst den angivna versionen kommer man få en felrapport, men batchen avbryts inte. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="sql" minoccurs="1" maxoccurs="1" type="xs:string"> <xs:annotation> <xs:documentation source="version"> 1.0.0 </xs:documentation> <xs:documentation source="description"> En exekverbar SQL-sats med schemanamn substituerat mot strängen SCHEMA. Ex: &SELECT * FROM SCHEMA.ADDRESS where GATADR IS NULL&. Strängen skall ej avslutas med semikolon. </xs:documentation> </xs:annotation>
Markus Umefjord 2014-08-23 UND-07-T-06 13 (30) </xs:element> <xs:element name="howtofix" minoccurs="0" type="xs:string"> <xs:annotation> <xs:documentation source="version"> 1.0.0 </xs:documentation> <xs:documentation source="description"> En beskrivning av hur man rättar fel som denna regel hittar. </xs:documentation> </xs:annotation> </xs:element> </xs:all> </xs:complextype> </xs:schema> Exempel på regelfilinnehåll: <?xml version="1.0" encoding="iso-8859-1"?> <controlfile xmlns="http://batch.ladok.se/db03/regelfil/1.0.0" xsi:schemalocation="http://batch.ladok.se/db03/regelfil/1.0.0 db03-regelfilv1.0.0.xsd"> <rulename>nullvärden i LARARE</ruleName> <!--Max 60 tecken--> <description> Hittar poster i tabellen LARARE som innehåller NULL i kolumnen TITEL </description> <databaseversion>2007-11-29</databaseversion> <!--Ska vara datum--> <sql> SELECT KOD,INST FROM SCHEMA.LARARE WHERE TITEL IS NULL </sql> <howtofix> Du kan rätta detta fel genom att köra följande SQL-sats: UPDATE SCHEMA.LARARE SET TITEL = ' _' WHERE KOD=? AND INST=? Ersätt frågetecken med resultatet från körningen. </howtofix> </controlfile> Regelfilen ska namnges med en unik kod som filnamn. Filändelsen ska vara.xml. Ex: REGEL_123.xml, ger koden REGEL_123. Krav 1.1 Dokumentation av regelfilformatet Prioritet: 0 Regelfilformatet ska dokumenteras som en versionshanterad XSD-fil.
Markus Umefjord 2014-08-23 UND-07-T-06 14 (30) 4 Tolkning 4.1 Syfte Tolkningens syfte är att tolka det regelfilformat som anger reglerna för hur felaktiga poster ska sökas ut eller ändras. Den tolkade informationen innehåller följande delar; kod (framgår av filnamnet), namn, beskrivning samt SQL. 4.2 Beskrivning Tolkaren läser de regelfiler som användaren angivit via villkoren. Filerna parsas och SQL-satsen plockas fram, schema-identifieraren substitueras och den körbara SQL-koden skickas vidare till utsökningsmekanismen. 4.2.1 Delflöde 1. Batchprogrammet startas med kod som argument 2. Om kod saknas i argumentlistan skall detta tolkas som att alla tillgängliga regler ska användas. 3. Tolkaren verifierar att regelfilen går att hitta med hjälp av koden. 4. För varje regelfil som ska köras, gör följande: a. Öppna regelfilen. b. Tolka/parsa regelfilen. c. Ersätt schema-identifieraren ( SCHEMA ) i SQL-strängen mot det konfigurerbara värdet ${SCHEMA}. d. Kontrollera att SQL-satsen som är giltig och körbar. 5. Aktivera utsökning med samtliga verifierade SQL-satser. 4.3 Krav för delsystem Tolkning Krav 2 Inläsning av regelfil Prioritet: 0 Regelfilerna ska vara läsbara och ligga i katalogen ${INPUT} när batchen startar. Tolkaren skall läsa en eller flera regelfiler från denna katalog (anges via batchvillkor i Nouveau).
Markus Umefjord 2014-08-23 UND-07-T-06 15 (30) Krav 3 Tolkning av regelfil Prioritet: 0 Tolkaren skall tolka de inlästa regelfilerna, göra eventuella manipuleringar av SQL-koden (t.ex. ersätta schema-identifieraren), validera att den färdiga SQL-satsen är körbar mot databasen samt returnera de färdiga SQL-satser som ska tillämpas. Krav 3.1 Verifiera genererad SQL-kod Prioritet: 0 Tolkningen ska kontrollera att SQL-satsen är körbar genom att testa den mot databasen (testa, inte köra). Om SQL-satsen inte är körbar ska tolkaren generera ett felmeddelande som loggas och skickas som ett mail till beställaren av batchen. Krav 3.2 Logga genererad SQL-kod Prioritet: 1 Tolkarens output, dvs. den SQL-sats som sedermera körs vid exekvering ska kunna hittas i loggarna. 4.3.1 Felhantering Om ett fel upptäcks i en regelfil där regeln inte kan tolkas på rätt sätt (SQL-satsen är inte körbar) så ska tolkaren avbryta batchen efter att ha loggat felet. Detta gör det möjligt att snabbt upptäcka fel i konfigurationen. Fel som upptäcks på detta sätt ska skickas som ett mail till beställaren av batchen.
Markus Umefjord 2014-08-23 UND-07-T-06 16 (30) 5 Utsökning gäller endast SELECT-filer 5.1 Syfte Utsökning av felaktiga poster sker genom att exekvera den SQL-sats som genererats av tolkaren. Syftet är att samla in och förbereda det data som ska användas vid rapportgenereringen. 5.2 Beskrivning Utsökningen sker genom att de SQL-satser som tolkats från regelfilerna exekveras. Resultatet ska ligga till grund för de rapportfiler som skapas. Utsökningen av felaktiga poster måste resultera i att informationen som söks ut är tillräcklig för att ge ett relevant underlag till rapportmottagaren. Vad som måste ingå i en framgångsrik utsökning anges i nedanstående krav. 5.2.1 Delflöde 1. SQL-koden för alla regelfiler har tolkats och validerats av tolkaren 2. För varje SQL-sats, gör följande: a. Kör SQL-koden mot databasen b. Om fel påträffas, generera en felrapport och fortsätt med nästa SQL-sats. c. Om fel inte påträffas, vidarebefordra resultatet för rapportering. 5.3 Krav för delsystem Utsökning Krav 4 Utsökning av information Prioritet: 0 Varje post som söks ut måste kunna kopplas till primärinformation som innehåller följande delar: 1. Tabell där posten påträffades 2. Primärnyckel i tabellen 3. När utsökningen gjordes 4. Hur lång tid utsökningen tog (anges i sekunder) Informationen ska kunna kopplas direkt eller indirekt till varje post, dvs. det ska vara möjligt att utgå från en post i resultatet och kunna få fram ovanstående information. Krav 4.1 Identifiering av primärnyckel
Markus Umefjord 2014-08-23 UND-07-T-06 17 (30) Prioritet: 1 Primärnyckelns sammansättning varierar beroende på vilken tabell man söker i. Typiskt är primärnyckeln en sammansättning av två eller flera kolumner. Utsökningsmekanismen måste för varje SQL-sats som körs identifiera vilken primärnyckeln är för de utsökta posterna. Detta görs genom slagningar mot Mimer-vyn INFORMATION_SCHEMA.KEY_COLUMN_USAGE. Ex: Om den genererade SQL-satsen ser ut på följande vis: select * from UTC.ADRESS; så ska identifieringen av primärnyckeln själv ta reda på att det är kolumnerna PNR + ADRTYP som utgör primärnyckeln. Detta krav är en förutsättning för att man ska kunna implementera Krav 6. Krav 4.2 Validering av databasversion Prioritet: 2 För att undvika problem med att nya regelfiler inte är kompatibla med äldre versioner av databasen är det önskvärt att man kontrollerar databasversionen i tabellen VERSION. Om man i regelfilen angett fältet databaseversion skall man kontrollera att kolumnen UTSKICK i tabellen VERSION har en version som är lika med eller nyare än versionen i regelfilen. Om versionen i databasen är äldre än versionen i regelfilen ska regelfilen inte köras, och istället för en rapport ska en felrapport skapas. Versionen som anges i regelfilen ska följa samma format som värdena i VERSION.UTSKICK; i skrivande stund ett datum på formatet yyyy-mm-dd. 5.3.1 Felhantering Om fel upptäcks vid utkörningen ska varje felaktig utsökning resultera i en felrapport som genereras istället för en normal rapport. Fel i detta steg ska inte stoppa batchen, utan resterande utsökningar ska genomföras. 5.4 SELECT DISTINCT För att regelfilerna skall parsas korrekt får DISTINCT inte efterföljas av parenteser som i detta exempel: SELECT DISTINCT (pnr) FROM Korrekt användning av DISTINCT ser istället ut enligt följande: SELECT DISTINCT pnr FROM
Markus Umefjord 2014-08-23 UND-07-T-06 18 (30) 6 Ändring gäller endast INSERT-, UPDATE och DELETE-filer 6.1 Syfte Rättning av felaktiga poster sker genom att exekvera den SQL-sats som genererats av tolkaren. 6.2 Beskrivning Rättningen sker genom att de SQL-satser som tolkats från regelfilerna exekveras. Vad som måste ingå i en framgångsrik rättning anges i nedanstående krav. 6.2.1 Delflöde 3. SQL-koden för alla regelfiler har tolkats och validerats av tolkaren 4. För varje SQL-sats, gör följande: a. Kör SQL-koden mot databasen b. Om fel påträffas, generera en felrapport och fortsätt med nästa SQL-sats. 6.3 Krav för delsystem Ändring 6.3.1 Validering av databasversion För att undvika problem med att nya regelfiler inte är kompatibla med äldre versioner av databasen är det önskvärt att man kontrollerar databasversionen i tabellen VERSION. Om man i regelfilen angett fältet databaseversion skall man kontrollera att kolumnen UTSKICK i tabellen VERSION har en version som är lika med eller nyare än versionen i regelfilen. Om versionen i databasen är äldre än versionen i regelfilen ska regelfilen inte köras, och istället för en rapport ska en felrapport skapas. Versionen som anges i regelfilen ska följa samma format som värdena i VERSION.UTSKICK; i skrivande stund ett datum på formatet yyyy-mm-dd. 6.3.2 Felhantering Om fel upptäcks vid utkörningen ska varje felaktig ändring resultera i en felrapport som genereras istället för en normal rapport. Fel i detta steg ska inte stoppa batchen, utan resterande ändringar ska genomföras.
Markus Umefjord 2014-08-23 UND-07-T-06 19 (30) 7 Rapportering 7.1 Syfte Batchens huvudsyfte är att generera underlag till underhållspersonal som med hjälp av detta manuellt ska kunna rätta de felaktigheter som hittas. Detta underlag levereras i form av rapportfiler som kan laddas ner via Nouveau-grässnittet. Maskinella rättningar genererar endast information till rapportsammanställningen. 7.2 Beskrivning Den information som påträffas i utsökningen utgör underlaget för rapportfilerna som skapas. Varje regel som exekveras ska generera två rapportfiler eller en felrapportfil. De två rapportfilerna ska lista samtliga poster som påträffats vid utsökningen, men redovisat på två olika format. Den första rapportfilen innehåller strängseparerade värden, med kolumnrubriker på första raden. Den andra rapportfilen innehåller en Sql-selectsats per rad, där selectsatsen gör det möjligt att direkt söka ut den post som påträffats, dvs. med primärnyckeln som avgränsning. De regelfiler som resulterar i 0 träffar kommer det inte skapas några rapportfiler för, de hamnar endast i sammanställningen. När samtliga rapportfiler för alla regelfiler är genererade ska rapporteringsdelen skapa en sammanställning av det totala resultatet i en separat fil. 7.2.1 Delflöde skapa strängseparerad rapportfil vid utsökning 1. SQL-satsen har körts av utsökningen och resultatet är redo 2. Tolka vilken information som finns tillgänglig för rapportering (kolumnnamnen) 3. Skriv kolumnnamnen som rubriker i rapportfilen i den ordning de förekommer i SQLsatsen, med en specifik teckensträng som separator. Rader ska ej avslutas med separatorsträngen. 4. Läs informationen som finns tillgänglig 5. För varje post i resultatet gör detta: a. Skriv samtliga kolumnvärden i den ordning de förekommer i SQL-satsen till rapportfil med en specifik teckensträng som separator. Rader ska ej avslutas med separatorsträngen. 6. Spara filen enligt namnkonvention. 7. Notera filnamnet för att kunna zippa ihop alla rapportfiler till en zipfil. 8. Spara undan underlag för rapportsammanställning.
Markus Umefjord 2014-08-23 UND-07-T-06 20 (30) 7.2.2 Delflöde skapa rapportfil med SELECT-satser vid utsökning 1. SQL-satsen har körts av utsökningen och resultatet är redo 2. Tolka vilken/vilka tabeller som värden har sökts ut ifrån. 3. Tolka vilka kolumner som finns med i primärnyckeln. 4. Fastställ att alla primärnyckelkolumner finns med i utsökningen. a. Om en eller fler primärnyckelkolumner saknas i utsökningen: i. Logga ett fel i batch-loggen med information om vilka primärnyckelkolumner som saknas i utsökningen. ii. Spara undan denna information till rapportsammanställningen. iii. Avbryt detta flöde. Rapportfil skapas ej. 5. Skapa ett SELECT-uttryck enligt följande pseudokod: SELECT * FROM tabellnamn 6. För varje post i resultatet gör detta: a. Läs värdet från primärnyckelkolumnerna. b. Skapa en WHERE-uttryck där primärnyckelkolumnerna och motsvarande värden avgränsar frågan enligt följande pseudokod: WHERE pk1= v1 AND pk2= v2 AND AND pkn= vn c. Slå ihop SELECT-uttryck och WHERE-uttryck och skriv detta som en rad i rapportfilen. Avsluta raden med semikolon. 7. Spara filen enligt namnkonvention. 8. Notera filnamnet för att kunna zippa ihop alla rapportfiler till en zipfil. 9. Spara undan underlag till rapportsammanställningen. 7.2.3 Delflöde skapa zipfil 1. Samtliga rapporter och felrapporter har skapats och skrivits till disk 2. Tag alla rapporter och felrapporter som innehåller relevant information (ej tomma) och skapa en zipfil av dessa. 3. Skriv en rad i BATFIL för att man ska kunna hämta den via Nouveau. 7.2.4 Delflöde skapa rapportsammanställning 4. Samtliga rapporter har skapats och underlag finns tillgängligt 5. För varje regelfil som aktiverats gör detta: a. Skriv följande information till rapportsammanställningsfilen: i. ${BATCH_KOD}
Markus Umefjord 2014-08-23 UND-07-T-06 21 (30) ii. Namn på regeln (läses från regelfilen) iii. Beskrivning av regel (läses från regelfilen) iv. Hur lång tid rapportgenereringen tog v. Hur många poster som påträffades/ändrades i exekveringen. 6. Spara filen med namnet rapportsammanstallning.txt 7. Skriv en rad i BATFIL för att man ska kunna hämta den via Nouveau. 7.3 Krav i delssystem Rapportering Krav 5 Skapa rapportfil strängseparerad, gäller endast utsökning. Prioritet: 0 Programmet ska skapa en rapportfil för varje regel som körts. Rapportfilen namnges efter namnet på regeln, dvs. ${BATCH_KOD}, men med filändelsen _rapport.txt. Rapportfilen genereras med strängseparerade värden. Defaultvärdet ska vara ~#~, dvs teckenkombinationen tilde, staket, tilde. Filen ska innehålla en rad med rubriker som består av kolumnnamnen, därefter en rad för varje post i resultatet med motsvarande värden. Förhållandet mellan regelfil och rapportfil framgår nedan: Regelfilnamn Katalog Rapportfilnamn Katalog Null_alla_tabeller.txt ${INPUT} Null_alla_tabeller_rapport.txt ${OUTPUT} Exempel: Regelfil: KOD123.xml Batchkod (deducerad från filnamnet): KOD123 Rapportfilnamn: KOD123_rapport.txt SQL-sats som körs: SELECT PNR, ADRTYP FROM UTC.ADRESS WHERE GATADR IS NULL; Filinnehåll: PNR~#~ADRTYP 010101P658~#~4 0706133949~#~2 0909090904~#~4
Markus Umefjord 2014-08-23 UND-07-T-06 22 (30) Teckenkombinationen ~#~ används som separator mellan värden i filen. Varje rad avslutas med newline-tecken. Om inga poster hittades vid utsökningen ska rapporten skriva ut texten Inga poster hittades. Detta för att undvika förvirring om filen är tom. Krav 5.1 Stöd för andra skiljetecken Prioritet: 2 Det kan finnas behov av att använda andra strängar som fältseparator i filen. Det ska via det konfigurerbara värdet ${SEPARATOR} vara möjligt att ange valfria tecken/teckenkombinationer som används som separatorer mellan fälten i filen. Krav 5.2 Hantering av NULL-värden i resultatet Prioritet: 1 I de fall där ett utläst värde är NULL skall detta skrivas i rapportfilen som teckenkombinationen NULL Krav 6 Skapa rapportfil SELECT-satser Prioritet: 2 Programmet ska skapa en rapportfil för varje regel som körts. Rapportfilen namnges efter namnet på regeln, dvs. ${BATCH_KOD}, men med filändelsen _rapport.sql. Rapportfilen ska innehålla SELECT-satser separerade av semikolon. Detta gör det möjligt för testpersonalen att snabbt kunna söka fram de poster som hittats av utsökningen i ett SQL-klientprogram. Filen ska innehålla en rad för varje post i resultatet. Förhållandet mellan regelfil och rapportfil framgår nedan: Regelfilnamn Katalog Rapportfilnamn Katalog Null_alla_tabeller.txt ${INPUT} Null_alla_tabeller_rapport.sql ${OUTPUT} Exempel: Regelfil: KOD123.xml Batchkod (deducerad från filnamnet): KOD123 Rapportfilnamn: KOD123_rapport.sql SQL-sats som körs: SELECT PNR, ADRTYP, POSTNR FROM UTC.ADRESS WHERE GATADR IS NULL;
Markus Umefjord 2014-08-23 UND-07-T-06 23 (30) Filinnehåll: SELECT * FROM UTC.ADRESS WHERE PNR='010101P658' AND ADRTYP='4'; SELECT * FROM UTC.ADRESS WHERE PNR='0706133949' AND ADRTYP='2'; SELECT * FROM UTC.ADRESS WHERE PNR='0909090904' AND ADRTYP='4'; Observera att POSTNR inte är en del av primärnyckeln och därför inte tas med i WHERE-satsen. Det ska vara möjligt att via konfiguration stänga av genereringen av denna rapporttyp. Krav 6.1 Skapa rapportfil SELECT-satser med flera tabeller Prioritet: 3 I de fall flera tabeller joinas ihop i utsökningen ska detta kunna översättas till en select-fråga som är körbar och plockar ut motsvarande post ur databasen. Joinuttrycken måste bevaras och avgränsningen i rapportfilen ska ske med tillgängliga primärnyckelvärden i de berörda tabellerna. Exempel: SQL-sats som körs: SELECT * FROM UTV.NAMN A, UTV.ADRESS B WHERE A.PNR = B.PNR AND A.ENAMN IS NULL AND B.GATADR IS NULL; Filinnehåll: SELECT * FROM UTV.NAMN A, UTV.ADRESS B WHERE A.PNR = B.PNR AND A.PNR = '010101P658' AND A.ADRTYP = '4' AND B.PNR='010101P658'; Observera att samtliga join-avgränsningar och primärnyckelavgränsningar finns representerade i WHERE-uttrycket. Krav 7 Skapa rapportsammanställning Prioritet: 1 När rapporterna är genererade skall batchen skapa en sammanställning av batchen som helhet. Innehållet i rapportsammanställningen ska vara följande: 1. Total exekveringstid för samtliga regelfiler. 2. Antalet regelfiler som körts. 3. När första regelfilen startades
Markus Umefjord 2014-08-23 UND-07-T-06 24 (30) 4. När sista regelfilen avslutades 5. För varje regelfil ska följande innehåll skrivas ut: a. ${BATCH_KOD} b. Namn på regeln (läses från regelfilen) c. Beskrivning av regel (läses från regelfilen) d. Status, OK eller FAIL. Om FAIL skall en anledning skrivas ut. e. Hur många poster som påträffades/ändrades i exekveringen. f. Hur lång tid rapportgenereringen tog g. SQL-satsen som kördes Exempel: Regelfiler: KOD123.xml, KOD456.xml Filinnehåll: SAMMANSTÄLLNING AV BATCH DB03 Total exekveringstid: 3456 sek Antal aktiva regelfiler: 2 Starttid: 2007-10-11 15:00:00 Stopptid: 2007-10-11 15:57:36 KOD123 Namn: Nullvärden i LARARE Beskrivning: Utsökning av lärare där INAKTIV-kolumnen innehåller null eller '_'. Syftet är att... Status: OK Antal hittade poster: 234 Exekveringstid: 1234 sek SQL: SELECT KOD,INST,INAKTIV FROM UTV.LARARE WHERE (INAKTIV IS NULL OR INAKTIV = '_') KOD456 Namn: Nullvärden i ADRESS Beskrivning: Utsökning av adresser där GATADR-kolumnen är null. Syftet är... Status: FAIL Primärnyckekolumnen ADRTYP saknas i SELECT-uttrycket. Sqlrapport har ej genererats.
Markus Umefjord 2014-08-23 UND-07-T-06 25 (30) Antal hittade poster: 10 Exekveringstid: 2222 sek SQL: SELECT PNR,POSTNR FROM UTC.ADRESS WHERE GATADR IS NULL Krav 7.1 Skapa zipfil av rapporter Prioritet: 2 För att undvika problem vid nedladdning av filer i Nouveau är det önskvärt att applikationen zippar ihop samtliga rapport- och felrapportfiler till en zipfil som registreras i BATFIL. Detta gör att man enbart behöver ladda ner två filer från servern när man väljer funktionen Hämta fil i Nouveau sammanställningen och zipfilen. Zipfilen ska enbart innehålla de filer som har något innehåll tomma rapportfiler ska uteslutas. Krav 8 Konfigurerbara rapporttyper Prioritet: 2 Det ska vara möjligt att konfigurera vilka rapporttyper man vill generera. Vissa driftscentraler kan vara intresserade av båda rapporttyperna medan andra enbart vill ha en. Det ska vara möjligt att via konfiguration ange det konfigurerbara värdet ${REPORT_TYPES} som styr vilken/vilka rapporter som ska genereras. Krav 9 Skicka notifikation om batchavslut Prioritet: 0 När samtliga rapporter samt rapportsammanställning är skapade ska batchen skicka en notifikation till personen som aktiverat batchen. Detta skall ske på samma sätt som för andra batchar, dvs. genom konfiguration av mottagaradress (${REPORT_TO}) i Nouveau. 7.3.1 Felhantering Om fel inträffar när en rapportfil ska skapas ska detta resultera i en felrapport istället för en rapportfil. Om det utsökta resultatet inte innehåller samtliga primärnyckelkolumner ska detta leda till att man inte skapar en rapportfil med SELECT-satser då man inte entydigt kan hitta den påträffade posten på det sättet. Dessa fel ska loggas och tas med i sammanställningen.
Markus Umefjord 2014-08-23 UND-07-T-06 26 (30) 8 Konfigurerbara värden 8.1 Syfte Det är önskvärt att vissa parametrar ska kunna konfigureras utan att behöva ändra i applikationen. Det rör sig om t.ex. varifrån regler ska läsas, var rapportfilerna sparas, till vem/vilka rapportsammanställningen skickas etc. Konfigurerbara värden gör det möjligt för driftspersonal på driftscentralerna att ändra vissa viktiga inställningar utifrån de förutsättningar som gäller för dem. 8.2 Beskrivning Krav 10 Generell mekanism för konfiguration Prioritet: 1 Programmet ska hantera all inkommande konfiguration av statiska värden på samma sätt. Meningen är att man från ett och samma ställe ska kunna ändra samtliga konfigurerbara värden, t.ex. via en properties-fil. Mekanismen skall läsa konfigurationen vid uppstart och därefter använda dessa värden statiskt under resten av exekveringen. Ändringar i konfigurationen som sker efter att batchen startats (medan den fortfarande pågår) ska inte läsas in. Krav 11 Definition av konfigurerbara värden Prioritet: 0 Följande värden ska vara möjligt för en driftsansvarig att konfigurera utan att ändra i applikationen. 8.2.1.1 ${BATCH_KOD} Beskrivning Konfiguration via Obligatorisk Unik kod som motsvarar filnamnet för en regelfil (utan filändelsen.xml) Batchvillkor i Nouveau. Nej, om den ej anges tolkas detta som att samtliga regelfiler i ${INPUT} ska köras. 8.2.1.2 ${INPUT} Beskrivning Konfiguration via Sökväg till den katalog där regelfilerna ligger. Batchspecifik property i ladok.batch.properties.
Markus Umefjord 2014-08-23 UND-07-T-06 27 (30) Obligatorisk Ja 8.2.1.3 ${OUTPUT} Beskrivning Konfiguration via Obligatorisk Sökväg till den katalog dit rapportfilerna och felrapportfilerna ska skrivas. Batchspecifik property i ladok.batch.properties. Ja 8.2.1.4 ${REPORT_TO} Beskrivning Konfiguration via Obligatorisk E-post-adress dit notifikation om att batchen är klar skickas. Personliga inställningar i Nouveau. Nej, om den ej anges används standard-epost-adressen för användaren som startat batchen. 8.2.1.5 ${SCHEMA} Beskrivning Konfiguration via Obligatorisk Namnet på det schema där regeln ska köras. Global property i ladok.batch.properties. Ja 8.2.1.6 ${REPORT_TYPES} Beskrivning Anger vilka rapporttyper man är intresserad av att generera. Konfiguration via Global property i ladok.batch.properties. Obligatorisk Nej, om inget anges genereras samtliga tillgängliga rapporttyper. 8.2.1.7 ${SEPARATOR} Beskrivning Konfiguration via Obligatorisk Anger vilken teckenkombination som används som separator i rapportfilerna för Krav 5. Global property i ladok.batch.properties. Nej, om inget anges används teckenkombinationen tilde, staket, tilde (~#~).
Markus Umefjord 2014-08-23 UND-07-T-06 28 (30) 8.2.2 Felhantering När ett konfigurerbart värde saknas i konfigurationen skall systemet försöka använda ett defaultvärde för att om möjligt kunna fortsätta. Systemet ska i dessa fall skriva en varning i batchloggen så att systemansvariga kan rätta felet. Om det är orimligt att fortsätta när ett värde saknas eller om ett angivet värde är felaktigt och oanvändbart så ska systemet logga detta som ett fel i batchloggen beroende på konsekvenserna. Normalt sett ska denna typ av fel leda till att batchen avbryts.
Markus Umefjord 2014-08-23 UND-07-T-06 29 (30) 9 Uppföljning 9.1 Syfte Uppföljning sker när batchen är avslutad. Batchen har då producerat en eller flera rapportfiler och/eller en eller flera felrapportfiler. Rapportfilerna är ett underlag för driftspersonal som manuellt ska rätta felaktiga värden i databasen. Felrapportfilerna är ett underlag främst för ladokpersonal. Om ett fel har uppstått i en batch så beror det på onormala omständigheter och detta skall normalt återkopplas till Ladokpersonal för översyn och rättning. 9.2 Beskrivning Åtkomsten till rapport- och felrapportfiler ska ske i första hand via Nouveau-gränssnittet. För driftspersonal ska det även möjligt att hämta filerna direkt via filytan för Nouveau. När användaren har mottagit mailnotifikationen är filerna tillgängliga för nedladdning. Tillsammans med sammanställningen ska rapportfilerna ge tillräckligt med information för att driftspersonal ska kunna rätta de fel som identifierats med de givna reglerna. 9.2.1 Delflöde 1. Användaren loggar in i Nouveau 2. Användaren väljer en batch är klarmarkerad 3. Användaren klickar på Hämta fil 4. Samtliga rapportfiler och felrapportfiler som genererats av batchen laddas ner via Save as -dialog. Krav 12 Nedladdning av filer från Nouveau Prioritet: 0 Man ska kunna ladda ner rapportfiler och felrapportfiler via Nouveau på samma sätt som för befintliga batchar.
Markus Umefjord 2014-08-23 UND-07-T-06 30 (30) 10 Icke funktionella krav 10.1 Användbarhet All utveckling av program med grafisk layout, dvs. formulär och utskrifter, ska följa Standards and Guidelines (S&G) som gäller för Uniface-utveckling. 10.2 Prestanda Inga särskilda prestandakrav eftersom den faktiska prestandan till största del är kopplad till de regler (de SQL-satser) som körs. Hänsyn ska tas till prestanda vid utveckling av regelfiler på så sätt att de optimeras för god prestanda innan regelfilen tas i bruk. 10.3 Säkerhet Inga särskilda säkerhetsmekanismer behövs då systemet ska köras i batchmiljö. 10.4 Stabilitet Systemet körs inte som en service som förväntas ha en viss uptime. Batchen startas antingen manuellt eller via schedulering. Dock ska batchen logga alla fel, varningar och viktiga informativa händelser i en batchlogg som kan följas upp. Batchen ska kunna hantera en obegränsad storlek på det resultat (antalet poster) som returneras från regelfilerna.