DKAL Snitflader REST Register

Transkript

1 DKAL Snitflader REST Register 1

2 Indholdsfortegnelse A2.1 INTRODUKTION 3 A2.1.1 HENVISNINGER 3 A2.1.2 LÆSEVEJLEDNING 4 A SÅDAN LÆSES EN REST GRAF 4 A SÅDAN LÆSES EN RESSOURCE OG EN TYPE 4 A SÅDAN LÆSES EN OPERATION 6 A2.2 OVERSIGT OVER FUNKTIONSOMRÅDE 7 A2.2.1 KONFIGURATION AF ET REGISTER 8 A2.3 RESSOURCER 9 A2.3.1 SLUTBRUGERSAMLINGREFERENCESAMLING 10 A2.3.2 SLUTBRUGERSAMLING 10 A2.3.3 SLUTBRUGER 10 A2.3.4 MYNDIGHEDSTILMELDING 11 A2.3.5 GRUPPETILMELDINGSAMLING 12 A2.3.6 GRUPPETILMELDING 12 A2.3.7 SLUTBRUGERSTAMDATA 13 A2.4 OPERATIONER 15 A2.4.1 HENT REFERENCE TIL SLUTBRUGERLISTE 15 A2.4.2 HENT SLUTBRUGER DELLISTE 16 A2.4.3 SLET ÆNDRINGSLISTE 17 A2.4.4 HENT EN SLUTBRUGERS STAMDATA OG TILMELDINGER 17 A2.4.5 OPRET BOKS / OPDATER STAMDATA 19 A2.4.6 TIL- / AFMELD EN SLUTBRUGER TIL EN MYNDIGHED / ALLE MYNDIGHEDER 20 A2.4.7 TILMELD / AFMELD EN SLUTBRUGER TIL EN TILMELDINGSGRUPPE 21 A2.4.8 SLET EN TILMELDING FOR EN SLUTBRUGER 22 Bilag A2: REST Register 2

3 A2.1 Introduktion Dette dokument beskriver DKAL s REST snitflade for funktionsområdet vedrørende Register. Funktionsområdet anvendes af en myndighed til at hente og opdatere stamdata og administrerer til- og afmeldinger for slutbrugere. Dokumentet henvender sig til udviklere og arkitekter, der skal integrere et Register (fagsystem) med DKAL. Denne introduktion indeholder en henvisning til andre relevante dokumenter, og en læsevejledning til snitfladebeskrivelsen. Efter introduktionen findes selve snitfladebeskrivelsen. A2.1.1 Henvisninger Følgende dokumenter indeholder information, som er relevant for den snitflade, der er beskrevet i dette dokument: DKAL snitflader indeholder den overordnede beskrivelse af DKAL s system-til-system snitflader, hvilket inkluderer en overordnet beskrivelse af REST snitfladen. Dokumentet indeholder også en begrebsliste, som beskriver alle DKAL relaterede begreber, der er anvendt i dette dokument. Disse begreber er i dette dokument skrevet med kursiv og det anbefales at læse dem forud for dette dokument. Bilag F Sikkerhed beskriver sikkerheden vedrørende DKAL s system-til-system snitflader. Bilag A5 HTTP returkoder og fejlkoder beskriver den generelle anvendelse af HTTP returkoder for REST snitfladen, samt de specifikke fejlkoder, som DKAL anvender. REST snitfladen består af yderligere tre funktionsområder, som er beskrevet i følgende dokumenter: Bilag A1 REST Afsendersystem beskriver REST snitflade for et afsendersystem. Et afsendersystem anvendes af en myndighed til at sende afsendelser til slutbrugere. Bilag A3 REST Afhentningssystem beskriver REST snitflade for et afhentningssystem. Systemet anvendes 1) af virksomhed til at hente meddelelser fra deres sikre boks, og 2) af myndigheder til at hente meddelelser sendt til dem enten fra andre myndigheder, eller fra slutbrugere via de af myndigheden opsatte postkasser. Bilag A4 REST Portal beskriver REST snitflade for en portal. En portal anvendes af en myndighed til at 1) til- og afmelde slutbrugere til tilmeldingsgrupper, 2) hente en slutbrugers seneste meddelelser, og 3) efterspørge antallet af ulæste meddelelse. Bilag A2: REST Register 3

