ELEKTRONISK INDBERETNING BACKEND 6/ VERSION 1.2

Transkript

1 ELEKTRONISK INDBERETNING BACKEND 6/ VERSION 1.2

2 Indhold Indhold... 2 Introduktion... 3 Funktionalitet... 4 Moduler... 4 Opbygning af besked... 4 Eksempler... 4 Svar på besked... 5 Datatyper... 5 DataSet... 5 GUID... 5 CPR... 6 dk.hob.ei.general.plugin... 7 Metoder... 7 CancelDocument... 7 GetPrivat GetPrivat Next... 9 DeletePrivat Ex Indberet SendSystemInformation Appendix A XML beskedformat Appendix B Revisioner

3 Introduktion Backend systemet er et modulært system der står for at modtage beskeder fra frontend systemet, verificere den digitale signatur og sende beskeden videre til det rette modul. Desuden vil backend systemet returnere eventuelle svar dette modul måtte ønske til frontend systemet, hvorfra det kan hentes af en klient. Dette dokument beskriver udelukkende backend systemet i dets helhed; for beskrivelse af de tilgængelige moduler og deres metoder henvises til de rette dokumenter. For beskrivelse af hvorledes beskeder leveres til backend systemet, henvises til frontend beskrivelsen. 3

4 Funktionalitet Moduler Backenden består af en række moduler der hver især kan tilføre ekstra funktionalitet. Disse moduler har unikke navne som dk.hob.ei.general.plugin, dk.hob.ei.users.admin osv. Opbygning af besked En besked til backenden skal være i SOAP format 1 og signeret i XML 2 dsig format 3. Certifikatet med hvilket beskeden er signeret skal være et gyldigt DanID OCES certifikat 4 som har adgang til den ønskede funktionalitet. Alle oprettede brugere på systemet har adgang til modulet dk.hob.ei.general.plugin, det er derfor ikke nødvendigt at have ret hertil i rettighedssystemet. Metode navnet der kaldes er defineret som det modulets unikke navn efterfulgt af en underscore (_), efterfulgt af en af modulet defineret metode, f.eks. dk.hob.ei.general.plugin_getmydetailsex. Der henvises til de respektive modulers dokumentation for en oversigt over hvilken funktionalitet de stiller til rådighed. Eksempler Et eksempel på en besked til backenden uden argumenter, modul dk.hob.ei.general.plugin, metode GetAllGroups. <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <dk.hob.ei.general.plugin_getallgroups xmlns=" /> </soap:body> </soap:envelope> Denne signeres: <Signature xmlns=" <SignedInfo> <CanonicalizationMethod Algorithm=" /> <SignatureMethod Algorithm=" /> <Reference URI="#DataID"> <Transforms> <Transform Algorithm=" /> </Transforms> <DigestMethod Algorithm=" /> <DigestValue>dM6iBmT1gKpJ5Irk+ZAAE+H8W08=</DigestValue> </Reference> </SignedInfo> <SignatureValue>Er7UqsgIvyBNWyiY77qIH8cefYaDFLniZZBYxuDekDrVjjKD74PrlbGXZ82aOI366tvGVadE0uGmcTBiZh i0/ic5ja08usngjq/a9ngdwmlrnnpk2y1t2izdoirjuhiuxdff7phlnp4hi1pkppi5upzxqqsb1bcdmjdxu8rovgy=</signatur evalue> <KeyInfo> <KeyValue xmlns=" <RSAKeyValue> <Modulus>sses1Z7M/8AT9NkYcQ8fH9VvbKQtj8z23GRK37tCfHnVDV/8+0gcBleZqlQCEseUxaDnm+IXJaVvR3PP0rW 2kKiCQBNg5t1ca0ctpZv9Eacg+D5p03iGQRMhDmMukP9xUkWkKpqoD3GxGxMcR9uwu34KWsCob7efb1XoGpIZoxc=</Modulus> <Exponent>AQAB</Exponent> </RSAKeyValue> </KeyValue> <X509Data xmlns=" 1 SOAP / 2 xml / 3 xmldsig core / 4 4

