Digital post Integration for virksomheder Via sikker og REST Version 6.4

Transkript

1 Digital post Integration for virksomheder Via sikker og REST Version 6.4 1

2 Indholdsfortegnelse G.1 INTRODUKTION 4 G.1.1 OVERBLIK OVER HVORDAN DIGITAL POST KAN TILGÅS 4 G.1.2 FLOW SOM EN DIGITAL FORSENDELSE GENNEMLØBER 5 G.1.3 METADATA (ATTENTIONFORMAT / SAGDOKUMENT) 6 G.1.4 FYSISK STØRRELSE PÅ POST 7 G.1.5 KONFIGURATION SLÅR IGENNEM FOR BÅDE OFFENTLIGE OG PRIVATE AFSENDERE 8 G.2 AUTOMATISK VIDERESENDELSE 8 G.2.1 INDHOLDET DER FREMSENDES 8 G.2.2 KONFIGURATION AF AUTOMATISK VIDERESENDELSE 8 G.3 SYSTEMINTEGRATION VIA WEBSERVICE 9 G.3.1 OVERSIGT OVER FUNKTIONSOMRÅDET FEJL! BOGMÆRKE ER IKKE DEFINERET. G KVITTERING FOR MODTAGELSE / IDEMPOTENT 9 G GENUDSENDELSESMEKANISME VED SERVICEVINDUE 9 G RESSOURCEOVERSIGT 10 G.3.2 EKSEMPEL PÅ XML 11 G.3.3 XSD-SKEMAER OG TEGNSÆT 11 G.3.4 KONFIGURATION AF WEBSERVICE 12 G.3.5 SIKKERHED 12 G.3.6 FREMSENDELSE AF TESTMEDDELELSE TIL SERVICEN SOM URL EN PEGER PÅ 13 G.3.7 REFERENCEIMPLEMENTERING 13 G.3.8 OPERATIONER 14 G MODTAG EN FORSENDELSE 14 G.3.9 RESSOURCER 15 G MEDDELELSE 15 G VEDHAEFTNINGSAMLING 16 G VEDHAEFTNING 16 Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 2

3 Versionshistorik Version Udgivelsesdato Ændringer 6.4 Første udgivelse. Vejledningen er blevet til på baggrund af snitfladen REST Afhentningssystem, hvor alt vedrørende hvordan virksomheder kan modtage post fra indbakken via systemkald er flyttet til dette dokument. En beskrivelse af automatisk videresendelse er tilføjet. Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 3

4 G.1 Introduktion Denne beskrivelse henvender sig til virksomheder, der har behov for at få overført digitale post fra deres digitale postkasse til egne systemer, heriblandt løsninger. G.1.1 Overblik over hvordan digital post kan tilgås Fra den dag hvor det er obligatorisk at modtage post fra det offentlige digitalt vil alle virksomheder som udgangspunkt have en digital postkasse, hvortil post fra det offentlige bliver fremsendt. Det er virksomhedens ansvar at tilgå denne post. Nedenfor er vist en oversigt over de forskellige måder hvorpå jeres virksomhed kan vælge at tilgå den digitale post samt de fordele og begrænsninger der er ved hver løsning. Adgang til digital post Fordele og begrænsninger (A) Via virk.dk / e-boks.dk ved anvendelse af standardfunktionalitet Adgang til læse og besvare digital post. Opsætning af advisering når ny post ankommer. Opsætning af arkiveringsregler, der automatisk flytter posten til en mappe. Tildeling af begrænset / fuld adgang til eksterne brugere, eksempelvis revisor. Myndighedspåførte metadata er kun i begrænset omfang tilgængelige. (B) Via virk.dk / e-boks.dk ved anvendelse af udvidet funktionalitet Som standard plus Adgang til udvalgt post for udvalgte medarbejdere Kræver en postfordeler som fordeler posten (C) Via automatisk videresendelse til sikker Al post bliver videresendt til en konfigureret adresse Posten bliver liggende i den digitale postkasse Myndighedspåførte metadata er tilgængelige i XML. Egenudviklede løsninger kan stå for videredistribution og journalisering på baggrund af eventuelle metadata. Forsendelsestypen er alene tilgængelig i tekstform. Det er ikke muligt at besvare post. Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 4