4 A2.1.2 Læsevejledning Metoden der anvendes i dette dokument til beskrivelse af ressourcer og operationer er beskrevet i dette afsnit. A Sådan læses en REST graf REST operationerne illustreres ved hjælp af en URI-graf. Denne graf illustrerer hvilke HTTP operationer der er tilgængelig for det pågældende funktionsområde. Se nedenstående eksempel. GET PUT DEL /afsendersystem/{sysid} /afsendelser /tilmeldingsliste /{meddelelsesid} Øverst til højre ses en farvekode for hver HTTP operation: Grøn for GET, blå for PUT, og gul for DELETE (forkortet DEL). Grafen læses fra venstre mod højre og angiver et antal URI er. En URI kan indeholde en eller flere parametre, som er omkranset af { }. Den første del af grafen, /afsendersystem/{sysid}, indeholder således parameteren sysid, og kan f.eks. være /afsendersystem/1234. Den har ingen farvekoder angivet, hvilket viser at ingen operationer er tilgængelige. Eksempelet ovenfor viser følgende operationer: GET /afsendersystem/{sysid}/afsendelser GET /afsendersystem/{sysid}/afsendelser/{meddelelsesid} PUT /afsendersystem/{sysid}/afsendelser/{meddelelsesid} DELETE /afsendersystem/{sysid}/afsendelser/{meddelelsesid} GET /afsendersystem/{sysid}/tilmeldingsliste Det er ikke den fuld URI, der er angivet. De starter fra den fælles rod som alle URI erne i snitflade har, og deres fælles præfix, som angiver protokol, host og snitflade version, er udeladt. A Sådan læses en ressource og en type Ressourcer er dataobjekter, der anvendes som input eller output til operationerne i RESTgrafen. Typer er mindre datastrukturer, der indgår i en eller flere ressource. Ressourcer og typer er dokumenteret via en oversigt, som viser deres relationer, og via hver sin tabel, som beskriver formål, det tilhørende XML skema, samt hvert enkelt felt. Bilag A2: REST Register 4

5 Nedenstående illustration er et eksempel på en oversigt af ressourcer og typer. AfsendelseSamling Afsendelse MeddelelseFESDmetadata VedhaeftningSamling 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. Referencen følger pilens retning. En stiplet pil viser at en type eller ressource er inkluderet som en del af en anden type eller ressource. Inkluderingen følger pilens retning. Ovenstående illustration viser således at ressourcen AfsendelseSamling har en reference til ressourcen Afsendelse, og at typerne MeddelelseFESDmetadata og VedhaeftningSamling er inkluderet i ressourcen Afsendelse. Hver ressource og type er beskrevet i en tabel, som beskriver formål, det tilhørende XML skema, samt hvert enkelt felt. Tabellen kan også indeholde eksempler og kommentarer. For hvert felt er angivet hvordan det kan anvendes, feltets navn og en beskrivelse. Nedenfor er vist et forsimplet eksempel for ressourcen Afsendelse. RESSOURCE Afsendelse Beskriver ressourcens/typens formål. XSD Navnet på det XSD skema som beskriver ressourcen. Angiver om det er en ressource eller en type. R Type Meddelelse Servicebesked C Indholdstype Angiver indholdstypen for afsendelsen. U Titel Titlen på afsendelsen. C Metadata Metadata for afsendelsen. Felt navnet Beskrivelse R: feltet kan kun læses. C: feltet er obligatorisk ved oprettelse, og kan efterfølgende kun læses. U: feltet er obligatorisk ved oprettelse, og kan efterfølgende opdateres. I eksemplet ovenfor er feltet Indholdstype påkrævet ved oprettelse idet der står (C) ud for feltet. Feltet Type er afledt af Indholdstype (en indholdstype er enten servicebesked eller en Bilag A2: REST Register 5

6 meddelelse). Derfor kan dette felt kun læses (R). Feltet Titel er også påkrævet ved oprettelse, men kan opdateres efterfølgende (U). Feltnavne som starter med små bogstaver er attributter. Store begyndelsesbogstaver angiver elementer. A Sådan læses en operation Hver operation i snitfladen er beskrevet i en tabel, som beskriver formål, input parametre, output content og mulige fejlkoder, der kan returneres. Tabellen kan også indeholde eksempler på anvendelse og kommentarer. /afsendersystem/{sysid}/afsendelser/{meddelelsesid} Eksempler på anvendelse et med operationen. Beskriver eksempler hvor operationen anvendes. GET Angiver om det er en læse (GET) eller skrive (PUT) operation. Input parametre Input søgeparametre Output content Fejlkoder Beskriver alle parametre i URI en. Beskriver eventuelle søgeparametre. I denne sektion fremgår resultatet af kaldet deriblandt om resultatet er OIOXML / binært. Af denne sektion fremgår mulige fejlkoder, der kan returneres. Den første kode er den DKAL-specifikke fejlkode. Den relaterede HTTP returkode er angivet i parentes. PUT operationer kan kun opdatere felter i en ressource som er angivet som opdaterbare (se ressource forklaringen U). Bilag A2: REST Register 6

