LESSOR-5. Inquiry (teknisk beskrivelse) Tilgængelighed for andre systemer

LESSOR-5 Inquiry (teknisk beskrivelse) Effektive og fleksible IT-løsninger til LØN, TID og HR Tilgængelighed for andre systemer LESSOR-5 Inquiry har til formål at gøre data i LESSOR-5 tilgængelig for andre systemer. Med LESSOR-5 Inquiry har virksomheden mulighed for at lade eksterne klient-programmer foretage kontrollerede forespørgsler på data i LESSOR-5 databasen. Derved opnås en meget enkel mulighed for at integrere systemer i virksomheden. I LESSOR-5 defineres et antal queries og et klientprogram kan nu via en http-request forespørge på data og modtage resultatet som et xml-dokument. Ved at anvende http og xml gøres det let for forskellige teknologier på forskellige platforme og servere at kommunikere da mange programmeringssprog og værktøjer understøtter disse. En anden fordel er at man kan anvende en browser fx Internet Explorer til at afprøve funktionen med. Dette hjælper meget i både udvikling af klienten og evt. fejlfindings-situationer. Definitionen af queries vil normalt blive foretaget af en LESSOR-konsulent, men kan evt. foretages af kunden selv. Klient-programmet udarbejdes af kunden eller en ekstern konsulent på kundens vegne. LESSOR kan bistå med rådgivning og vejledning i forbindelse hermed. Gydevang 46 3450 Allerød Tlf 48 16 60 00 Fax 48 16 60 06 post@lessor.dk www.lessor.dk

Request Et eksempel på en http-request: http://localhost:7001/lessor5/inquiry?name=emppay&lonnr=0315 localhost udskiftes med ip-adresse eller DNS-navn hvis klienten ikke kører på samme server som LESSOR-5. :7001 er den tcp/ip-port som LESSOR-5 normalt benytter. Til LESSOR-5 test-system kan fx benyttes 7003. Det kan konfigureres og derfor være anderledes i det konkrete tilfælde. /lessor5/inquiry er konstant.?name=emppay angiver navnet på query. Der kan som nævnt defineres et antal af disse. &lonnr=0315 er en parameter til netop emppay-query en. Der skal i hvert enkelt tilfælde aftales hvilke parametre (navne og værdier) der skal anvendes. Der kan anvendes flere parametre idet der blot fortsættes med &parm2=value2&parm3=value3. Såfremt der mangler en krævet parameter i requesten returneres status= 11 (no value found for xxx). Det er således klientens ansvar at sikre at der sendes de rigtige parametre i requesten. Det anbefales at klient anvender en url-template der indeholder tags der udskiftes af klienten ved de enkelte requests, fx: http://lessorsrv:7001//lessor5/inqiry?name=emppay&lonnr=${lonnr} hvor klienten så udskifter ${lonnr} med det aktuelle lønnummer. Disse templates kan være hard-kodede, komme fra en tekst-file eller fra rækker i en database-tabel. Implementering er helt op til klienten. LESSOR-5 - Inquiry (teknisk beskrivelse) 2/15

Response Resultatet er som nævnt et xml-dokument. Strukturen på dette bestemmes af definitionen i LESSOR-5. Der er flere muligheder for at styre xml-dokumentets udseende, hvilket gennemgås nærmere under definition af queries, men det vil afspejle LESSOR-5s datamodel (tabeller og felter). Her gennemgås et eksempel, der tilstræbes af være repræsentativ for de muligheder der er, selve xml-dokumentet findes i appendix A. <?xml version="1.0" encoding="iso-8859-1"?> Linien sendes altid af hensyn til xml-værktøjer og specifierer primært at der anvendes iso-8859-1 character set, dette skulle sikre at de Danske bogstaver (æøåæøå) kan håndteres korrekt. <emppay generated="20090910151217" lookupdate="20090910" sourcesystem="lessor-5" status="0" text="ok"> emppay er navnet på query en fra http-requesten. generated= xxx angiver hvornår xml-dokumentet er dannet (LESSOR-5 serverens tid). lookupdate= xxx angiver hvilken dato der er anvendt til opslaget i LESSOR-5 databasen. LESSOR-5 indeholder historik og revisionsspor i databasen, se mere herom senere. Default er dags dato, men kan angives i request. sourcesystem= LESSOR-5 er blot til information. status= 0 og text= OK angiver retur-status på requesten, se mere herom senere. <employeeemployment lonnr="0315"> employeeemployment er LESSOR-5 tabel-navnet hvorfra de følgende data hentes, det kan overrides i querydefinition såfremt der ønskes et andet tag-navn. lonnr= 0315 er en felt-værdi der returneres. I query-definitionen kan man vælge om et felt skal returneres som en xml-attribut (som her) eller som et xml-tag. Normalt vil felt-navnet være det som LESSOR-5 anvender (engelsk) men her er der valgt et andet (lonnr) i definitionen. <emppermanentpayreg> Dette xml-tag markere at efterfølgende data kommer fra emppermanentpayreg-tabellen. I eksemplet kom der ikke data fra employeeemployment-tabellen, udover lonnr, var det tilfældet kunne de forekomme som separate xml-tags. Læg mærke til at der er flere emppermanentpayreg- og employeetaxinformation-tags inde under employeeemployment-tag et. LESSOR-5 - Inquiry (teknisk beskrivelse) 3/15

