Leverandørguide til Digital Post 2

Transkript

1 Leverandørguide til Digital Post 2

2 Indholdsfortegnelse 1.1 Målgruppe Formål Forudsætninger Integrationstestmiljø Certifikater Adgang til konfiguration via systemkald Referenceimplementering Hvordan afgøres det nemmest hvorvidt vi har hul igennem til Digital Post REST? Myndighed afleverer meddelelse til slutbruger Slutbruger besvarer henvendelse fra myndighed myndighed afhenter Myndighed besvarer henvendelse fra slutbruger Afsende meddelelse med åbningskvittering Modtagelse af åbningskvitteringssvar Afsend meddelelse til slutbruger der kan besvares via formular Myndighed modtager henvendelse fra slutbruger Afsend meddelelse til flere slutbruger Myndighed tømning af sin virksomhedsindbakke Fejlsøgning Versionshistorik Version Dato Beskrivelse / Initial version 1

3 1 Indledning 1.1 Målgruppe Målgruppen for denne vejledning er systemarkitekter hos myndigheder samt myndighedernes leverandører som ønsker en indføring i hvilke integrationsmuligheder Digital Post tilbyder. 1.2 Formål Formålet med vejledningen er at sætte læseren i stand til hurtigt at forstå de primære integrationsscenarier som Digital Post-løsningen muliggør. Vejledningen fungerer som overblik og indgang til de snitfladebeskrivelser, som leveres med løsningen. Denne vejledning er udarbejdet af e-boks og supplerer og understøtter vejledninger udarbejdet af Digitaliseringsstyrelsen. Digitaliseringsstyrelsens vejledninger er tilgængelige på Digitaliseringsstyrelsens hjemmeside under Digital Post ( 1.3 Forudsætninger Vejledningen anvender en række termer der er unikke for Digital Post som med fordel kan læses indledningsvist. Se dokumentet Digital post - Snitflader v7.0, kapitel 3 Begrebsliste. Snitfladerne er tilgængelige via følgende links: Snitflade version 6.3: Snitflade version 7.0: Når der i det følgende omtales slutbrugergrænsefladen henvises der til slutbrugernes, dvs. hver enkelt borger og virksomheds sikre webbaserede digitale postkasse. 1.4 Integrationstestmiljø Digital Post stiller et integrationstestmiljø til rådighed således at funktionalitet kan udvikles og testes før det porteres til produktionsmiljøet. Snitfladen dokumenterer URL er og adresser for miljøerne. 2 Konfiguration der foretages af myndigheden via administrationsportalen Før myndigheder kan afsende og modtage meddelelser via Digital Post løsningen, er det nødvendigt for myndigheden at foretage diverse konfigurationer. De følgende integrationsscenarier vil hver i sær opremse hvad der som minimum er påkrævet at opsætte for at det pågældende scenarie kan realiseres. Al opsætning og konfiguration af produktionsmiljøet foretages af myndigheden via den web-baserede grænseflade kaldet administrationsportalen. I integrationstestmiljøet kan myndigheden give leverandøren adgang til administrationsportalen. Bemærk På digst.dk/digitalpostvejledninger kan myndigheden med fordel starte med vejledningen 2

4 Hurtigt i gang med administrationsportalen, der er tilgængelig fra forsiden. Derudover er der i administrationsportalen for hvert funktionsområde detaljerede hvordan oprettes guides. 2.1 Certifikater I forbindelse med opsætning af systemintegration skal der i alle tilfælde konfigureres et certifikat bortset fra når myndighed ønsker at modtage meddelelser fra slutbrugere via REST PUSH. Når et system skal konfigureres hvor et certifikat skal uploades gælder følgende: Certifikatet skal være et OCES-certifikat af typen virksomheds- eller funktionscertifikat. For integration via sikker kan medarbejdercertifikater endvidere anvendes. Konkret skal certifikatet eksporteres med den offentlige nøgle og gemmes i base-64 format førend det kan uploades i administrationsportalen. 2.2 Adgang til konfiguration via systemkald Det er alene myndigheden der kan foretage konfigurationen i produktionsmiljøet. Erfaringsmæssigt kan det være tidskrævende og fejlbehæftet for myndigheden og dennes leverandør at synkronisere de oplysninger myndigheden har konfigureret med leverandørens systemer, ikke mindst da værdierne er forskellige i integrationstest- og produktionsmiljøet. For at afhjælpe dette kan leverandøren i stedet foretage API-kald, som gør leverandøren i stand til via systemkald at hente de af myndigheden konfigurerede værdier. Specielt kan materialer og postkasser tildeles et alias, som kan gøres konstant på tværs af miljøer. Leverandøren kan da tilføje simpel logik der omsætter dette alias til den aktuelle værdi i det aktuelle miljø. Bemærk Leverandøren kan hente alle konfigurationsindstillinger per afsender og afhentningssystem via REST baserede systemkald. Se Bilag A1 - REST - Afsendersystem v7.0, afsnit A1.2.6 Hent konfigurationsindstillinger og Bilag A3 - REST - Afhentningssystem v7.0, afsnit A3.3.1 Hent kontakthierarki (ID - A3.3.8) for detaljer. 2.3 Referenceimplementering Fra forsiden i administrationsportalen kan en ZIP-fil indeholdende en referenceimplementering downloades; referenceimplementering er skrevet i.net (C#). Zip-filen indeholder kildekode og en beskrivelse af hvordan servicen installeres. Dette kan være en genvej til hurtigt at komme i gang 3 Afklaring af integrationsform Digital Post stiller en række snitflader til rådighed, som kan anvendes efter behov: REST, S/MIME, filbaseret og printfiler. Valget mellem de forskellige snitflader vil typisk afhænge af leverandørens eksisterende tekniske infrastruktur. Og i nogle tilfælde vil der være behov for at anvende flere. Eksempelvis for ad hoc baseret S/MIME forsendelse hvor det er nødvendigt at undersøge om individuelle slutbrugere er tilmeldt via REST kald (af hensyn til at afdække at slutbrugeren ikke er fritaget). 3

5 Snitfladerne er beskrevet i dokumentet Digital post - Snitflader v7.0 ; desuden findes bilag A1, A2, A3, A4, A5, B, C og D som er referencedokumentation for hver af snitfladerne. Uanset hvilken integrationsform der vælges, er de metadata der udveksles de samme, det er alene indpakningen der er forskellig. Af hensyn til læsbarheden er integrationsformen REST valgt i de følgende eksempler som illustration af hvilke data der udveksles. 4 Grundlæggende vilkår og forudsætninger I det følgende beskrives forskellige integrationsscenarier. Hovedparten af scenarierne har forudsætninger og er underlagt generelle vilkår, som gør sig gældende uanset hvilken snitflade der anvendes. Disse vilkår er beskrevet i dokumentet Digital post - Snitflader v7.0, kapitel 4 Generelle vilkår. Blandt de spørgsmål der besvares i afsnittet er f.eks. hvorledes det afgøres om en slutbruger kan modtage digital post, hvilke krav er der hvis en forsendelse indeholder HTML, tilladte tegnsæt samt den maksimale meddelelsesstørrelse. Samtlige scenarier hvor myndigheden sender en meddelelse til en slutbruger forudsætter, at myndigheden har undersøgt hvorvidt de har lov til at anvende Digital Post som leveringskanal. Efter Lov om Digital Post er langt de fleste tilmeldt, men der er stadigvæk en stor gruppe der er fritaget. En beskrivelse af hvordan dette afgøres fremgår af det nævnte afsnit. Bemærk e-boks skal lukke op for den IP adresse der sendes fra før der kan sendes og modtages afsendelser i testmiljøet; dette sker ved at kontakte e-boks teknisk support via teknisk@support.e-boks.dk. 4.1 Hvordan afgøres det nemmest hvorvidt vi har hul igennem til Digital Post REST? Ovenstående spørgsmål har den tekniske support af løsningen modtaget en del gange og her følger den mest basale test der kan svare herpå: 1. Åbn en browser 2. Indtast følgende i URL: afsendersystem/{sysid}/tilmeldinger/{indholdstypeid}?cvr={cvr} o Hvor {SysId} er det afsendersystem myndigheden har oprettet i administrationsportalen o Hvor {indholdstype} er et tilfældigt tal. o Hvor {cvr} er et tilfældigt 8 cifret tal. 3. Eftersom det er et https kald vil browseren prompte for valg af certifikat, der skal anvendes som klientcertifikat ved udførelsen af kaldet. Vælg det certifikat som myndigheden har opsat på afsendersystemet. 4. Hvis der er hul igennem til Digital Post, vil der blive returneret XML med en fejlkode der angiver at det er en ugyldig forespørgsel. Dette er en succes eftersom at indholdstypen vil være ukendt da den blev valgt tilfældigt. Hvis ovenstående lykkes kan det konstateres: 1) at der er åbnet for IP-adressen samt 2) at, der blev anvendt korrekt certifikat. Herfra er det alene et spørgsmål om at bygge videre på kaldene / udveksle data imellem myndighed og leverandør. 4