5 <X509Certificate>MIIFNjCCBB6gAwIBAgIEPhsqOTANBgkqhkiG9w0BAQUFADA+MQswCQYDVQQGEwJESzEMMAoGA1UEC hmdverdmsewhwydvqqlexhuremgt0nfuybtexn0zw10zxn0ienbiekwhhcnmdqwmti3mdk1mte1whcnmdywmti3mtaymte1wjcbg zelmakga1uebhmcresxmjawbgnvbaotkuhpqibcvvnjtkvtuybtt0zuv0fsrsbbl1mgly8gq1zsojiwnjq2mzmwmuawfwydvqqdf BBDYXJzdGVuIFP4cmVuc2VuMCUGA1UEBRMeQ1ZSOjIwNjQ2MzMwLVJJRDoxMDUzMDE2ODA0NDg4MIGfMA0GCSqGSIb3DQEBAQUAA 4GNADCBiQKBgQCyx6zVnsz/wBP02RhxDx8f1W9spC2PzPbcZErfu0J8edUNX/z7SBwGV5mqVAISx5TFoOeb4hclpW9Hc8/StbaQq IJAE2Dm3VxrRy2lm/0RpyD4PmnTeIZBEyEOYy6Q/3FSRaQqmqgPcbEbExxH27C7fgpawKhvt59vVegakhmjFwIDAQABo4ICeDCCA nqwdgydvr0paqh/baqdagp4mcsga1udeaqkmckadziwmdqwmti3mdk1mte1woepmjawnjaxmjcxmdixmtvamiibawydvr0gbih7m IH4MIH1BgkpAQEBAQEBAQIwgecwLwYIKwYBBQUHAgEWI2h0dHA6Ly93d3cuY2VydGlmaWthdC5kay9yZXBvc2l0b3J5MIGzBggrB gefbqccajcbpjakfgnuremwawibarqbl1reqybuzxn0ienlcnrpzmlryxrlcibmcmegzgvubmugq0egdwrzdgvkzxmgdw5kzxigt 0lEIDEuMS4xLjEuMS4xLjEuMS4xLjIuIFREQyBUZXN0IENlcnRpZmljYXRlcyBmcm9tIHRoaXMgQ0EgYXJlIGlzc3VlZCB1bmRlc ibpsuqgms4xljeums4xljeums4xljeumi4wggyjyiziayb4qgenba0wc2vtcgxvewvlv2vimbuga1udeqqomaybcmnzb0bob2iuz GswgZQGA1UdHwSBjDCBiTBVoFOgUaRPME0xCzAJBgNVBAYTAkRLMQwwCgYDVQQKEwNUREMxITAfBgNVBAsTGFREQyBPQ0VTIFN5c 3RlbXRlc3QgQ0EgSTENMAsGA1UEAxMEQ1JMNjAwoC6gLIYqaHR0cDovL3JpbWZha3NlLmNlcnRpZmlrYXQuZGsvb2Nlc3Rlc3QuY 3JsMB8GA1UdIwQYMBaAFJ1WbSTx1EE9SGGGTS+dHVi7zFAcMB0GA1UdDgQWBBS4OrnBWOfuUdUMMCXhwJpzI1fztzAJBgNVHRMEA jaambkgcsqgsib2fqdbaaqmmaobbfy2ljadagooma0gcsqgsib3dqebbquaa4ibaqcvzq9jiffhxiovpdd06xkzkwxlhbldfhc1u FHpAWbQnD+gEgO9+q/RKBTp0/sTPJLGFPopGcllzLnG62xsU3w2goT8viMR3R2jeaer3uxCp+dGymYJJkQYHQHEgn/GZm/KsaHQy EAYu02rY8W63+V9IE+56vAOrHV2+t5nPmzEIRZTzs7rIkEFWWcLaTyCTwy2poV8yX9/Uv9jHzlpb1GGcp+y7/aBT9CJ3UUR7Xc61 AjN1p1qhQD4H1qUlzhrHk0pFE4I+tFdJlpXG6RPggBXY7c6pGbqC9zsxWTQs5rAWaLfwYun7q63h4IBOUgvezzdanxxA+U+kEhEK vunp513</x509certificate> </X509Data> </KeyInfo> <Object Id="DataID"> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <dk.hob.ei.general.plugin_getallgroups xmlns=" /> </soap:body> </soap:envelope> </Object> </Signature> Et eksempel på en besked med to argumenter: <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <dk.hob.ei.users.admin_getuserdetailsbycprex xmlns=" <cpr> </cpr> <includelockedusers>false</includelockedusers> </dk.hob.ei.users.admin_getuserdetailsbycprex> </soap:body> </soap:envelope> Svar på besked Når en besked behandles med prioritet ikke OneWay, vil beskeden returnere et svar der sendes videre til frontend, hvor det kan hentes af en klient. Modulmetoder der returnerer et svar, dvs. ikke har retur type void bør altså kaldes med prioritet High. Datatyper DataSet Backenden benytter XML schemas 5 til at repræsentere DataSet datatypen. GUID Backenden benytter i vid udstrækning GUID/UUID 6, der repræsenteres som en streng type i et XML schema, dog med Microsoft udvidelsen msdata:datatype=ʺsystem.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089ʺ. 5 xmlschema / 6 guid/draft leach uuids guids 01.txt samt 5