<paytypecode>1001</paytypecode> Her fremgår at værdien af feltet paytypecode er 1001. Feltet er et tekst-felt hvor leading- og trailing-spaces er fjernet. <units>1</units> units-feltet er et decimaltal. Hvis det havde decimaler ville det se således ud: <units>2.17</units> Læg mærke til at decimal-tegnet er et punktum (og IKKE et komma!). Såfremt det var negative ville der være et minustegn foran tallet. <employeetaxinformation> Herefter kommer data fra employeetaxinformation-tabellen. Denne tabel er på linie med emppermanentpayreg mens de begge er underordnet employeeemployment. <taxyear>2007</taxyear> taxyear er et heltal. Såfremt det kunne være negativt ville der være et minus-tegn foran. <taxcardreceiveddate>20080219</taxcardreceiveddate> Feltet indeholder en dato, der altid er på formen yyyymmdd. En sidste bemærkning omkring xml-resultatet er at gøre opmærksom på at felter uden værdi, dvs. blanke tekstfelter, talfelter med nul og de specielle LESSOR-5 min- og max-datoer IKKE returneres. LESSOR-5 - Inquiry (teknisk beskrivelse) 4/15

Fejl-situationer Hvis man ikke angiver en korrekt url frem til og med inquiry får man en normal http 404 not found retur. Angiver man ingen (null) eller et ukendt query-name får man følgende retur: <?xml version="1.0" encoding="iso-8859-1"?> <xxx generated="20090910163829" lookupdate="20090910" sourcesystem="lessor-5" status="10" text="127.0.0.1(127.0.0.1) requested unknown query:xxx"/> Såfremt LESSOR-5 ikke kan finde nogen data til en request returneres: <?xml version="1.0" encoding="iso-8859-1"?> <emppay generated="20090910163941" lookupdate="20090910" sourcesystem="lessor-5" status="1" text="no data"/> En oversigt over status-koder og tilhørende tekst 0 OK 1 no data 10 127.0.0.1(127.0.0.1) requested unknown query:xxx 11 <request-error:text> 20 192.168.1.27 (pcbjb) not allowed 30 error in inquiry.xml configuration 31 <SQL-error:text> 90 <general-error:text> Logning Der anvendes log4j til logning og logning kan derfor konfigureres i log4j.properties eller jboss-log4j.xml afhængig af platform. Java-klasse-navnet er dk.lessor.lessor5.integration. InquiryServlet. Udover generelle fejl- og debugmeddelelser er følgende relevante: NFO: Inquiry from:127.0.0.1:/lessor5/inquiry?name=empbycpr&dkcprnummer=101010106 INFO: Inquiry from:127.0.0.1:/lessor5/inquiry?name=reload INFO: 127.0.0.1:inquiry.xml will be reloaded WARN:127.0.0.1(127.0.0.1) requested unknown query:xxx WARN:RequestError:no value found for <parameter> WARN: error in inquiry.xml configuration WARN: SQLerror:<sql-error text> ERROR: InquiryServletException:<stacktrace> LESSOR-5 - Inquiry (teknisk beskrivelse) 5/15