6 5 Integrationsscenarier I det følgende vil der blive redegjort for en række almindelige integrationsscenarier. For hvert scenarie vil det fremgå hvilken konfiguration der som minimum er krævet, hvordan de konfigurerede oplysninger bliver anvendt som metadata ved udførelsen af scenariet samt de væsentligste ekstra oplysninger der skal medsendes. Som illustration anvendes REST til at illustrere hvilke metadata der skal afleveres til henholdsvis modtager fra Digital Post. Såfremt myndigheden/leverandøren ønsker at anvende andre snitflader end REST, henvises til den detaljerede dokumentation for disse snitflader. Forskellene vil primært handle om at metadata er indpakket anderledes i de øvrige snitflader, men der er også forskel i omfanget af metadata der er til rådighed i den specifikke snitflade. Eksempelvis er der færre metadata om en afsendelse til rådighed i den filbaserede snitflade end i REST. For at holde hvert scenarie så kort og fokuseret som muligt vil scenarierne i visse tilfælde bygge videre på tidligere scenarier. Dette vil fremgå for hvert scenarie via interne henvisninger. Rækkefølgen hvormed scenarierne er nævnt er sket med henblik på at starte med helt basal funktionalitet og løbende udbygge disse. Derfor anbefales det at læse dem kronologisk i den rækkefølge de står skrevet. Bemærk at for at holde eksemplerne simple og læsbare, kan XML en i eksemplerne i enkelte tilfælde være blevet beskåret, hvilket vil være angivet med. Dette vil i givet fald være områder, der ikke har betydning for realiseringen af formålet med scenariet. 5.1 Myndighed afleverer meddelelse til slutbruger Formål: Eksemplet her illustrerer hvordan en afsendelse afleveres til en slutbruger inklusiv et vedhæftet dokument. Det forudsættes at det på forhånd er undersøgt at myndigheden har lov til at fremsende Digital Post til slutbrugeren. Henvisning: Afsendelse via REST sker via operation A1.3.1 som er dokumenteret i dokumentet Bilag A1 - REST - Afsendersystem v7.0. I samme dokument under ressourcer findes en beskrivelse af hver egenskab for ressourcen Afsendelse. Minimumskonfiguration. Følgende skal som minimum opsættes for at kunne afsende en meddelelse til en slutbruger. 1. Opret afsendersystem herved opsættes det certifikat der skal anvendes som klientcertifikat ved efterfølgende kald. Det kan både være myndighedens eget certifikat eller et funktionscertifikat fra leverandøren. Efter oprettelse findes SystemID der skal noteres til senere brug. 2. Opret tilmeldingsgruppe. Tilmeldingsgrupper er synlige for slutbrugerne og gør dem i stand til at se hvilke typer af forsendelser de kan forvente at modtage digitalt. 3. Opret materiale. Tilknyt materialet til tilmeldingsgruppen der blev oprettet ovenfor samt tilknyt det til afsendersystemet der blev oprettet. Noter tildelte MaterialeId er til senere brug. 5