6 Klienter skal i nogle tilfælde generere GUIDs. Umiddelbart har Win32 API et metoden CoCreateGuid,.NET har System.Guid.NewGuid. Java 1.5 kan f.eks. benytte java.util.uuid eller tidligere versioner kan benytte Apache Axis 7 eller JUG 8. På Unix er det muligt at bruge OSSP uuid 9 eller libuuid fra e2fsprogs 10. GUID bliver ofte overført som streng, i disse tilfælde foregår det altid på formatet {XXXXXXXX XXXX XXXX XXXX XXXXXXXXXXXX}. Denne streng er altid med store bogstaver. CPR CPR numre er strengt taget ikke en separat datatype da CPR numre repræsenteres som en streng. CPRnumre overholder dog den konvention at de altid er på 10 tegn, dvs. uden bindestreg

7 dk.hob.ei.general.plugin Alle oprettede brugere har adgang til dette modul og er en del af standard funktionaliteten i backenden. Modulet står for generelt at modtage indberetninger og sende dem videre til det rette undermodul, samt andre generelle opgaver. Metoder CancelDocument C# : boolean CancelDocument(String documentid, String pluginname, String groupid) Denne metode annullerer en indberetning. Dokumentet bliver markeret som annulleret og ikke slettet. documentid pluginname groupid Skema id et på det dokumentet der ønskes annulleret. Navnet på det modul der skal behandle annulleringen, f.eks. dk.hob.ei.mortality.plugin Den gruppe dokumentet er tilknyttet. Denne streng er formateret som en GUID. GetPrivat C# : DataSet GetPrivat () Denne metode benyttes til at hente den private post til det signerende certifikat. Denne metode skal bruges sammen med GetPrivat Next() og DeletePrivat Ex(). Hvis der ligger rigtigt meget post til brugeren, vil det hele ikke blive returneret på én gang, men kun den første blok. Man kan se i det returneret DataSet om der er flere blokke. Hvis der er dette, så skal man kalde GetPrivat Next() indtil der ikke er flere blokke. Til sidst kalder man så DeletePrivat Ex() med de brev id er man har fået fra den sidste blok. Den sidste blok inkludere også det der er returneret fra GetPrivat () og der kun er én blok. Der returneres et DataSet hvis schema ser ud som følger: <?xml version="1.0" standalone="yes"?> <xs:schema id="newdataset" xmlns="" xmlns:xs=" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> <xs:element name="newdataset" msdata:isdataset="true" msdata:locale="en-us"> <xs:choice minoccurs="0" maxoccurs="unbounded"> <xs:element name="personpostkasse"> <xs:element name="uibrevid" msdata:datatype="system.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string" minoccurs="0" /> <xs:element name="uibrugerid" msdata:datatype="system.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string" minoccurs="0" /> <xs:element name="uibeskedtypeid" msdata:datatype="system.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string" minoccurs="0" /> <xs:element name="txfra" type="xs:string" minoccurs="0" /> <xs:element name="txemne" type="xs:string" minoccurs="0" /> <xs:element name="txbesked" type="xs:string" minoccurs="0" /> <xs:element name="dtmodtaget" type="xs:datetime" minoccurs="0" /> 7