5 (D) Via systemintegration, dvs. webservice (REST/XML) Al post bliver videresendt til en konfigureret URL end point Posten bliver liggende i den digitale postkasse Standardmetadata såsom navnet på afsender er tilgængelig Myndighedspåførte metadata er tilgængelige i XML. Egenudviklede løsninger kan stå for videredistribution og journalisering på baggrund af eventuelle metadata. Forsendelsestypen er alene tilgængelig i tekstform. Det er ikke muligt at besvare post. Formålet med denne vejledning er at uddybe mulighederne (C) og (D). Det skal bemærkes at uanset hvilken af disse integrationsformer der vælges forbliver posten i den digitale postkasse og det er muligt at på et senere tidspunkt at logge på virk.dk / e-boks.dk og tilgå den tidligere digitale post. Sammenfattet kan det opsummeres, at den primære forskel mellem mulighed (C) og (D) er hvorvidt integrationsformen rent teknisk sker via en løsning (S/MIME) eller via webservice (REST). Konkret er den eneste forskel at der via mulighed (D) er adgang til navnet på den afsendende myndighed, hvilket ikke er tilfældet i mulighed (C). Er en virksomhed også tilmeldt e-boks erhverv, så vil al den post virksomhederne modtager fra private afsendere også blive videresendt. Dette sker også selv om post fra private afsendere ikke vises i Digital Post på Virk.dk. Når der i denne vejledning refereres til virksomheder, inkluderer det også myndigheder, der optræder som slutbrugere og har behov for at tilgå deres digitale postkasse. G.1.2 Flow som en digital forsendelse gennemløber Hvad sker der fra en forsendelse forsøges afleveret af en myndighed til at den modtages af en virksomhed? Dette besvares lidt forsimplet i det følgende: 1. En myndighed ønsker at aflevere en forsendelse til en virksomhed og skal afgøre hvorvidt forsendelsen kan afleveres i virksomhedens digitale postkasse. 2. Indtil det er blevet obligatorisk at modtage digital post er det frivilligt for virksomheder at tilmelde sig. Efter at det er blevet obligatorisk kan en virksomhed under specielle omstændigheder undtagelsesvist blive fritaget midlertidigt. 3. Såfremt virksomheden er tilmeldt og ikke er fritaget kan myndigheden nu aflevere forsendelsen digitalt ved at angive CVR-nummeret på modtageren. Myndigheden kan vælge at påføre andre metadata såsom P-nummer samt eventuelt berige meddelelsen med egne sags-oplysninger såsom sagstype, dokumenttype, matrikelnummer eller nummerplade for blot at nævne nogle muligheder. 4. Forsendelsen modtages i virksomhedens digitale postkasse. Såfremt virksomheden har konfigureret at automatisk videresendelse eller systemintegration via webservice ønskes vil meddelelsen blive leveret som efterspurgt. Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 5