7 Eksempel: Materiale ID Afsendersystem ID Nedenfor fremgår eksempel på aflevering af en afsendelse. De væsentligste karakteristika bliver uddybet efterfølgende: PUT <?xml version="1.0" encoding="utf-8"?> <dkal2:afsendelse xmlns:dkal1="urn:oio:dkal:1.0.0" xmlns:dkal2="urn:oio:dkal:2.0.0"> <dkal1:afsendelsemodtagersamling> <dkal2:afsendelsemodtager> <dkal1:cprnummeridentifikator> </dkal1:cprnummeridentifikator> </dkal2:afsendelsemodtager> </dkal1:afsendelsemodtagersamling> <dkal1:meddelelseindholdstypeidentifikator> </dkal1:meddelelseindholdstypeidentifikator> <dkal2:meddelelsetiteltekst>testoverskrift</dkal2:meddelelsetiteltekst> <dkal1:meddelelseindholddata>vgvzdcbizxnrzwq=</dkal1:meddelelseindholddata> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningsamling> <dkal1:vedhaeftning> <dkal1:vedhaeftningnavn>test</dkal1:vedhaeftningnavn> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningindholddata>vgvzda==</dkal1:vedhaeftningindholddata> </dkal1:vedhaeftning> </dkal1:vedhaeftningsamling> </dkal2:afsendelse> Version. Eksemplet ovenfor afleverer til version 2 af snitfladen. Dette fremgår: o Ved at 2 indgår i URL en: /srv.svc/2/afsendersystem/, samt o Ved at Afsendelse refererer namespace urn:oio:dkal:2.0.0 Meddelelses identifikation. Leverandøren skal tildele afsendelsen en global unik MeddelelsesId. 6

8 o Denne skal indgå som en del af URL en. I eksemplet ovenfor har afsendelsen MeddelelsesId a100. o Bemærk at det tildelte SystemId et for afsendersystemet her 149 skal anvendes i de første 6 karakterer som beskrevet under de generelle vilkår i snitfladen (se indledning for reference). o Derudover skal leverandøren sørge for at de følgende cifre er unikke. o Via ovenstående 2 regler bliver MeddelelsesId globalt unik hvilket bl.a. er relevant i forbindelse med supportsager samt tilbagekaldelse af dokumentet (se senere). Modtageren. Eftersom der er anvendt et CPR-nummer i eksemplet er her tale om en afsendelse til en borger. Tilsvarende kan det være til et CVR-nummer. Indholdstypen / materialet. Alle afsendelser skal angive hvilken type af forsendelse der er tale om ved at referere en såkaldt indholdstype / materiale. Materialet muliggør konfiguration af hvad der er gældende for denne forsendelse, såsom hvorvidt den kan besvares samt hvorvidt slutbrugeren skal kvittere for modtagelsen. Materialet anvendes samtidig i fakturerings og statistik øjemed. Fysisk indhold af hoveddokumentet. o Af eksemplet fremgår hvordan selve indholdet til hoveddokumentet er vedlagt. Eftersom indholdet er indsat i et XML dokument er det base 64 indkodet. Base 64 afkodning af det fysiske indhold i eksemplet vil vise at dokumentet her indeholder teksten Test besked. o Formatet af indholdet skal fremgå via FilformatNavn. I eksemplet fremgår at der er tale om tekstbaseret indhold. Alternativer kunne være PDF, eller HTM, der angiver at indholdet er HTML. Vedhæftning. Eksemplet illustrerer hvordan et dokument er vedlagt samt hvordan det fysiske indhold afleveres ligeledes base 64 indkodet som for hoveddokumentet. 5.2 Slutbruger besvarer henvendelse fra myndighed myndighed afhenter Formål: Eksemplet her viser hvordan det er muligt på en afsendelse til en slutbruger at angive at slutbrugeren kan besvare den. Desuden vises hvordan svaret fra slutbrugeren modtages. Henvisning: Svaret bliver afleveret via ressourcen Meddelelse. For detaljer om denne henvises til snitflade bilag A3 afhentningssystem under ressourcer. Minimumskonfiguration. Myndigheden som afleverer en afsendelsen til en slutbruger skal på forsendelsestidspunktet afgøre hvorvidt slutbrugeren der modtager meddelelsen skal være i stand til at besvare denne. Hermed sikres det at myndigheden har konfigureret hvordan de vil afhente slutbrugerens svar. Indledningsvist identisk med scenariet Myndighed afleverer meddelelse til slutbruger - her forudsættes samme konfiguration som i forrige eksempel at være oprettet. Opret et afhentningssystem. Herved opsætter myndigheden det end point (URL) eller den sikre e- mailadresse hvortil Digital Post skal aflevere svaret. Myndigheden skal samtidig oplyse hvorvidt der ønskes version 1 eller version 2 af ressourcen Meddelelse for nye integrationer anbefales altid den seneste version. Opret en postkasse. Postkassen skal pege på afhentningssystemet herved konfigureres hvordan postkassen bliver tømt. Gør materialet besvarbart. Rediger materialet der blev oprettet i forrige eksempel og angiv at besvarelse er mulig samt referer den postkasse der netop er oprettet. Herved bliver denne forsendelsestype besvarbar og den er nu sammenkædet med et end point hvortil svaret vil blive afleveret. 7

9 Afhentningssystem ID Aflever forsendelse der kan besvares. Postkasse ID Angivelse af at en afsendelse kan besvares kan ske på to måder: o På materialet dette blev konfigureret ovenfor. o På forsendelsen. Hvis vi undlod at konfigurere at materialet kan besvares, så er det i forsendelsesøjeblikket muligt at referere en postkasse hvortil svaret skal returneres. Dette kaldes for svarpostkassen. Herved kan forsendelsen besvares. Her antages at det er konfigureret på materialet samt at eksemplet ovenfor gentages. Herved vil slutbrugeren modtage en meddelelse der kan besvares. Slutbrugeren besvarer. Slutbrugeren kan nu logge på slutbrugergrænsefladen, trykke på besvar, skrive svaret til myndigheden og trykke på send. Svaret vil blive afleveret til postkasses tilhørende afhentningssystem hvoraf det fremgår hvilket end point eller sikker der skal sendes til. 8