7 A2.2 Oversigt over funktionsområde Dette funktionsområde gør det muligt for et register / fagsystem at hente stamdata og tilmeldinger på tilmeldingsgruppe- og myndighedsniveau for slutbrugere. Et register kan opdatere stamdata og tilmeldinger, samt oprette nye slutbrugere. En oversigt over samtlige operationer er vist nedenfor. /register/{sysid} /slutbrugerliste /slutbruger/{cvr} /slutbruger/{cpr} /{slutbrugerlisteid} /{dellisteid} GET PUT DEL /boks/{cvr} /boks/{cpr} /myndighedstilmelding /tilmeldingsgrupper/{tilmeldingsgruppeid} GET /register/{sysid}/slutbrugerliste Hent reference til slutbrugerliste og referencer til de enkelte dellister, som slutbrugerlisten kan være delt i. GET /register/{sysid}/slutbrugerliste/{slutbrugerlisteid}/{dellisteid} Hent del af slutbrugerliste. For hver slutbruger fremgår stamdata, tilmeldinger på tilmeldingsgruppeniveau, og tilmelding på myndighedsniveau. Bemærk at opsætningen af registret har stor indflydelse på den liste der returneres (se A2.2.1). DELETE /register/{sysid}/slutbrugerliste/{slutbrugerlisteid} Operationen anvendes til at bekræfte at en ændringsliste er færdigbehandlet. Hermed bliver den næste ændringsliste, såfremt der er en, tilgængelig. GET /register/{sysid}/slutbruger/{cpr/cvr} Operationen henter oplysning om en slutbrugers stamdata og tilmeldinger. Stamdata inkluderer bl.a. slutbrugerens navn, mobilnummer, adresse, og status. Det fulde mobilnummer er kun vist såfremt denne ydelse er tilkøbt. adressen er kun delvist angivet. Tilmeldingerne angiver hvilke tilmeldingsgrupper, som slutbrugeren er tilmeldt. Det fremgår ligeledes om slutbrugeren har tilmeldt sig alt for den pågældende myndighed samt om vedkommende har tilmeldt sig alle myndigheder. PUT /register/{sysid}/boks/{cpr/cvr} Operationen opretter en ny boks og/eller foretager online opdatering af stamdata for en eksisterende slutbruger. Registret kan angive om slutbrugeren ønsker servicebeskeder eller både ønsker servicebeskeder samt meddelelser. Ved oprettelse af en ny slutbruger, som ønsker at modtage meddelelser, er det kun en foreløbig oprettelse, som slutbrugeren selv skal logge ind og bekræfte. PUT /register/{sysid}/boks/{cpr/cvr}/myndighedstilmeldinger Operationen opdaterer status for slutbrugerens tilmelding på myndighedsniveau. Herved kan en slutbruger til- og afmelde sig1) den myndighed registret er tilknyttet eller 2) alle myndigheder. Herved bliver slutbrugeren samtidig automatisk tilmeldt nye tilmeldingsgrupper henholdsvis myndigheder når de oprettes. Bilag A2: REST Register 7

8 PUT /register/{sysid}/boks/{cpr/cvr}/tilmeldingsgrupper/{tilmeldingsgruppeid} Operationen gør det muligt at tilmelde en slutbruger til en tilmeldingsgruppe. Hvis tilmeldingen inkluderer modtagelse af meddelelser som ikke er servicebeskeder, er det kun en foreløbig tilmelding, som slutbrugeren selv skal logge ind og bekræfte. Hvis en tilmelding kun vedrører modtagelse af servicebeskeder, træder den omgående i kraft. DELETE /register/{sysid}/boks/{cpr/cvr}/tilmeldinggrupper/{tilmeldingsgruppeid} - Slet en tilmelding for en slutbruger. A2.2.1 Konfiguration af et register Via administrationsportalen opsættes: Registrets tilknytning til et afsendersystem eller hele myndigheden. Dette har betydning for hvilke slutbrugere der returneres i tilmeldingslister. Komplette lister eller ændringslister ønskes. Dette har betydning for de tilmeldingslister der produceres. Bilag A2: REST Register 8