6 5. Her forudsættes, at virksomheden har konfigureret deres digitale postkasse til at al post skal forsøges afleveret til en webservice, som virksomheden selv udstiller. Hele forsendelsen inklusive vedhæftninger og metadata vil da blive forsøgt afleveret som en samlet operation. 6. Webservicen, som virksomheden udstiller, skal være i stand til at kunne modtage OIOXML ressourcen Meddelelse. Dette er et XML-dokument, der beskriver hele forsendelsen inklusiv hoveddokument samt eventuelle vedhæftninger og metadata. 7. Virksomheden eller dennes leverandør kan selv implementere logik, der gør det muligt at opsætte egne regler for håndtering, behandling og journalisering af post afhængig af oplysningerne, der er tilgængelige i forsendelsen. G.1.3 Metadata (Attentionformat / Sagdokument) Den afsendende myndighed kan vælge at berige en forsendelse med metadata. Dette kan ske via nedenstående to vedhæftede XML filer. Det er op til hver enkelt myndighed at vurdere om de vil anvende denne mulighed og i hvilket omfang. Det må forventes at omfanget løbende bliver udvidet. attention.xml. En vedhæftning som myndigheden kan vælge at vedlægge i forbindelse med aflevering af en meddelelse. Filen modsvarer attentionfeltet på et traditionelt fysisk brev. Det afhænger af den enkelte myndighed hvorvidt filen er medtaget samt hvad den indeholder. Filen kan bl.a. indeholde p-nummer via feltet ProductionUnitIdentifier. Filen indeholder OIOXML-ressourcen AttentionFormat. Bemærk, at filen ikke bliver skemavalideret i forbindelse med modtagelsen i digital post. Det er derfor vigtigt at den service som virksomheden udstiller, er i stand til at modtage en forsendelse på trods for, at denne fil ikke kan skemavalideres. Nedenfor fremgår opbygningen af ressourcen. Specielt skal det bemærkes, at det er muligt at angive en adresse på slutmodtageren samt at elementet AttentionObjektSamling kan indeholde vilkårlige nøgle-værdi-par, som den enkelte myndigheden tilbyder. Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 6

7 Nedenfor er vist et fiktivt eksempel på hvordan XML kunne se ud. Eksemplet viser en henvendelse til Digitaliseringsstyrelsen hvor P-nummer er angivet samt ekstra metadata som beskriver indholdet af dokumentet. sagdokument.xml. En vedhæftning, som er beregnet til struktureret beskrivelse af indholdet af meddelelsen. Digital post anvendes blot som transportmedie og forholder sig ikke til indholdet af denne fil. Filen indeholder OIOXML-ressourcen Sagdokument. Det skal bemærkes at filen ikke er blevet skemavalideret ved modtagelse i digital post og virksomhedens service, der modtager en forsendelse, ikke må fejle på trods for at filen ikke kan skemavalideres. Ovenstående metadata vil være tilgængelig uanset om der vælges automatisk videresendelse eller meddelelsen afleveres via webservice. Det er muligt at læse mere om ovenstående på digitaliseringsstyrelsens hjemmeside. Området benævnes under et for Attentionformat. G.1.4 Fysisk størrelse på post Digital post vil som udgangspunkt ikke overstige nedenstående begrænsninger. Samlet størrelse - 10 Mb. Størrelsen af hoveddokument + vedhæftninger (incl. metadata) vil normalt ikke overstige denne grænse. Maksimale antal vedhæftninger - 10 vedhæftninger. Metadatafiler, som også er vedhæftninger, er inkluderet i denne grænse. Bemærk, at dertil kommer at både kryptering og signering af et dokument forøger størrelsen med ca. 1/3 hver. Det betyder at det antal bytes, der modtages vil være noget større som følge heraf (78%). Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 7

8 G.1.5 Konfiguration slår igennem for både offentlige og private afsendere Virksomhedens digitale postkasse kan tilgås både fra virk.dk under digital post og/eller via e- Boks. Uanset hvorfra virksomhedens digitale postkasse tilgås, er det den samme postkasse, der konfigureres. Med andre ord slår konfigurationen igennem begge steder uanset hvorfra konfigurationen sker og vil virke for både post fra offentlige afsendere såvel som private afsendere virksomheden har tilmeldt sig. G.2 Automatisk videresendelse G.2.1 Indholdet der fremsendes Digital post som afleveres til en digitale postkasse, der har opsat automatisk videresendelse til en adresse vil blive forsøgt videresendt den angivne adresse. en har følgende karakteristiks: Afsenderen er Af emnefeltet fremgår navnet på den afsendende myndighed samt titlen på meddelelsen. Hvis hoveddokumentet ikke er formateret som HTML eller ren tekst vil det være vedlagt som en vedhæftning. Samtlige vedhæftninger vil være vedlagt. Eventuelle påhæftede metadata fra myndigheden, dvs. attentionformattet (attention.xml) og/eller oplysninger om sagen (sagdokument.xml), vil være vedlagt. G.2.2 Konfiguration af automatisk videresendelse I den digitale postkasse, hvad enten den tilgås fra virk.dk eller e-boks.dk, under indstillinger vælges menupunktet videresendelse. Herfra kan vælges Opret videresendelse hvorved nedenstående skærmbillede fremkommer. Ovenfor skal angives den adresse hvortil post skal videresendes samt uploades det tilhørende certifikat. Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 8