10 Eksempel på modtaget svar: Nedenfor ses et eksempel på det XML der afleveres til det end point der er opsat på afhentningssystemet. <dkal2:meddelelse xmlns:xsi= xmlns:xsd= xmlns:dkal1="urn:oio:dkal:1.0.0" xmlns:dkal2="urn:oio:dkal:2.0.0"> <dkal1:korrelationidentifikator> </dkal1:korrelationidentifikator> <dkal2:meddelelseidentifikator>dkal2016a06a23a10b45b02b122162</dkal2:meddelelseidentifikator> <dkal1:meddelelsemodtagetdatotid> t11:42:51</dkal1:meddelelsemodtagetdatotid> <dkal2:meddelelsetypenavn>meddelelse</dkal2:meddelelsetypenavn> <dkal2:signaturbevis>...</dkal2:signaturbevis> <dkal1:indholdstoerrelsemaal>80</dkal1:indholdstoerrelsemaal> <dkal2:meddelelsetiteltekst>sv: TestOverskrift</dkal2:MeddelelseTitelTekst> <dkal1:meddelelseindholddata>vgvzdcbizxnrzwq=</dkal1:meddelelseindholddata> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:meddelelsetraadidentifikator>2016a06a23a11b42b51b237506</dkal1:meddelelsetraadidentifikator> <dkal2:postkassemetadata> <dkal1:postkasseidentifikator>2437</dkal1:postkasseidentifikator> <dkal1:postkasseemneidentifikator>2807</dkal1:postkasseemneidentifikator>... </dkal2:postkassemetadata> <dkal1:meddelelsefesdmetadata/> <dkal1:vedhaeftningsamlingkvantitet>0</dkal1:vedhaeftningsamlingkvantitet> </dkal2:meddelelse> KorrelationIdentifikator. Relationen til den meddelelse der besvares fremgår via dette felt. Den oprindelige afsendelse der blev sendt til slutbrugeren blev tildelt en meddelelses-identifikator. Svaret her refererer via dette felt den meddelelse der besvares. Herved kan svaret sammenkædes til den oprindelige meddelelse. MeddelelseTraadIdentifikator. Dette felt skal anvendes såfremt myndigheden ønsker at besvare denne henvendelse. Herved bliver myndighedens svar sammenkædet med den tidligere meddelelse og slutbrugeren har mulighed for i slutbrugergrænsefladen at vælge vis korrespondance og se et overblik over samtlige af de meddelelser der indgår i denne dialog. Fysiske indhold. Indholdet er base 64 indkodet. 9

11 5.3 Myndighed besvarer henvendelse fra slutbruger Formål: Myndighed besvarer en henvendelse fra slutbruger. Dette er en forlængelse af eksemplet ovenfor. Besvarelse er identisk med en afsendelse, som beskrevet i eksemplet i afsnit 5.1. Eksempel: PUT <?xml version="1.0" encoding="utf-8"?> <dkal2:afsendelse xmlns:dkal1="urn:oio:dkal:1.0.0" xmlns:dkal2="urn:oio:dkal:2.0.0"> <dkal1:afsendelsemodtagersamling> <dkal2:afsendelsemodtager> <dkal1:cprnummeridentifikator> </dkal1:cprnummeridentifikator> </dkal2:afsendelsemodtager> </dkal1:afsendelsemodtagersamling> <dkal1:meddelelseindholdstypeidentifikator> </dkal1:meddelelseindholdstypeidentifikator> <dkal1:meddelelsetraadidentifikator>2016a06a23a11b42b51b237506</dkal1:meddelelsetraadidentifikator> <dkal2:meddelelsetiteltekst>testoverskrift</dkal2:meddelelsetiteltekst> <dkal1:meddelelseindholddata>vgvzdcbizxnrzwq=</dkal1:meddelelseindholddata> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningsamling> <dkal1:vedhaeftning> <dkal1:vedhaeftningnavn>test</dkal1:vedhaeftningnavn> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningindholddata>vgvzda==</dkal1:vedhaeftningindholddata> </dkal1:vedhaeftning> </dkal1:vedhaeftningsamling> </dkal2:afsendelse> MeddelelseTraadIdentifikator. Afsendelsen er identisk med scenariet Myndighed afleverer meddelelse til slutbruger bortset at dette felt skal være udfyldt, eftersom det sammenkæder svaret med den originale meddelelse. Værdien findes i den meddelelse der besvares hvor et tilsvarende felt optræder (se scenariet Slutbruger besvarer henvendelse fra myndighed ). 10

12 5.4 Afsende meddelelse med åbningskvittering Formål: Det er muligt at prompte slutbrugeren der modtager henvendelsen for en kvittering i forbindelse med at meddelelsen åbnes. Bemærk at det er valgfrit for slutbrugeren hvorvidt vedkommende vælger at kvittere; på trods af at vedkommende ikke kvitterer, kan slutbrugeren stadigvæk læse indholdet. Konfiguration. På materialet kan opsættes kvittering for åbning. På materialet kan myndigheden angive hvorvidt denne forsendelsestype skal prompte slutbrugeren for en kvittering i forbindelse med at slutbrugeren åbner meddelelsen første gang. Angiv postkasse hvortil kvittering skal afleveres. For at myndigheden kan modtage kvitteringen skal angives en postkasse som igen peger på et afhentningssystem. Herved kan kvitteringen dirigeres tilbage til myndigheden. Aflever afsendelse hvor kvittering for modtagelse efterspørges. Anmodning om at slutbrugeren skal kvittere kan ske på følgende måder: Ved at konfigurere det på materialet som beskrevet ovenfor. Ved at efterspørge dette på den specifikke forsendelse. Konkret gøres dette ved at angive postkasse hvortil åbningskvittering skal returneres. I det efterfølgende eksempel er det efterspurgt på forsendelsen. 11