9 A2.3 Ressourcer Følgende ressourcer og typer anvendes i forbindelse med registre. SlutbrugerSamlingReferenceSamling SlutbrugerSamling Slutbruger SlutbrugerStamdata GruppetilmeldingSamling Myndighedstilmelding Gruppetilmelding SlutbrugerSamlingReferenceSamling - Indeholder en reference til en slutbrugerliste. Dette kan enten være en komplet liste eller en ændringsliste. En slutbrugerliste kan pga. størrelse være delt i et antal dellister; ressourcen inkluderer således en samling af referencer til hver delliste. SlutbrugerSamling - Indeholder en liste af ressourcen Slutbruger som indeholder stamdata og tilmeldinger. Slutbruger - Beskriver en slutbrugers stamdata samt tilmeldinger. Tilmeldingerne fremgår både for den specifikke myndighed på myndighedsniveau og tilmeldingsgruppe-niveau, SlutbrugerStamdata - Indeholder stamdata for en slutbruger, hvilket bl.a. inkluderer CPR-/CVR-nummer, navn, mobilnummer, adresse, og DKAL status. Ressourcen indgår i ressourcen Slutbruger. Myndighedstilmelding - Beskriver en slutbrugers tilmelding på myndighedsniveau til 1) en specifik myndighed, eller 2) alle myndigheder. Af tilmeldingen fremgår bl.a. hvorvidt adviseringer ønskes via SMS og/eller samt hvorvidt brugeren automatisk ønsker at tilmelde sig nye myndigheder / tilmeldingsgrupper. GruppetilmeldingSamling - Indeholder en liste af tilmeldinger på tilmeldingsgruppe-niveau. Gruppetilmelding - Beskriver en tilmelding på tilmeldingsgruppe-niveau. Af tilmeldingen fremgår bl.a. hvorvidt adviseringer ønskes via SMS og/eller . Bilag A2: REST Register 9

10 A2.3.1 SlutbrugerSamlingReferenceSamling RESSOURCE SlutbrugerSamlingReferenceSamlin g Ressourcen indeholder en liste af referencer til slutbrugerlister med stamdata og tilmeldinger for hver slutbruger. Tilmeldingerne er angivet på myndigheds- og tilmeldingsgruppeniveau. Listen indeholder følgende felt på overordnet niveau R SlutbrugerSamlingURLreference Identificerer listen. Relevant for ændringslister hvor en liste skal slettes førend der opnås adgang til den næste ændringsliste. Indeholder en liste af SlutbrugerDelSamlingURLreference, der hver refererer til en del af slutbrugerlisten. A2.3.2 SlutbrugerSamling SlutbrugerSamling RESSOURCE Ressourcen indeholder en liste af slutbrugere med stamdata og tilmeldinger for hver slutbruger. Tilmeldingerne er angivet på myndigheds- og tilmeldingsgruppeniveau. Det kan enten være en komplet liste af tilmeldinger eller en liste af ændring af tilmeldinger. Indeholder en liste af ressourcen Slutbruger. A2.3.3 Slutbruger Slutbruger RESSOURCE Ressourcen indeholder information om en slutbrugers stamdata og tilmeldinger. Tilmeldingerne er opdelt i myndigheds-tilmelding og tilmeldingsgruppe-tilmelding. Bilag A2: REST Register 10