9 G.2.3 Genudsendelsesmekanisme Ved automatisk videresendelse af en forsendelse via , hvor modtagerens system ikke svarer, gentages forsøg på forsendelse efter følgende genudsendelsesmønster. Første genudsendelse efter 3 min. Anden genudsendelse efter 10 min Tredje genudsendelse efter 20 min Herefter forsøges genudsendt efter 30 min og efterfølgende hver 10 minut i 10 timer. Herefter oprettes en notifikation i slutbrugergrænsefladen om at meddelelse ikke kan sendes og der foretages ikke yderligere. G.3 Systemintegration via webservice Ved integration via webservice skal virksomheden udstille en webservice, som vil blive kaldt når der er ny post til virksomheden. Myndigheden/virksomheden kan således via et eksternt system løbende modtage meddelelser. I det følgende beskrives hvordan levering kan garanteres samt information om de data der udveksles. G Kvittering for modtagelse / idempotent Hvis en meddelelse afleveres til den angivne URL og servicen som URL en peger på modtager meddelelsen, men det succesfulde retursvar ikke når at blive returneret på grund af tekniske problemer, vil meddelelsen blive forsøgt leveret igen indtil servicen returnerer med et positivt retursvar. I ovenstående situation er det afgørende, at servicen på trods for at meddelelsen tidligere er modtaget succesfuldt returnerer med en succesfuld bekræftelse for modtagelsen igen (httpstatuskode 200). Dette designprincip kaldes idempotent og er medvirkende til at garantere sikker levering. G Genudsendelsesmekanisme ved servicevindue Hvis den service som URL en peger på af en eller anden grund ikke svarer, eksempelvis som følge af et servicevindue, så starter følgende genudsendelsesmekanisme. 1. Det første døgn forsøges meddelelsen afleveret med en høj frekvens. 2. Fra dag 2. optræder en advarsel såfremt en bruger logger på løsningen, som informerer om at levering ikke var mulig. 3. Fra dag 2. og til og med dag 30. forsøges meddelelsen genleveret en gang i døgnet. Der bliver samtidig udsendt en til den adresse der er angivet på afhentningssystemet, som informerer om problemet. 4. Dag 31. Levering opgives og der advares herom ved logon på løsningen. I denne situation vil der optræde en knap genudsend som gør det muligt at bestille en genudsendelse. Alle meddelelser, der ikke er modtaget en succesfuld kvittering for ved aflevering, vil da blive forsøgt genleveret i løbet af de kommende 24 timer. Digital post Snitflader - Bilag A6: REST Modtagelse af post 6.4 9

10 G Ressourceoversigt Ressourcer er OIOXML dataobjekter der udveksles. Nedenstående oversigt beskriver de forskellige OIOXML ressourcer der indgår og deres sammenhæng. Servicen modtager en Meddelelse som kan indeholde vedhæftninger. MeddelelseReferenceSamling Meddelelse MeddelelseFESDmetadata VedhaeftningSamling PostkasseMetadata Signaturbevis Vedhaeftning AfsenderMetadata Ressourcer er rodobjekter i modsætning til typer som skal inkluderes i andre rodobjekter. Ressourcer er vist med fuldt optrukken kant, og typer er vist med stiplet kant. En reference fra en ressource til en anden ressource er vist med en fuldt optrukken pil. En stiplet pil viser at en type eller ressource er inkluderet som en del af en anden type eller ressource. Samtlige ressourcer og typer har tilknyttet et XSD skema. Indholdet af hver ressource og type, dvs. de enkelte XML elementer, fremgår af en tabel i det følgende. Det er ikke alle ressourcer der er tilgængelige når meddelelsen modtages som slutbruger. De pågældende ressourcer er nævnt nedenfor. Meddelelse Indeholder information om en meddelelse, heriblandt afsender, titel, modtagelsestidspunkt, selve det binære indhold samt evt. vedhæftninger og deres indhold. VedhaeftningSamling Beskriver en liste af vedhæftninger Vedhaeftning Beskriver en vedhæftning, heriblandt titel, format, samt en reference til det binære indhold. Specielt vil de nævnte metadata optræde som vedhæftede filer. Digital post Snitflader - Bilag A6: REST Modtagelse af post