13 Eksempel: I eksemplet nedenfor efterspørges åbningskvittering på den specifikke forsendelse. PUT <?xml version="1.0" encoding="utf-8"?> <dkal2:afsendelse xmlns:dkal1="urn:oio:dkal:1.0.0" xmlns:dkal2="urn:oio:dkal:2.0.0"> <dkal1:afsendelsemodtagersamling> <dkal2:afsendelsemodtager> <dkal1:cprnummeridentifikator> </dkal1:cprnummeridentifikator> </dkal2:afsendelsemodtager> </dkal1:afsendelsemodtagersamling> <dkal1:meddelelseindholdstypeidentifikator> </dkal1:meddelelseindholdstypeidentifikator> <dkal1:meddelelsekvitteringstypenavn>valgfrit</dkal1: MeddelelseKvitteringsTypeNavn> <dkal1:meddelelsekvitteringpostkasseidentifikator>12</dkal1:meddelelsekvitteringpostkasseidentifikator> <dkal2:meddelelsetiteltekst>testoverskrift</dkal2:meddelelsetiteltekst> <dkal1:meddelelseindholddata>vgvzdcbizxnrzwq=</dkal1:meddelelseindholddata> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningsamling> <dkal1:vedhaeftning> <dkal1:vedhaeftningnavn>test</dkal1:vedhaeftningnavn> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningindholddata>vgvzda==</dkal1:vedhaeftningindholddata> </dkal1:vedhaeftning> </dkal1:vedhaeftningsamling> </dkal2:afsendelse> MeddelelseKvitteringsTypeNavn angiver at åbningskvittering ønskes ved at sætte værdien til valgfrit. MeddelelseKvitteringPostkasseIdentifikator angiver hvortil kvitteringssvaret skal sendes. 12

14 5.5 Modtagelse af åbningskvitteringssvar Formål: Beskriver det svar der returneres i forbindelse med at en slutbruger kvitterer ved åbning af meddelelse. I slutbrugergrænsefladen vil slutbrugeren i forlængelse af eksemplet ovenfor ved åbning af dokumentet der blev afleveret, blive anmodet om at kvittere for modtagelsen. Kvitteringen er frivillig og såfremt brugeren undlader at kvittere vil vedkommende stadigvæk være i stand til at læse dokumentet. Her antages at slutbrugeren kvitterer hvilket vil generere et kvitteringssvar til den oprindelige afsender. Eksempel på kvitteringssvar Nedenfor ses et eksempel på den XML der afleveres til det end point der er opsat på afhentningssystemet. Eksemplet illustrerer anvendelse af version 2 af snitfladen. <dkal2:meddelelse xmlns:xsi= xmlns:xsd= xmlns:dkal1="urn:oio:dkal:1.0.0" xmlns:dkal2="urn:oio:dkal:2.0.0"> <dkal1:korrelationidentifikator> </dkal1:korrelationidentifikator> <dkal2:meddelelseidentifikator> aaabningskvittering</dkal2:meddelelseidentifikato r> <dkal1:meddelelsemodtagetdatotid> t11:42:51</dkal1:meddelelsemodtagetdatotid> <dkal2:meddelelsetypenavn>kvittering</dkal2:meddelelsetypenavn> <dkal2:signaturbevis>...</dkal2:signaturbevis> <dkal1:indholdstoerrelsemaal>80</dkal1:indholdstoerrelsemaal> <dkal2:meddelelsetiteltekst>åbningskvittering: TestOverskrift</dkal2:MeddelelseTitelTekst> <dkal1:meddelelseindholddata></dkal1:meddelelseindholddata> <dkal1:filformatnavn>pdf</dkal1:filformatnavn> <dkal1:meddelelsetraadidentifikator>2016a06a23a11b42b51b237506</dkal1:meddelelsetraadidentifikator> <dkal2:postkassemetadata> <dkal1:postkasseidentifikator>2437</dkal1:postkasseidentifikator> <dkal1:postkasseemneidentifikator>2807</dkal1:postkasseemneidentifikator> <dkal2:metadatasamling> <dkal2:metadata> <dkal1:metadatanoeglenavn>dkalemnekategori</dkal1:metadatanoeglenavn> <dkal2:metadatavaerditekst>rest Afhentnings post kasse</dkal2:metadatavaerditekst> </dkal2:metadata> </dkal2:metadatasamling> </dkal2:postkassemetadata> <dkal1:meddelelsefesdmetadata/> <dkal1:vedhaeftningsamlingkvantitet>0</dkal1:vedhaeftningsamlingkvantitet> </dkal2:meddelelse> Version 1. Såfremt afhentningssystemet er opsat til version 1 vil svaret ligne et helt almindeligt retursvar fra en slutbruger blot med Åbningskvittering foranstillet i titlen på svaret. MeddelelseTitelTekst. I version 1 vil det alene være muligt at finde dokumentet der kvitteres for via titlen. Titlen vil være sammensat af den oprindelige titel samt Åbningskvittering: som bliver foranstillet. MeddelelseTypeNavn. Dette felt vil indeholde værdien meddelelse. Version 2. Såfremt afhentningssystemet er opsat til version 2 vil følgende blive oplyst. MeddelelseTypeNavn. Dette felt vil indeholde værdien kvittering. 13

15 KorrelationsIdentifikator. Sammenkædningen til den meddelelse der bliver besvaret vil fremgår via dette felt. Den oprindelige afsendelse der blev sendt til slutbrugeren blev tildelt en MeddelelsesId. Svaret vil via dette felt refererer MeddelelseId på den meddelelse der besvares. 5.6 Afsend meddelelse til slutbruger der kan besvares via formular Formål: Her beskrives hvordan det er muligt at aflevere en forsendelse til en slutbruger som kan besvares via en formular. Det beskrives hvordan de indtastede felter i formularen returneres og bliver tilgængelig for myndigheden. Opbygning af en formular. Kort beskrevet skal der udarbejdes en XML fil der beskriver opbygningen af formularen eventuelt på flere sprog. Der henvises til bilag G i snitfladen der beskriver opbygningen af en formular. Nedenfor vises et eksempel på en formular hvor modtageren skal be-/afkræfte en tid hos skoletandlægen. 14