11 Specielt for ændringslist er Når denne ressource indgår i ressourcen Slutbrugere og der er tale om en ændringsliste, medtages kun de informationer, der er blevet ændret. Her vil typerne Stamdata, Myndighedstilmelding og Gruppetilmeldinger kun være angivet såfremt en ændring har fundet sted. Er en slutbrugers mobilnummer f.eks. blevet opdateret vil typen Stamdata være angivet. Hvert element i listen er en sekvens af nedenstående C SlutbrugerIdentitet CPR / CVR nummer på slutbrugeren. R SlutbrugerStamdata Informationer om slutbrugeren, bl.a. navn, mobilnummer og adresse. R Myndighedstilmelding Tilmeldinger for en slutbruger på myndighedsniveau. R GruppetilmeldingSamling Liste af tilmeldinger for en slutbruger på tilmeldingsgruppeniveau. Er en slutbruger tilmeldt på myndighedsniveau, slår det igennem på tilmeldingsgruppeniveau, således at brugeren optræder som værende tilmeldt alle myndighedens grupper. A2.3.4 Myndighedstilmelding Myndighedstilmelding RESSOURCE Ressourcen beskriver en slutbrugers tilmelding til 1) den myndighed som registret tilhører, eller 2) alle myndigheder. En bruger som tilmelder sig en myndighed vil optræde som være tilmeldt alle myndighedens tilmeldingsgrupper. En slutbruger som er tilmeldt alle myndigheder vil optræde som være tilmeldt alle myndigheder og deres tilmeldingsgrupper. R MyndighedIdentifikator Angiver CVR-nummeret på myndigheden, som denne tilmelding vedrører. U MyndighedTilmeldtIndikator ja nej. Er brugeren tilmeldt den pågældende myndighed. U AlleMyndighederTilmeldt Indikator ja nej. Er brugeren tilmeldt alle myndigheder. Er denne ja, sættes MyndighedTilmeldtIndikator automatisk til ja. Det er uafklaret hvorvidt denne facilitet stilles til rådighed i den endelige udgave. Bilag A2: REST Register 11

12 U AdviseringSMSindikator ja nej. Adviser brugeren via SMS når nye servicebeskeder / meddelelser ankommer til DKAL. Er feltet ikke angivet, anvendes slutbrugerens standardopsætning. U Advisering Indikator ja nej. Adviser brugeren via når nye servicebeskeder / meddelelser ankommer til DKAL. Er feltet ikke angivet, anvendes slutbrugerens standardopsætning. A2.3.5 GruppetilmeldingSamling GruppetilmeldingSamling Typen beskriver samling af tilmeldingsgrupper. TYPE Indeholder en liste af ressourcen Gruppetilmelding. A2.3.6 Gruppetilmelding Gruppetilmelding RESSOURCE Ressourcen beskriver en slutbrugers tilmelding til en tilmeldingsgruppe. I nogle situationer ønskes en liste indeholdende både de tilmeldingsgrupper som brugeren er tilmeldt samt de tilmeldingsgrupper som brugeren kan tilmelde sig for en specifik myndighed. Denne ressource anvendes til at beskrive begge dele, idet feltet TilmeldingsgruppeTilmeldtIndikator angiver den aktuelle status for tilmeldingsgruppen. R GruppetilmeldingURLreference Reference ressourcen. R TilmeldingsgruppeNavn Navnet på tilmeldingsgruppen. U AdviseringSMSindikator ja nej. Adviser brugeren via SMS når nye meddelelser (heriblandt servicebeskeder) ankommer til DKAL. Er feltet ikke angivet, anvendes slutbrugerens standardopsætning. Bilag A2: REST Register 12

13 U Advisering Indikator ja nej. Adviser brugeren via når nye meddelelser (heriblandt servicebeskeder) ankommer til DKAL. Er feltet ikke angivet, anvendes slutbrugerens standardopsætning. R TilmeldingsgruppeTilmeldt Indikator Angiver om slutbrugeren er tilmeldt denne tilmeldingsgruppe. Anvendes når en liste af tilmeldinger også indeholder tilmeldingsgrupper, som brugeren har mulighed for at tilmelde sig. A2.3.7 SlutbrugerStamdata SlutbrguerStamdata Ressourcen indeholder stamdata for en slutbruger. RESSOURCE Hvert element i listen er en sekvens af nedenstående felter R SlutbrugerIdentitet CPR / CVR nummer på slutbrugeren. C SlutbrugerNavn Slutbrugerens navn som angivet ved oprettelsen. U MobilNummer Slutbrugerens mobiltelefonnummer. Hele nummeret vil ikke være læsbart, med mindre fuld visning er tilkøbt. Et eksempel på et sløret nummer er ****. Når nummeret opdateres, vil slutbrugeren automatisk blive bedt om at verificere dette. Det er angivet om nummeret er blevet verificeret eller ej. U EpostAdresseFoerste Angiver brugerens private adresse som der sendes adviseringer til i det omfang brugeren ønsker. Når adressen opdateres, vil slutbrugerne automatisk blive bedt om at verificere den. Det er angivet om adresse er blevet verificeret eller ej. adressen er kun delvist angivet, f.eks. som anders@*****, og anvendes som et hint til slutbrugeren, der kan genkende sin adresse. Den fulde adresse er således aldrig tilgængelig for et register. Bilag A2: REST Register 13