11 G.3.2 Eksempel på XML Nedenfor er vist et eksempel på XML, som vil kunne blive afleveret til servicen. G.3.3 XSD-skemaer og tegnsæt XML en der udveksles er underlagt OIOXML standarden. Denne standard har til formål at ensarte navngivningen af felter der indgår XML en der udveksles samt stiller krav til genbrug af tidligere specifikationer i det om fang de findes og er dækkende. Den OIOXML ressource, der leveres til servicen er navngivet meddelelse og er underlagt et XSD skema som er tilgængeligt på digitaliser.dk: Indholdet af brevet samt indholdet af hver vedhæftning er base64 encoded. Alle XML dokumenter samt det base64 kodede indhold, er i formatet UTF8. Digital post Snitflader - Bilag A6: REST Modtagelse af post

12 G.3.4 Konfiguration af webservice I den digitale postkasse, hvad enten den tilgås fra virk.dk eller e-boks.dk, under indstillinger vælges menupunktet videresendelse. Herfra kan vælges Opret afhentningssystem hvorefter nedenstående skærmbillede fremkommer. Oplysninger der skal angives til konfigurationen: 1. URL: angiver end point på den service, der skal kaldes. 2. Kontaktoplysninger: specielt anvendes adressen til at informere om problemer med aflevering til servicen. Det er vigtigt at holde adressen under kontaktoplysninger opdateret, da den anvendes til at orientere om post ikke kan afleveres. G.3.5 Sikkerhed Webservicen skal være konfigureret til at anvende HTTPS. Servicen bør validere klientcertifikatet, dvs. sikre at det er e-boks der foretager kaldet, og at alle andre der måtte kalde ignoreres. Digital post Snitflader - Bilag A6: REST Modtagelse af post