Sikkerhed Det forudsættes at klient og LESSOR-5 server befinder sig på et lokalnet, således at der ikke er behov for kryptering og firewall-opsætning mm. Såfremt klient og LESSOR-5 server befinder sig på forskellige lokationer, kan trafikken ledes via et privat net eller fx en ssl/ssh-tunnel etableret af routere/firewalls. Skal kommunikationen foregå via internettet bør der krypteres med ssl, dette kræver en opsætning i LESSOR-5 applikationsserveren (JBoss eller WebLogic). I inquiry.xml kan defineres fra hvilke ip-adresse man vil tillade queries, forsøg fra, andre vil blive afvist (status=20) og logget. Det anbefales at sætte 127.0.0.1 (localhost) ind for at lette test og support. LESSOR-5 database historik I LESSOR-5 gemmes såvel historik (hvilke værdier galt hvornår) og revisionsspor (hvem har rettet hvad og hvornår). Normalt vil LESSOR-5 Inquiry returnere de gyldige værdier på forespørgsels-tidspunktet. Ønsker man de værdier der var gældende på et tidligere tidspunkt eller værdier gældende på et tidspunkt ud i fremtiden kan man tilføje parametren &lookupdate=yyyymmdd til http-url en. Man kan kun få værdierne der gælder på et givet tidspunkt, ikke de gældende værdier over en periode. Man ligeledes kun få de bedst kendte data, ikke hvad troede vi værdien var den x., dvs. der er ikke adgang til revisionssporet. LESSOR-5 - Inquiry (teknisk beskrivelse) 6/15

Definition af queries Dette vil ofte blive udført af LESSOR-konsulenten i samarbejde med kunden eller dennes eksterne konsulent. Der er intet i vejen for at kunden selv udfører arbejdet såfremt de nødvendige kvalifikationer er til stede. Denne beskrivelse giver en vejledning i hvorledes LESSOR-5 siden sættes op. Beskrivelsen er baseret på et standardsetup og kan derfor afvige i detaljerne fra den akutelle installation, men principperne vil være gældende. Da installations-directoriet kan variere fra kunde til kunde er det underforstået at der refereres relativt ud fra dette. Sti-angivelser er angivet med java- og linux-standard, mens skråstregerne skal udskiftes med back-slash es ( \ ) i windows-miljøer. Aktivering af LESSOR-5 Inquiry I misc/properties.xml skal linierne: <property name="inquiry" value="false"/>  Ændres til:  <property name="inquiry" value="c:/lessor/lessor5/misc/inquiry.xml"/> Evt. Kan den første linie slettes og kommentar-markeringen i starten og slutningen af anden linie fjernes. Vær opmærksom på at stien til inquiry.xml er korrekt! LESSOR-5 - Inquiry (teknisk beskrivelse) 7/15

Reload inquiry.xml læses ved første request til LESSOR-5 Inquiry og de nødvendige interne objekter genereres. Herefter besvares request ud fra disse objekter uden at inquiry.xml læses igen. Dette indebærer at LESSOR-5 (JBoss/WebLogic) skal genstartes såfremt ændringer i inquiry.xml skal have effekt på det kørende system. For at undgå denne service-afbrydelse kan man fra en browser eller et klient-program sende følgende URL: http://localhost:7001/lessor5/inquiry?name=reload Hvorefter man vil modtage: <?xml version="1.0" encoding="iso-8859-1"?> <reload generated="20090911120931" lookupdate="20090911" sourcesystem="lessor-5" status="0" text="inquiry.xml will be reloaded"/> Ved næste LESSOR-5 Inquiry request vil den nye definition fra inquiry.xml blive anvendt. LESSOR-5 - Inquiry (teknisk beskrivelse) 8/15