14 U EpostAdresseAnden Som første adresse. U SlutbrugerDKALstatusKode Angiver modtagerens DKAL status: 0: Ikke tilmeldt 1: Kun tilmeldt som servicebeskedmodtager. 2: Har accepteret DKAL vilkår. En slutbruger har kun en sikker boks, når DKAL vilkår er accepteret. Ved oprettelse af en slutbruger anvendes dette felt til at angive om hvilken type oprettelse slutbrugeren ønsker. Ønsker slutbrugeren at kunne modtage meddelelser udover servicebeskeder, vil dette kun være en foreløbig oprettelse. Slutbrugeren skal efterfølgende selv logge ind og bekræfte. R SlutbrugerEboksStatusKode Angiver modtagerens e-boks status: 0: Ikke tilmeldt. 1: Tilmeldt. R SlutbrugerRegistreringDatoTid Angiver tidspunktet for oprettelse af slutbrugeren. Bilag A2: REST Register 14

15 A2.4 Operationer Følgende operationer er tilgængelige for registre. A2.4.1 Hent reference til slutbrugerliste /register/{sysid}/slutbrugerliste GET Hent reference til en bestilt slutbrugerliste indeholdende en liste af slutbrugere. Pga. størrelse kan en slutbrugerliste være delt i flere dele, så der bliver også hentet en liste en referencer til hver del af listen. Ændringslister Kompletliste Konfiguration Såfremt registret ønsker ændringslister produceres en ændringsliste. Ændringerne hentes efter behov fra en kø med et aftalt interval. Den ældste ændringsliste returneres altid via dette kald. Når denne liste er modtaget og behandlet skal det bekræftes ved at slette den. Herefter skal denne operation kaldes igen. Denne proces fortsætter indtil der alle tilgængelige ændringslister er behandlet. Såfremt registeret ønsker komplette lister produceres en komplet liste. Er komplet liste bliver fjernet når en ny liste er blevet produceret. Er et register i gang med at hente de enkelte dele af en liste, når den bliver fjernet, skal registeret hente referencen til den nye komplette liste, og hente delene i denne liste. Se afsnit (se A2.2.1) Input parametre sysid Identificerer registret. Fremgår af administrationsportalen. Output content (OIOXML) Slutbruger Samling Reference Samling Reference til en slutbrugerliste og den dellister. Fejlkoder 121 Ingen adgang til system {sysid} (401) Bilag A2: REST Register 15

16 A2.4.2 Hent slutbruger delliste /register/{sysid}/slutbrugerliste/{slutbrugerlisteid}/ {dellisteid} Input parametre GET Hent en del af en bestilt slutbrugerliste indeholdende en liste af slutbrugere. For hver slutbruger er angivet stamdata, tilmeldinger på tilmeldingsgruppeniveau, og tilmelding på myndighedsniveau. sysid slutbrugerlisteid dellisteid Identificerer registret. Fremgår af administrationsportalen. Identificerer slutbrugerlisten. Identificerer delliste, der er en del af en slutbrugerliste. Output content (OIOXML) Slutbruger Samling En liste med slutbrugere. Fejlkoder 121 Ingen adgang til system {sysid} (401) Pseudo kode eksempel // Hent ændringsliste med slutbrugere, som er delt i flere dele string uri = "/register/1234/slutbrugerliste"; SlutbrugerSamlingReferenceSamling slutbrugerlisteref = HTTP_GET(uri); // Iteration over alle dellister foreach (SlutbrugerSamlingReference uri in slutbrugerlisteref) { } SlutbrugerSamling slutbrugere = HTTP_GET(uri); // Iteration over alle Slutbrugere foreach (Slutbruger slutbruger in slutbrugere) { string identitet = slutbruger.slutbrugeridentitet; if (slutbruger.stamdata!= null) // stamdata er blevet opdateret if (slutbruger.myndighedstilmelding!= null //slutbruger.myndighedstilmelding.tilmeldtmyndighedindikator } HTTP_DELETE(slutbrugere.SlutbrugerSamlingURLreference); Bilag A2: REST Register 16