16 Validering af input. For inputfelter hvor slutbrugerne skal indtaste tekst, er det muligt at angive hvorvidt feltet er påkrævet samt tilknytte en valideringsregel. Valideringsreglen tilføjes ved at angive en såkaldt Regular Expression. Opbygningen af disse udtryk er relativt kompleks og ligger uden for denne vejledning at beskrive. Ved at søge på nettet efter regular expression examples er det muligt at finde omfangsrige samlinger med eksempler på valideringsregler, som eventuelt kan tilpasses og afprøves ved hjælp af online validatorer. Online validatorer findes på nettet ved at søge efter regular expressions validator online. Konfiguration Opret formularen. XML-filen der beskriver opbygningen af formularen, eventuelt i flere sprogudgaver, skal uploades i forbindelse med at en formular oprettes i administrationsportalen. I forbindelse med at formularen bliver gemt, valideres den imod et XSD skema. Herved sikres det, at formularen kan vises overfor slutbrugeren. Tilknyt formularen til en postkasse. Dette gøres ved at tilknytte formularen til et emne på den ønskede postkasse. Emner er en underkategorisering af postkassen der giver slutbrugeren mulighed for at kategorisere typen af henvendelse. Hvert emne kan have sin egen formular / ingen formular tilknyttet. Hvis der ikke er tilknyttet en formular vil slutbrugeren ved anvendelse af dette emne/postkasse, uanset om det er initiering eller besvarelse, skulle skrive en fritekst, dvs. en ustruktureret henvendelse. Hvis der er tilknyttet en formular skal slutbrugeren ved anvendelse af emnet/postkassen udfylde formularen. Dvs. det er myndigheden der afgør hvorvidt de ønsker et struktureret eller ustruktureret svar. Såfremt der ikke er oprettet emner på postkassen er det muligt at tilknytte en formular til standardemnet. Efter at postkassen er gemt er det muligt via postkasseoversigten at vælge Info for den oprettede postkasse. Heraf fremgår emner inklusiv EmneId. Noter det tildelte EmneId da dette skal anvendes efterfølgende. Afsend meddelelse med formular tilknyttet. Afsendelsen er fuldstændig identisk med scenariet hvor slutbruger kan besvare uden formular se Slutbruger besvarer henvendelse fra myndighed. Slutbruger åbner meddelelsen i slutbrugergrænsefladen, trykker besvar, udfylder formularen og vælger send. Herved vil svaret blive sendt til myndigheden som strukturerede data. 15

17 Formularsvar der fremsendes til myndighed Nedenfor ses et eksempel på det XML der afleveres til det end point der er opsat på afhentningssystemet. I eksemplet antages det at slutbrugeren har besvaret med Ja, vi kommer til den oplyste tid. <dkal2:meddelelse xmlns:xsi= xmlns:xsd= xmlns:dkal1="urn:oio:dkal:1.0.0" xmlns:dkal2="urn:oio:dkal:2.0.0"> <dkal1:korrelationidentifikator> </dkal1:korrelationidentifikator> <dkal2:meddelelseidentifikator>dkal2016a06a23a10b45b02b122162</dkal2:meddelelseidentifikator> <dkal1:meddelelsemodtagetdatotid> t11:42:51</dkal1:meddelelsemodtagetdatotid> <dkal2:meddelelsetypenavn>meddelelse</dkal2:meddelelsetypenavn> <dkal2:signaturbevis>...</dkal2:signaturbevis> <dkal1:indholdstoerrelsemaal>80</dkal1:indholdstoerrelsemaal> <dkal2:meddelelsetiteltekst>sv: TestOverskrift</dkal2:MeddelelseTitelTekst> <dkal1:meddelelseindholddata></dkal1:meddelelseindholddata> <dkal1:filformatnavn>pdf</dkal1:filformatnavn> <dkal1:meddelelsetraadidentifikator>2016a06a23a11b42b51b237506</dkal1:meddelelsetraadidentifikator> <dkal2:postkassemetadata> <dkal1:postkasseidentifikator>2437</dkal1:postkasseidentifikator> <dkal1:postkasseemneidentifikator>2807</dkal1:postkasseemneidentifikator> <dkal2:metadatasamling> <dkal2:metadata> <dkal1:metadatanoeglenavn>singleselect</dkal1:metadatanoeglenavn> <dkal2:metadatavaerditekst>singleselect-1</dkal2:metadatavaerditekst> </dkal2:metadata> </dkal2:metadatasamling> </dkal2:postkassemetadata> <dkal1:meddelelsefesdmetadata/> <dkal1:vedhaeftningsamlingkvantitet>0</dkal1:vedhaeftningsamlingkvantitet> </dkal2:meddelelse> Identifikation af hvilken formular der besvares: Via PostkasseIdentifikator og PostkasseEmneIdentifikator er det muligt identificere hvilken formular der besvares. MetadataNoegleNavn. Hver formular felt har tilknyttet en nøgle. I formulareksemplet ovenfor er SingleSelect et eksempel herpå. MetadataVaerdiTekst. Her fremgår den værdi slutbrugeren oplyste. I formulareksemplet er det værdien der modsvarer at vedkommende ønsker at deltage. Forskel imellem version 1 og 2. Af hensyn til at være bagud kompatibel kan funktionaliteten tilføjes udelukkende via administrationsportalen på trods af at myndigheden anvender version 1 af snitfladen. Eftersom muligheden ikke oprindeligt var tilstede i version 1 har dette nogle begrænsninger: Version 1: For ikke at bryde med skemaet i version 1 samt undgå potentielle driftsproblemer, vil kun 2 felter fra formularen blive returneret struktureret i version 1. Dette modsvarer den praksis der i forvejen gør sig gældende for version 1 grundet indtastningsfelter. Svaret af samtlige felter vil være tilstede i besvarelsen, men blot indsat som ustruktureret tekst i selve meddelelsen. Den maksimale længde af tekstfelter er her 256. Version 2: Her vil samtlige felter fra formularen blive returneret som strukturerede data. Ydermere er længden af tekstfelter blevet forøget til 1024 med henblik på at formularer kan indeholde tekstfelter der tillader lange tekster. 16