Inquiry.xml I appendix B er indsat et eksempel på en LESSOR-5 Inquiry-definition. Der er kommentarer for at lette ændringer. Filen (eller en tilsvarende) ligger standard som template_inquiry.xml og det anbefales at kopiere den til inquiry.xml og derefter anvende den som udgangspunkt. Filen kan rettes med notepad, wordpad eller en hvilken som helst anden tekst-editor. Ved at anvende en xml-editor kan man få tjekket at dokumentet har en korrekt xml-struktur. Har man ikke en i forvejen og kun har begrænset behov kan vi anbefale notepad++ der kan hentes gratis på nettet søg med google. <host ip="127.0.0.1"/> Her kan tilføjes flere ip-adresser der skal have lov til at foretage inquiry-requests: <allow default="deny"> <host ip="127.0.0.1"/>  <host ip="10.20.30.40"/> <! Kursus Server --> <host ip="0:0:0:0:0:0:0:1"/>  </allow> <query name="empbycpr"> Hver query starter med dette xml-tag og slutter med </query>. Navnet skal være unikt og det anbefales at undgå specialtegn (måske bortset fra punktum, bindestreg og underscore), herunder de Danske tegn (æøåæøå). Navnet skal angives med små bogstaver. <table name="zip" label="postdistrikt"> En query består af et eller flere tabel-opslag (der kan returnere ingen, en eller flere rækker). Er tabellerne defineret efter hinanden kommer data også efter hinanden i resultatet uden indbyrdes sammenhæng (som emppermanentpayreg og employeetaxinformation i det tidligere eksempel). Tabeller kan også defineres inden i hinanden hvorved tabel-opslaget på den indre tabel vil blive foretaget for hver række i den ydre tabel (som de to ovennævnte tabeller i forhold til employeeemployment) Ønsker man ikke at LESSOR-5 tabel-navnet anvendes som xml-tag kan man angive en label der så anvendes i stedet. <key name="dkcprnummer"/>  LESSOR-5 - Inquiry (teknisk beskrivelse) 9/15

På hver tabel vil man normalt angive en eller flere keys, der udvælger hviken række (hvilke rækker) der skal returneres. Såfremt der kun angives name vil det være det felt der skal anvendes som parameter i requesten hvis det er den yderste tabel, eller såfremt det er en indre tabel skal feltet hedde det samme i den ydre tabel idet det er værdien fra den aktuelle række der så anvendes til at afgrænse. Har felterne forskellige navne i en ydre og en indre tabel anvendes foreign-key på den indre til at angive kolonne-navnet på den ydre tabel. Ønsker man at afgrænse baseret på en konstant værdi i stedet for en parameter-værdi eller en værdi fra en anden tabel angives denne i value, formatet er det samme som beskrevet under response. rel angiver relationen mellem de to felter eller feltet og konstanten. Normalt anvendes lig, som er default og ikke behøver at angives. Man kan angive: Lig = Mindre end (<) angives i xml som < Mindre end eller lig (<=) <= Ej lig (<>) <> Større end (>) > Større end eller lig (>=) >= Man kan angive flere <key der i givet fald sættes sammen med og (and). Det er pt. ikke muligt at lave udvælgelser baseret på eller (or). Man kan godt definere det samme felt som <key.. flere gang hvis man fx ønsker et interval: <key name="code" value="1000" rel=">="/>  <key name="code" value="3000" rel="<"/>  Type anvendes i <key.. til at afgøre om der skal sættes apostroffer omkring værdierne I det genererede SQL. Det betyder at der for default typen text ikke behøver at blive angivet noget, mens den skal angives for integer, decimal og date. <field name="paytypecode"/> For hver tabel skal man angive hvilke kolonner man ønsker retur i xml-dokumentet. Såfremt man ønsker afgrænsnings-felterne retur skal disse angives både som <key.. og <field Angives blot name vil feltet blive returneret som et xml-tag med felt-navnet som navn. <xxx>værdi</xxx> Såfremt det ikke drejer sig om et tekst-felt skal man angive typen (integer, decimal eller date) for at få den korrekte formatering. LESSOR-5 - Inquiry (teknisk beskrivelse) 10/15