8 <xs:element name="gruppepostkasse"> <xs:element name="uibrevid" msdata:datatype="system.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string" minoccurs="0" /> <xs:element name="txpluginnavn" type="xs:string" minoccurs="0" /> <xs:element name="txbrugernavn" type="xs:string" minoccurs="0" /> <xs:element name="txgruppenavn" type="xs:string" minoccurs="0" /> <xs:element name="uigruppeid" msdata:datatype="system.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string" minoccurs="0" /> <xs:element name="itype" type="xs:short" minoccurs="0" /> <xs:element name="txemne" type="xs:string" minoccurs="0" /> <xs:element name="txbesked" type="xs:string" minoccurs="0" /> <xs:element name="txekstrabesked" type="xs:string" minoccurs="0" /> <xs:element name="dtmodtaget" type="xs:datetime" minoccurs="0" /> <xs:element name="attachments"> <xs:element name="uilinjeid" msdata:datatype="system.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string" minoccurs="0" /> <xs:element name="uibrevid" msdata:datatype="system.guid, mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string" minoccurs="0" /> <xs:element name="txnavn" type="xs:string" minoccurs="0" /> <xs:element name="txtype" type="xs:string" minoccurs="0" /> <xs:element name="txdata" type="xs:string" minoccurs="0" /> <xs:element name="metadata"> <xs:element name="istart" type="xs:short" minoccurs="0" /> <xs:element name="iantal" type="xs:short" minoccurs="0" /> <xs:element name="istorrelse" type="xs:integer" minoccurs="0" /> </xs:choice> </xs:schema> PersonPostkasse (der en række for hvert brev) uibrevid GUID der unikt identificerer dette brev. uibrugerid uibeskedtypeid txfra txemne GUID der unikt identificerer modtageren. GUID der unikt identificerer beskedtypen. Denne benyttes primært internt i backenden til at tilbagekalde og overskrive visse typer beskeder, blandt andet notifikationer om ventende antal ubehandlede opgaver. Tekstfelt indeholdende afsenderens navn. Fritekstfelt bestemt af afsenderen. txbesked Selve beskeden i XML beskedformat, nærmere beskrevet i Appendix A. dtmodtaget Dato for modtagelsen. 8

9 GruppePostkasse (der en række for hvert brev). Der ligger skemaer her. uibrevid GUID der unikt identificerer dette brev. txpluginnavn txbrugernavn txgruppenavn uigruppeid itype txemne txbesked Det unikke navn på skema typen som dette brev indeholder. Indeholder hvem der har sendt dette skema. Navnet på gruppen som dette skema er sendt med. Gruppe ID et for ovennævnte gruppe. Gruppe typen. Se Backend Admin dokumentationen. Fritekstfelt bestemt af afsenderen. Selve skemaet som et DataSet. txekstrabesked Kan indeholde en tekst besked i XML beskedformat. Se Appendix A. dtmodtaget Dato for modtagelsen. Attachments (hvis et brev har tilknyttet en attachment, vil der blive gemt en række her. Der kan godt være flere attachments til samme brev) uilinjeid GUID der unikt identificerer denne attachment. uibrevid txnavn txtype txdata GUID der definere hvilket brev denne attachment er tilknyttet. Fritekst over hvad denne attachment indeholder. Fil extension typen, f.eks. txt eller htm. Selve attachment data gemt i base64 encoding. MetaData (bliver brugt til at fortælle om der er flere breve som der skal hentes. Der vil være en række for hver blok, dvs. at hvis der er 3 blokke i alt, vil der være 3 rækker i denne tabel, hvor den første række indikere den blok som lige er blevet hentet ned) istart Brev nummer som denne blok starter med. iantal istorrelse Antal af breve i denne blok. Samlet størrelse i bytes af denne blok. GetPrivat Next C# : DataSet GetPrivat Next(String[] privateletters, String[] groupletters) Dette kald vil hente den næste blok af breve ned. Derudover vil den også slette de breve som der er givet ind som argument. Se DeletePrivat Ex() for en beskrivelse af argumenterne. 9

10 Det DataSet som der bliver returneret er det samme som GetPrivat () returnere. Bemærk dog, at MetaData tabellen vil indeholde en række mindre for hvert kald. DeletePrivat Ex C# : void DeletePrivat Ex(String[] privateletters, String[] groupletters) Denne metode sletter de angivne private beskeder hvor modtager er certifikatet med hvilket dette kald er signeret. Bemærk, at denne besked skal sendes med prioritet OWAdmin og ikke som Hi. privateletters groupletters Angiver hvilke beskeder der ønskes slettet. Dette er en liste med de brev id er som der skal slettes. Angiver hvilke gruppe beskeder der ønskes slettet. Der kan kun angives gruppe beskeder som ligger en brugeres egen private gruppe. Indberet C# : void Indberet(String letterid, String pluginname, String groupid, String subject, String document) Denne metode benyttes til generelt at indberette data. Indberetteren, dvs. det certifikat der har signeret metode kaldet, skal have adgang til modulet pluginname og modulet pluginname hvor sidste led er erstattet af Indberetning, f.eks. dk.hob.ei.mortality.plugin og dk.hob.ei.mortality.indberetning. Hvis dette ikke er opfyldt, vil indberetteren modtage en besked om dette gennem postsystemet, og hvis dette fejler, vil administratoren blive underrettet. Indberetningen valideres desuden mod modul specifikke kriterier, hvis disse ikke er opfyldt vil indberetningen fejle og sendes retur til indberetteren eller videre til den tilknyttede koder som defineret af indberetningshandlingerne. letterid pluginname groupid subject document Sættes til null, med mindre indberetningen oprindeligt er tilknyttet et brev, i så fald er det brevets id. Denne streng er formateret som en GUID. Navnet på det modul der skal behandle indberetningen, f.eks. dk.hob.ei.mortality.plugin Den gruppe dokumentet er tilknyttet. Denne streng er formateret som en GUID. Hvis indberetningen medfører afsendelse af post, benyttes denne streng som emne. Selve dokumentet der indberettes. Se det relevante dokument for beskrivelse af denne streng. SendSystemInformation C# : void SendSystemInformation(DataSet info) 10