18 5.7 Myndighed modtager henvendelse fra slutbruger Formål: Myndighed ønsker at udstille en postkasse hvortil slutbrugere på eget initiativ kan rette henvendelse til myndigheden. Minimumskonfiguration: Opret postkasse. For at slutbrugere kan rette henvendelse skal myndigheden som minimum udstille mindst en postkasse som slutbrugerne kan adressere henvendelsen til. Med henblik på at få slutbrugerne til at sende henvendelserne til rette afdeling hos myndigheden, og dermed undgå at myndigheden skal fordele posten manuelt, er det muligt at oprette flere postkasser og gruppere disse. Summen af denne struktur kaldes for myndighedens kontakthierarki. En postkasse skal pege på et afhentningssystem der tømmer postkassen. Se konfiguration af scenariet Slutbruger besvarer henvendelse fra myndighed. Slutbruger initierer henvendelse. Via slutbrugergrænsefladen har slutbrugeren nu mulighed for at vælge myndighedens postkasse, skrive en besked til denne og trykke send. Slutbrugeren kan se sin meddelelse i sendt post. Eksempel Eksemplet er identisk med scenariet Slutbruger besvarer henvendelse fra myndighed med den forskel at der ikke er en KorrelationsId der peger på den originale meddelelse der besvares, eftersom der ikke er en meddelelse der besvares. Variant med formular: struktureret henvendelse. Ovenstående scenarie kan udbygges ved at tilknytte en formular til postkassen. Herved vil slutbrugeren kunne initiere en meddelelse til en formular. Formularbaseret henvendelse omtales struktureret henvendelse, i modsætning til ovenstående der omtales ustruktureret henvendelse. Variant med forskelligt kontakthierarki for borgere og virksomheder. Såfremt myndigheden har behov for at nogle postkasser alene optræder for borgere og andre udelukkende for virksomheder er dette muligt. I administrationsportalen skal myndigheden da vælge at skifte til to kontakthierarkier. Scenariet vil være identisk med ovenstående bortset fra at svaret fra borgere vil komme fra en PostkasseId og svaret fra virksomheder vil komme til en anden PostkasseId. 17

19 5.8 Afsend meddelelse til flere slutbruger Formål: Det er muligt via version 2 af snitfladen at afsende den samme meddelelse til optil 10 modtagere. Indholdet vil da være helt identisk til samtlige de angivne modtagere. Eksempel: PUT <?xml version="1.0" encoding="utf-8"?> <dkal2:afsendelse xmlns:dkal1="urn:oio:dkal:1.0.0" xmlns:dkal2="urn:oio:dkal:2.0.0"> <dkal1:afsendelsedatotid> </dkal1:afsendelsedatotid> <dkal1:afsendelsemodtagersamling> <dkal2:afsendelsemodtager> <dkal1:cprnummeridentifikator> </dkal1:cprnummeridentifikator> <dkal1:cprnummeridentifikator> </dkal1:cprnummeridentifikator> </dkal2:afsendelsemodtager> </dkal1:afsendelsemodtagersamling> <dkal1:meddelelseindholdstypeidentifikator> </dkal1:meddelelseindholdstypeidentifikator> <dkal2:meddelelsetiteltekst>testoverskrift</dkal2:meddelelsetiteltekst> <dkal1:meddelelseindholddata>vgvzdcbizxnrzwq=</dkal1:meddelelseindholddata> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningsamling> <dkal1:vedhaeftning> <dkal1:vedhaeftningnavn>test</dkal1:vedhaeftningnavn> <dkal1:filformatnavn>txt</dkal1:filformatnavn> <dkal1:vedhaeftningindholddata>vgvzda==</dkal1:vedhaeftningindholddata> </dkal1:vedhaeftning> </dkal1:vedhaeftningsamling> </dkal2:afsendelse> Forskel i forhold til afsendelse til en slutbruger. Den eneste forskel i forhold til at sende til én modtager er, at der angives flere modtagere i elementet AfsendelseModtagerSamling. Samtlige modtagere skal være tilmeldt Digital Post. Forsendelsen regnes for en transaktion som enten går godt eller fejler. Dvs. såfremt blot en af modtagerne ikke kan modtage eksempelvis som følge af at vedkommende er fritaget da afvises hele forsendelsen. Virkningstidspunktet. Leveringstidspunktet hvor slutbrugeren modtager meddelelsen kan være en dato frem i tiden. Dette tidspunkt kaldes for virkningstiden. Tidspunktet fremgår af feltet AfsendelseDatoTid som er medtaget i eksemplet ovenfor. Tilbagekaldelse ved flere modtagere. Som for forsendelser til en slutbruger er det muligt at foretage tilbagekaldes af afsendelsen såfremt virkningstiden ikke er indtruffet, dvs. hvor dokumentet ikke er blevet tilgængeligt for slutbrugerne. Da afsendelsen til samtlige modtagere regnes for en transaktion som modtages eller afvises i sin helhed, gælder ligeledes at tilbagekaldelse vil gælde for samtlige modtagere. 18

20 5.9 Myndighed tømning af sin virksomhedsindbakke Formål: Når Trafikstyrelsen eksempelvis udsender synsindkaldelse af en bil til en kommune, vil kommunen modtage indkaldelsen på lige fod med alle andre virksomheder, dvs. i deres sikre digitale postkasse som omtales slutbrugergrænsefladen. I dette scenarie forklares det, hvordan myndigheden har mulighed for at få videresendt post fra virk.dk, som om henvendelsen kom fra en slutbruger til en postkasse. Dvs. myndigheden kan få videresendt post fra indbakken i deres sikre digital postkasse til et End-point (URL / e- mail)som om en slutbruger havde rettet henvendelse via en postkasse. Myndigheden kan vælge at foretage denne form for videresendelse, begrænset til afsendere der er myndigheder. Fordelen herved er, at myndigheden kan anvende deres eksisterende systemer til at håndtere myndighedspost fra indbakken. Baggrund. I ovenstående tænkte eksempel skriver Trafikstyrelsen til en række af CVR-numre og skelner ikke til hvorvidt modtageren er en virksomhed eller myndighed. Virksomheder har mulighed for at konfigurere at post fra indbakken skal videresendes, som XML til et end point eller som sikker (S/MIME). De metadata der videresendes og er udfyldt vil være anderledes i denne situation i forhold til situationen hvor en slutbruger skriver til en postkasse som myndigheden udstiller. For at tilgodese at myndigheder kan have behov for at modtage deres virksomhedspost fra indbakken på lige fod med at en slutbruger skriver til en postkasse, er det muligt at konfigurer dette på afhentningssystemet ved at opsætte at dette skal modtages som myndighedspost. Begrænsninger. Når post ønskes videresendt som myndighedspost er der følgende begrænsninger: Opsætning af myndighedspost resulterer i at meddelelsen slettes fra indbakken i myndighedens sikre digitale postkasse. Som følge heraf er det ikke muligt at besvare meddelelsen - hverken via systemkald eller via slutbrugergrænsefladen. Hvis meddelelsen er større end 10 Mb og myndigheden har opsat videresendelse via sikker , da vil det fremsendte dokument blive udskiftet med en standardskrivelse, der informerer om at et stort dokument er afleveret i myndighedens indbakke som ikke er videresendt. Den oprindelige meddelelse der ikke blev videresendt, bliver ikke slettet fra indbakken og myndigheden kan logge på slutbrugergrænsefladen og tilgå det dvs. læse og/eller downloade dokumentet. Minimumkonfiguration 1. Opsæt arkiveringsregel. Myndigheden kan konfigurere at udvalgt post (eksempelvis Trafikstyrelsen) eller al post fra det offentlige som modtages i indbakken skal flyttes til en anden mappe. I eksemplet her oprettes en arkivmappe kaldet Offentlig post og der oprettes efterfølgende en arkiveringsregel der flytter al offentlig post til denne mappe. 2. Opsætning et afhentningssystem med tilknyttet mappe. Nu oprettes et afhentningssystem og mappen Offentlig post tilknyttes. Denne mappe blev netop ovenfor opsat til at indeholde al offentlig post. Marker på dette afhentningssystem at posten skal konverteres til myndighedspost ved at sætte kryds ud for myndighedspost. Rent teknisk omtales dette at posten ændres fra indbakke-format til postkasse-format. Konsekvensen heraf er at posten bliver tømt fra indbakken, dvs. slettet. 3. Efterprøv ved at flytte post til mappen. Det er muligt at teste ovenstående ved at flytte et dokument manuelt til mappen Offentlig post. Eventuelt kan det samme dokument flyttes væk fra mappen og tilbage igen, hvilket vil genafvikle videresendelse. 19