Ønsker man et andet navn på xml-tag et end felt-navnet kan dette angives ved hjælp af label. Hvis man ikke vil have feltet og værdien som et xml-tag, men der i mod som en attribut på tabel-tag et angives dette med attrib= true. Sættes attrib= true på alle felterne vil der kun komme en række i xml-dokumentet pr. række fra LESSOR-5 databasen. Har man brug for et felt til at afgrænse en underliggende tabel, men ikke ønsker feltet i xml-dokumentet kan output= false angives. <orderby> <field name="city"/>  <field name="code"/> </orderby> Returneres der data fra mere end en række kan/bør man specificere den ønskede rækkefølge. I modsat fald er rækkefølgen udefineret og afhængig af det anvendte database system og kan variere fra gang til gang. Et eller flere felter angives således at det første er mest betydende og så videre. Ønskes et felt sorteret i omvendt rækkefølge (fra størst til mindst) angives direction= desc. Hvis flere rækker har samme værdi i et sorterings-felt bør man angive (et) yderligere felt(er) således at sorterings-kriteriet er entydigt. Eksempelvis vil en postnummertabel sorteret på feltet city ikke være entydig da der er mange postnumre i København K. Specielle felter LESSOR-5 Inquiry udfylder et antal specielle felter som en query herved kan anvende som foreign-key i <key definitionen: now: indeholder forespørgselstidspunktet. lookupdate: indeholder den anvendte lookupdate (samme som now eller fra request). Vær opmærksom på at den indeholder seks nuller som klokkeslæt. year: det aktuelle årstal, fire cifre. LESSOR-5 - Inquiry (teknisk beskrivelse) 11/15

Appendix A - xml-response <?xml version="1.0" encoding="iso-8859-1"?> <emppay generated="20090910151217" lookupdate="20090910" sourcesystem="lessor-5" status="0" text="ok"> <employeeemployment lonnr="0315"> <emppermanentpayreg> <paytypecode>1001</paytypecode> <units>1</units> </emppermanentpayreg> <emppermanentpayreg> <paytypecode>4082</paytypecode> <units>2.17</units> </emppermanentpayreg> <employeetaxinformation> <taxyear>2007</taxyear> <taxcardtypecode>hovedkort</taxcardtypecode> </employeetaxinformation> <employeetaxinformation> <taxyear>2008</taxyear> <taxcardtypecode>hovedkort</taxcardtypecode> <incometaxrate>39</incometaxrate> <earnedincomerelief>4329</earnedincomerelief> <taxcardreceiveddate>20080219</taxcardreceiveddate> </employeetaxinformation> </employeeemployment> </emppay> LESSOR-5 - Inquiry (teknisk beskrivelse) 12/15

Appendix B inquiry.xml <?xml version="1.0" encoding="iso-8859-1"?> <inquiry> <allow default="deny"> <host ip="127.0.0.1"/>  <host ip="0:0:0:0:0:0:0:1"/>  </allow>  <query name="empbycpr"> <table name="employeebasicinformation">  <key name="dkcprnummer"/>  <field name="dkcprnummer" attrib="true"/>  <field name="firstname"/> <field name="lastname"/> <table name="employeeemployment"> <key name="employeebasicinformationcpr" foreign-key="dkcprnummer"/> <field name="code" label="employeeemploymentcode" attrib="true"/> <field name="employmentdate" type="date"/> LESSOR-5 - Inquiry (teknisk beskrivelse) 13/15

<field name="terminationdate" type="enddate"/> </table> </table> </query> <query name="emppay"> <table name="employeeemployment"> <key name="code" foreign-key="lonnr"/> <field name="code" label="lonnr" attrib="true"/> <table name="emppermanentpayreg"> <key name="employeeemploymentcode" foreign-key="code"/> <field name="paytypecode"/> <field name="units" type="decimal"/> <field name="rate" type="decimal"/> <field name="amount" type="decimal"/> </table> <table name="employeetaxinformation"> <key name="employeeemploymentcode" foreign-key="code"/> <field name="taxyear"/> <field name="taxcardtypecode"/> <field name="incometaxrate" type="integer"/> <field name="earnedincomerelief" type="decimal"/> <field name="cardwithouttax" type="decimal"/> <field name="taxcardreceiveddate" type="date"/> </table> </table> </query> <query name="zip"> LESSOR-5 - Inquiry (teknisk beskrivelse) 14/15

<table name="zip" label="postdistrikt"> <key name="country" value="dk"/> <field name="code" label="postnr"/> <field name="city" label="distrikt"/> <orderby> <field name="code"/>  </orderby> </table> </query> <query name="zip2"> <table name="zip" label="postdistrikt"> <key name="country" value="dk"/> <key name="code" value="1000" rel=">="/>  <key name="code" value="3000" rel="<"/>  <field name="code" label="postnr" attrib="true"/> <field name="city" label="distrikt" attrib="true"/> <orderby> <field name="city"/> <field name="code"/> </orderby> </table> </query> </inquiry> LESSOR-5 - Inquiry (teknisk beskrivelse) 15/15