17 A2.4.3 Slet ændringsliste /register/{sysid}/slutbrugerliste/{slutbrugerlisteid} Input Parametre DELETE Såfremt et register anvender ændringslister, skal en ændringsliste slettes førend den næste kan hentes. Slutbrugerlisten slettes således som en helhed, og det er ikke hver enkelt delliste, der slettes. sysid slutbrugerlisteid Identificerer registret. Fremgår af administrationsportalen. Identificerer en specifik ændringsliste. Denne id er angivet i den specifikke ændringsliste, som ønskes slettet. URI en for den specifikke ændringsliste er angivet i selve listen. Fejlkoder 121 Ingen adgang til system {sysid} (401) 145 Ukendt identifikation {slutbrugerlisteid} (404) Pseudo kode eksempel Se eksemplet for A A2.4.4 Hent en slutbrugers stamdata og tilmeldinger /register/{sysid}/slutbruger/{cpr} /register/{sysid}/slutbruger/{cvr} GET Returnerer en slutbrugers stamdata og tilmeldinger. Stamdata inkludere bl.a. slutbrugerens navn, mobilnummer, adresse, og status. Tilmeldingerne inkluderer: de tilmeldingsgrupper, som slutbrugeren er tilmeldt for det aktuelle register, samt oplysning om slutbrugeren har tilmeldt sig 1) alt for den myndighed registret er tilknyttet eller 2) har tilmeldt sig alt for alle myndigheder. Bilag A2: REST Register 17

18 Kommentar En af søgeparametrene CPR eller CVR skal være udfyldt. Input parametre sysid cpr cvr Identificerer registret. Fremgår af administrationsportalen. Angiver slutbrugeren, når det er en borger. Angiver slutbrugeren, når det er en virksomhed/myndighed. Input søgeparametre IkkeTilmeldte Indikator Hvis angivet inkluderes også de tilmeldingsgrupper, som slutbrugeren ikke er tilmeldt for myndigheden som registret er tilknyttet. For hver tilmeldingsgruppe vil det fremgå om slutbrugeren er tilmeldt eller ej. Output content (OIOXML) Slutbruger Information om slutbrugeren. Eksempel /register/4/slutbruger/ ?ikketilmeldte=1. Et specifikt register forespørger på en virksomheds stamdata samt tilmeldte og ikke tilmeldte tilmeldingsgrupper for den myndighed som registeret er tilknyttet. Fejlkoder 121 Ingen adgang til system {sysid} (401) 132 Ugyldig soegeparameter {parameter} (400) 146 Ukendt slutbruger (404) Pseudo kode eksempel // CVR string uri = "/register/1234/slutbruger/ "; // Hent tilmeldinger overordnet Slutbruger slutbruger = HTTP_GET(uri); Bilag A2: REST Register 18

19 A2.4.5 Opret boks / opdater stamdata /register/{sysid}/boks/{cpr} /register/{sysid}/boks/{cvr} Input parametre PUT Opret boks for den angivne slutbruger, eller opdater en eksisterende slutbrugers stamdata. Når en slutbruger oprettes skal det angives via slutbrugerens stamdata, om vedkommende ønsker at modtage servicebeskeder, eller om det også ønskes at modtage andre meddelelser. En servicebeskedmodtager kan oprettes omgående, hvorimod de resterende meddelelser (personfølsomme) kræver at brugeren efterfølgende logger ind og acceptere vilkårene førend vedkommende kan modtage afsendelser. sysid cpr cvr Slutbruger Stamdata Identificerer registret. Fremgår af administrationsportalen. Angiver slutbrugeren, når det er en borger. Angiver slutbrugeren, når det er en virksomhed/myndighed. Slutbrugerens stamdata. Fejlkoder 101 Max graense for data overskredet {datamaengde} (500) 121 Ingen adgang til system {sysid} (401) 133 Ugyldig felt i indhold {feltnavn} (400) 146 Ukendt slutbruger (404) Bilag A2: REST Register 19