13 G.3.6 Fremsendelse af testmeddelelse til servicen som URL en peger på Under udvikling i integrationstestmiljøet er det muligt at foretage testforsendelser via knappen test. Herved vil en testmeddelelse blive forsøgt leveret til den service URL en peger på, og httpstatuskoden, der blev returneret, vil fremgå så snart den er tilgængelig. G.3.7 Referenceimplementering Der er udarbejdet en referenceimplementering i.net (C#), som viser hvordan en service kan implementeres. Referenceimplementeringen er udarbejdet som et eksempel og dermed som hjælp til at komme i gang ikke som en service der er egnet til produktionsmiljøer. Referenceimplementeringen indeholder en testservice, der lytter efter meddelelser. Det vises hvordan meddelelsen modtages, heriblandt håndtering af encoding og opsplitning i vedhæftninger. Resultatet gemmes i et bibliotek per meddelelse, som indeholder hoveddokument og eventuelle vedhæftninger. Referenceimplementeringen, inklusiv en vejledning i hvordan den installeres, kan hentes som en ZIP-fil under punktet læs mere om videresendelse, der hvor afhentningssystemet sættes op på Virk.dk. Digital post Snitflader - Bilag A6: REST Modtagelse af post

14 G.3.8 Operationer Servicen, som virksomheden udstiller, skal kunne håndtere følgende kald. G Modtag en forsendelse URL konfigureret i den digitale postkasse Formål PUT Anvendes af virksomheder til at modtage meddelelser via systemkald fra deres indbakke. Virksomheden skal udstille en service der overholder følgende. Idempotent Hver meddelelse kan unikt identificeres via MeddelelseURLreference som er defineret i meddelelsen. Såfremt den samme meddelelse modtages flere gange er det afgørende at der ved efterfølgende modtagelse returneres med http status koden 200 som angiver succesfuld modtagelse, idet forsendelsen ellers vil blive forsøgt leveret igen og igen via genudsendelsesmekanismen. Input content (OIOXML) Meddelelse Ressourcen, der er afleveret i virksomhedens digitale postkasse som forsøges afleveret. Http svar 200 Succes. Skal returneres efter at data er persisteret lokalt og tjener som afslutning på transaktionen. Digital post Snitflader - Bilag A6: REST Modtagelse af post

15 G.3.9 Ressourcer Samtlige ressourcer for funktionsområdet er dokumenteret i det følgende. Hver ressource modsvares af et XSD skema af samme navn. G Meddelelse Meddelelse Formål RESSOURCE Ressourcen indeholder informationer om en meddelelse heriblandt dokumenter og NemSMS er. R MeddelelseURLreference Reference til meddelelsen. R MeddelelseTypeNavn Vil altid være Meddelelse. R AfsenderNavn Afsenderens navn. R Signaturbevis Ikke udfyldt. R MeddelelseServicebeskedTekst Ikke udfyldt. R MeddelelseTitelTekst Emnet som henvendelsen drejer sig om. R MeddelelseIndholdData Selve det binære indhold af meddelelsen indkodet i Base64 formatet. R FilformatNavn Angiver formatet af meddelelsens indhold. R IndholdsdataStoerrelseMaal Størrelsen på indholdet af meddelelsen i kilobytes før Base64 encoding. R MeddelelseTraadIdentifikator Såfremt meddelelsen er en del af en dialog, så angives her en pågældende dialog. Er kun inkluderet for Afhentningssystemer tilhørende myndigheder. R MeddelelseModtagetDatoTid Modtagelsestidspunktet. R VedhaeftningSamling Liste af vedhæftninger. R PostkasseMetadata Ikke udfyldt. R MeddelelseFESDmetadata Ikke udfyldt. R MeddelelseTidsfristDato En dato som angiver at der er en tidsfrist forbundet med meddelelsen. R MeddelelseTidsfristTekst Et notat som afsender kan tilknytte til afsendelsen. Eksempelvis til at beskrive tidsfristen. Digital post Snitflader - Bilag A6: REST Modtagelse af post

16 G VedhaeftningSamling VedhaeftningSamling Formål TYPE Typen indeholder en liste informationer om vedhæftede dokumenter eller bilag. Indeholder en liste af typen Vedhaeftning G Vedhaeftning Vedhaeftning Formål TYPE Typen indeholder information om en vedhæftning, inklusiv reference til selve indholdet et dokument eller bilag. R VedhaeftningNavn Navnet på dokumentet. File extension fremgår af FilformatNavn. R VedhaeftningIndholdData Selve indholdet af vedhæftningen indkodet i Base64 formatet. R FilformatNavn Angiver formatet på vedhæftningens indhold. Formatnavnet er endelsen af det filnavn, som man ville give indholdet skulle det gemmes som en fil. F.eks. pdf, docx. R IndholdStoerrelseMaal Størrelsen af filen i kilobytes før Base64 encoding. R MIMEcontentIdentifikator Vedhæftninger i en S/MIME afsendelse bliver tildelt en MIME Content-ID, således at der i teksten i afsendelsen kan refereres til vedhæftninger, f.eks. ved indlejring af billeder i teksten. For at kunne genskabe denne afsendelser med indlejrede vedhæftninger, bliver Content-ID bevaret og er tilgængelig via dette felt. R R R VedhaeftningOprindelig AfsenderNavn VedhaeftningOprindelig ModtagetDatoTid VedhaeftningOprindelig AfsenderCVRnummer Identifikator Ikke udfyldt. Ikke udfyldt. Ikke udfyldt. Digital post Snitflader - Bilag A6: REST Modtagelse af post