21 Data der fremsendes De data der fremsendes vil nu svare til at en slutbruger initierede en henvendelse, med en undtagelse der vil ikke være en KorrelationsId. 20

22 5.10 Fejlsøgning Det kan være svært at afgøre årsagen til en fejl og dermed hvem der skal udbedre denne. Ikke mindst som følge af at der er flere parter involveret; myndigheden anvender et system fra en leverandør, som igen baserer sig på Digital Post løsningen. Her følger nogle retningslinjer, som gør myndigheden i stand til selv at afveje hvorvidt det er deres leverandørs system der er fejlbehæftet, eller om der i sjældne tilfælde er behov for at oprette en support sag med henblik på fejlsøgning i Digital Post- løsningen. Fejl ved kald af Digital Post løsningen Samtlige kald der udføres i mod Digital Post løsningen, bliver valideret for samtlige input parametre. Såfremt en af disse parametre ikke er valid vil kaldet blive afvist med en 4 cifret fejlkode. Denne fejlkode har tilknyttet fejltekst og kan såfremt problemet ikke selv kan afhjælpes, anvendes ved henvendelse til teknisk support for en forklaring af mulige årsager. For at gøre leverandøren i stand til selv at kunne udbedre fejl, samt i tilfælde af kontakt til teknisk support på Digital Post løsningen (teknisk@support.e-boks.dk), at kunne indsnævre hvad der er gået galt, tilrådes det på det kraftigste at leverandørerne gemmer den fejl XML der bliver returneret her tænkes specielt på fejlkoden, den unikke FejlId samt fejlteksten. FejlId en er påkrævet ved udvidet årsagsafklaring i Digital Post løsningen. Det skema der er tilknyttet den fejl-xml der returneres - dvs. Fejl.XSD findes i en version 1 og version2. Den version der returneres vil afspejle den version der kaldes med. Hvis eksempelvis en REST operation kaldes med version 1 og denne fejler, så vil det resultere en fejl der overholder skemaet i version 1. 21

23 Kommunikationsloggen Kommunikationsloggen tillader myndighederne, med op til 24 timers forsinkelse (oftest dog væsentligt hurtigere), at danne sig et fuldstændigt overblik over hvad de succesfuldt har afleveret og modtaget igennem Digital Post-løsningen. Forsendelser som Digital Post afviste ved leveringen vil ikke kunne fremsøges via loggen, ligesom det ikke vil fremgå at en henvendelse fra en slutbruger ikke kunne leveres til myndigheden. Søgning i loggen. Myndighederne har mulighed for at fremsøge transaktioner på baggrund af den specifikke MeddelelseId, en specifik modtager. Samtlige søgninger bliver registreret i sikkerhedsloggen. Detaljer om hver forsendelse. For en forsendelse er det muligt at vise detaljer om forsendelsen såsom navn på vedhæftninger, størrelse af forsendelsen mv. Flere modtagere. En forsendelse til flere modtagere vil resultere i flere rækker i kommunikationsloggen, hvor det for hver række vil fremgå at der er andre modtagere involveret i denne forsendelse. Tilbagekaldelse og ændring af virkningsdato. Her vil meddelelsen fortsat være sorteret efter det oprindelige modtagelsestidspunkt også efter en opdatering. Det nye tidspunkt vil optræde under detaljer. For flere detaljer om anvendelse af kommunikationsloggen henvises til Digitaliseringsstyrelsens vejledning herom. 22

24 Afklaring af hvem der er skyld i en fejl Myndigheden anbefales altid forud for en henvendelse til teknisk support for Digital Post på forhånd at udføre følgende afklaringer. Hvis det er tale om en afsendelse fra myndigheden, som slutbrugeren påstår at vedkommende aldrig har modtaget, da anbefales det at kigge i kommunikationsloggen via slutbrugerens CPR/CVR-nummer. Hvis meddelelsen ikke findes her, da vil det oftest skyldes at meddelelsen af en eller anden årsag ikke er blevet leveret succesfuldt til Digital Post. For at finde den konkrete årsag anbefales det at fejfinde i leverandørens log for at se om der er blevet returneret en fejlkode i forbindelse med afleveringen til Digital Post. Hvis der er tale om et svar fra en slutbruger til en myndighed, som myndigheden ikke har modtaget i deres myndighedssystem, da kan kommunikationsloggen igen anvendes til at bekræfte at slutbrugeren har rettet henvendelse. Igen hvis meddelelsen findes i kommunikationsloggen, men ikke i myndighedens system, da skal myndigheden kigge i leverandørens log for at finde en forklaring af hvorfor meddelelsen ikke er kommet videre i systemet. 23