11 Denne metode bruges til at sende information til systemadministratoren om afsenderens systemkonfiguration. Det kræves at DataSettet benytter følgende schema: <?xml version="1.0" standalone="yes"?> <xs:schema id="sysinfo" xmlns="" xmlns:xs=" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> <xs:element name="sysinfo" msdata:isdataset="true" msdata:locale="da-dk"> <xs:choice maxoccurs="unbounded"> <xs:element name="program"> <xs:element name="txnavn" type="xs:string" minoccurs="0" /> <xs:element name="txversion" type="xs:string" minoccurs="0" /> <xs:element name="ipatch" type="xs:int" minoccurs="0" /> <xs:element name="providers"> <xs:element name="txnavn" type="xs:string" minoccurs="0" /> <xs:element name="txversion" type="xs:string" minoccurs="0" /> <xs:element name="system"> <xs:element name="txnavn" type="xs:string" minoccurs="0" /> <xs:element name="txversion" type="xs:string" minoccurs="0" /> <xs:element name="iservicepack" type="xs:int" minoccurs="0" /> <xs:element name="plugins"> <xs:element name="txnavn" type="xs:string" minoccurs="0" /> <xs:element name="txversion" type="xs:string" minoccurs="0" /> <xs:element name="components"> <xs:element name="txnavn" type="xs:string" minoccurs="0" /> <xs:element name="txversion" type="xs:string" minoccurs="0" /> <xs:element name="processes"> <xs:element name="txnavn" type="xs:string" minoccurs="0" /> <xs:element name="ihukommelse" type="xs:int" minoccurs="0" /> <xs:element name="ivirtualhukommelse" type="xs:int" minoccurs="0" /> <xs:element name="logfileszipped"> <xs:element name="txlog" type="xs:string" minoccurs="0" /> </xs:choice> </xs:schema> 11

12 Program txnavn txversion ipatch Klientens navn. Klientens version. Klients patch niveau. Providers txnavn txversion Database providerens navn. Database providerens version. System txnavn txversion Operativsystemets navn. Operativsystemets versionsnummer. iservicepack Operativsystemets patch niveau. Plugins txnavn txversion Modulets unikke navn. Modulets version. Components txnavn Komponentens filnavn. txversion Komponentens version. Processes txnavn Processens navn. ihukommelse ivirtualhukommelse Processens benyttede hukommelse. Processens benytted virtuelle hukommelse. LogFilesZipped txlog Alle log filer er appended sammen og encoded med UTF 8. Bagefter er den samlet tekst pakket med Gnu Zip (gz). Det pakket resultat er gemt som en enkelt række med base64 encoding. 12

13 Appendix A XML beskedformat <!DOCTYPE mail [ <!ELEMENT mail (text*,plugin*)> <!ATTLIST mail id CDATA #REQUIRED> <!ATTLIST mail title CDATA #REQUIRED> <!ELEMENT text (#PCDATA)> <!ATTLIST text italic (yes no) "no"> <!ATTLIST text underline (yes no) "no"> <!ATTLIST text bold (yes no) "no"> <!ELEMENT plugin (#PCDATA)> <!ATTLIST plugin change CDATA #IMPLIED> ]> 13

14 Appendix B Revisioner 1.0 Første udgave 1.1 Tilføjet revisionsafsnit. CancelDocument dokumenteret. DeletePrivat dokumenteret. GetAllGroups dokumenteret. GetPrivat dokumenteret. SendSystemInformation dokumenteret. XML beskedformat dokumenteret. Fjernet sætning omkring felter der skal initialiseres ved kald af Indberet, da disse alligevel overskrives og er modulspecifikke. Dokumenteret at der foregår automatisk validering. Eksempel på SOAP besked og signeret SOAP. 1.2 Fået opdateret dokumentationen til hvordan verden ser ud i dag. Fået fjernet obsolete kald og erstattet dem med nye kald. 14