20 Pseudo kode eksempel // CVR string uri = "/register/1234/boks/ "; SlutbrugerStamdata boks = new SlutbrugerStamdata() { SlutbrugerNavn = Niels Borgersen, AdresseFoerste. = borgersen@..., SlutbrugerDKALstatus = 2 } // Opret / opdater boks HTTP_PUT(uri, boks); A2.4.6 Til / afmeld en slutbruger til en myndighed / alle myndigheder /register/{sysid}/boks/{cpr}/myndighedstilmelding /register/{sysid}/boks/{cvr}/myndighedstilmelding PUT Til- og afmeld slutbrugeren på myndighedsniveau. Via dette kald kan en slutbruger til- og afmeldes 1) Den myndighed som registret er tilknyttet. En tilmelding her angiver at slutbrugeren er tilmeldt alle tilmeldingsgrupper for denne myndighed samt automatisk tilmeldes nye tilmeldingsgrupper når disse oprettes. Eller 2) Alle myndigheder. En tilmelding til alle myndigheder betyder at slutbrugeren er tilmeldt alle myndigheder samt automatisk tilmeldes nye myndigheder når disse oprettes. Myndigheden som tilmeldingen vedrører Den specifikke myndighed der kan til- og afmeldes er den som registeret er tilknyttet. Det vil sige den myndighed, der har oprettet registeret i administrationsportalen. Input parametre sysid cpr cvr Identificerer registret. Fremgår af administrationsportalen. Angiver slutbrugeren, når det er en borger. Angiver slutbrugeren, når det er en virksomhed/myndighed. Input Content (OIOXML) Myndigheds tilmelding Indeholder den nye tilmelding / opdatering af en eksisterende. Bilag A2: REST Register 20

21 Fejlkoder 101 Max graense for data overskredet {datamaengde} (500) 121 Ingen adgang til system {sysid} (401) 133 Ugyldig felt i indhold {feltnavn} (400) 146 Ukendt slutbruger (404) Pseudo kode eksempel // Tilmeld brugeren til den myndighed som registret er tilknyttet Myndighedstilmelding mt = new Myndighedstilmelding() { TilmeldtMyndighedIndikator = true } // CVR string uri = "/register/1234/boks/ /myndighedstilmelding"; HTTP_PUT(uri, mt); A2.4.7 Tilmeld / afmeld en slutbruger til en tilmeldingsgruppe /register/{sysid}/boks/{cpr}/tilmeldingsgrupper/{tid} /register/{sysid}/boks/{cvr}/tilmeldingsgrupper/{tid} PUT Opret en ny tilmelding af en slutbruger til en tilmeldingsgruppe, eller opdater en eksisterende tilmelding. Afhængig af registrets tilknytning til et afsendersystem / hele myndigheden afgrænses hvilke tilmeldingsgrupper der kan tilmeldes. Konfiguration Se afsnit (se A2.2.1) Input parametre sysid cpr cvr Identificerer registret. Fremgår af administrationsportalen. Angiver slutbrugeren, når det er en borger. Angiver slutbrugeren, når det er en virksomhed/myndighed. Bilag A2: REST Register 21

22 tid Identifikation af tilmeldingsgruppen. Kan findes via administrationsportalen, eller via en forespørgsel på en slutbrugers tilmeldinger hvor IkkeTilmeldte tilmeldingsgrupper medtages. Input content (OIOXML) Gruppetilmelding Indeholder den nye tilmelding, eller opdatering af en eksisterende. Fejlkoder 101 Max graense for data overskredet {datamaengde} (500) 121 Ingen adgang til system {sysid} (401) 133 Ugyldig felt i indhold {feltnavn} (400) 144 Ukendt tilmeldingsgruppe {tilmeldingsgruppeid} (404) 146 Ukendt slutbruger (404) Pseudo kode eksempel // Tilmeld brugeren til en tilmeldingsgruppe Gruppetilmelding gt = new Gruppetilmelding() { Advisering Indikator = true } // CVR string uri = "/register/1234/boks/ /myndighedstilmelding/54"; HTTP_PUT(uri, gt); A2.4.8 Slet en tilmelding for en slutbruger /register{sysid}/boks/{cpr}/tilmeldingsgrupper/{tid} /register{sysid}/boks/{cvr}/tilmeldingsgrupper/{tid} Input parametre Afmeld en slutbruger fra en specifik tilmeldingsgruppe. DELETE sysid cpr Identificerer registret. Fremgår af administrationsportalen. Angiver slutbrugeren, når det er en borger. Bilag A2: REST Register 22

23 cvr tid Angiver slutbrugeren, når det er en virksomhed/myndighed. Identificerer tilmeldingsgruppen Fejlkoder 121 Ingen adgang til system {sysid} (401) 143 Ukendt indholdstype {indholdstypeid} (404) 144 Ukendt tilmeldingsgruppe {tilmeldingsgruppeid} (404) 146 Ukendt slutbruger (404) Pseudo kode eksempel string uri = "/register/1234/boks/ /myndighedstilmelding/54"; HTTP_DELETE(uri); Bilag A2: REST Register 23