Anvenderguide til Stamdatamodulet KOMBIT

Transkript

1 Anvenderguide til Stamdatamodulet KOMBIT

2 1 Indholdsfortegnelse 1 Indholdsfortegnelse Historik Formål & Målgruppe Introduktion til Stamdatamodulet Forudsætninger Replikeringsservice Overførsel af stamdata Parsing af output Paginering Statuskoder Registre Cpr Forbrugsinformation Adgang til test- og udviklingsmiljø XML schema... 9 Anvenderguide 2

3 2 Historik Dato Version Ændring Ansvarlig 5. maj OFO, AHJ 19. maj Rettelser efter KOMBIT review SEF 9. juni Rettelser efter KOMBIT-review OFO Anvenderguide 3

4 3 Formål & Målgruppe Målgruppen for dette dokument er systemudviklere som skal bruge Stamdatamodulet til at replikere hele registre. 4 Introduktion til Stamdatamodulet Stamdatamodulet er en delt komponent til at tilgå data, f.eks. CPR-data. Stamdatamodulet består af en replikerings-service som man kan bruge til at kopiere hele registre og holde en lokal kopi af alle data. 4.1 Forudsætninger For at kunne tilgå de forskellige registre skal anvenderen indgå en aftale med KOMBIT, og anvenderen skal anskaffe et OCES-certifikat, som autentificerer anvenderen overfor serveren, og benyttes når anvendersystemet tilgår et register. Funktions- eller medarbejdercertifikater kan anvendes. 5 Replikeringsservice Replikeringsservicen giver systemer mulighed for at holde en lokal kopi af et register, som f.eks. CPR-registeret URI-format Før du læser om kommunikationsprotokollen i detaljer, er det vigtigt at forstå hvordan registre og datatyper er navngivet. Ressourcer (datatyper) er ordnet i et hierarkisk URInavnerum med URI-skemanavnet stamdata. stamdata://[register]/[view]/[version]?[query] URI-autoriteten, markeret i blåt med teksten register, repræsenterer registeret hvor data kommer fra, f.eks. the Central Person Register (CPR). URI-path-delen starter med en skråstreg '/' efterfulgt af navnet på den datatype (også kaldet view) man vil hente markeret i grønt med teksten view og hvilken version man ønsker, markeret i rødt med teksten version. Til sidst kan man med sende en række parametre som specificerer hvor langt man er nået i et udtræk, og hvor mange records man ønsker at hente ad gangen. Paginering bliver beskrevet i mere detalje til sidst i afsnit Overførsel af stamdata NB. Der findes en referenceimplementation af et klient-library til at kommunikere med replikeringsservicen. Klienten er skrevet i Java. Anvenderguide 4

5 5.2.1 Autentifikation Autentifikation sker ved hjælp af tovejs-ssl baseret på OCES-infrastrukturen. I PoC en anvendes et af Netic self signed-certifikat på serversiden. Første gang man tilgår løsningen skal man acceptere/stole på denne server Forespørgsler til replikeringsservicen Eksempel 1: Request GET /replication/cpr/person/v1 HTTP/1.1 Host: stage01.kombit.netic.dkk Accept: application/atom+xml Stamdata-replikeringsservicen er baseret på ATOM 1.0 [RFC4287]. ATOM er en syndikeringstilfælde er protokol og designet til at holde styr på ændringer i en ressource. I dette ressourcerne registre, eller nærmere bestemt data-typerne i de registre. ATOM er en REST- baseret protokol, som anvender HTTP. Dette kald henter data fra datatypen cpr/person/v1. Datatypen er bestemt ud fra den path man sender, se linje 1. Benyttes andre end GET fås 405 method not allowed som retursvar. Ønsker man at starte dataoverførsel fra et bestemt tag tilføjes offset=<værdi>. Paginering kan opnås ved at tilføje count=<antal>. Fx GET /replication/cpr/person/v1?offset=100000&count=5000 HTTP/1.1 Man har her valgt at få data overført i ATOM-format og sætter accept-headeren til application/atom+xml, se linje 3. Anvenderguide 5

6 På nuværende tidspunkt understøtter servicen output med følgende formater: ATOM-feed i XML (application/atom+xml) ATOM-feed i Fast Infoset (application/atom+fastinfoset) Du skal angive en af disse to i Accept-headeren Eksempel 1 (Fortsat): Response Svaret på et kald til replikerings-servicen er et ATOM-feed. Her er et response som kunne være kaldet i Eksempel 1. Du kan bruge ethvert ATOM-API til at parse det. HTTP/ OK Link: <stamdata://cpr/person/v1?offset= >; rel="next" <?xml version='1.0' encoding='utf-8'?> <feed xmlns=" xmlns:sd=" <id>tag:trifork.com,2011:cpr/person/v1</id> <updated> t05:31:13.049z</updated> <title>stamdata Registry Feed</title> <author> <name>trifork Public A/S</name> < >stamdata.support@trifork.com</ > </author> <entry> <id>tag:trifork.com,2011:cpr/person/v1/ </id> <title /> <updated> t13:00:43.000z</updated> <content type="application/xml"> <sd:person> <sd:cpr> </sd:cpr> <sd:koen>m</sd:koen> <sd:fornavn>hjalte</sd:fornavn> <sd:mellemnavn></sd:mellemnavn> <sd:efternavn>gulbæk-bruun</sd:efternavn> <sd:conavn></sd:conavn> <sd:lokalitet></sd:lokalitet> <sd:vejnavn>nørre Tranders Vej</sd:vejnavn> <sd:bygningsnummer></sd:bygningsnummer> <sd:husnummer>115</sd:husnummer> <sd:etage></sd:etage> <sd:sidedoernummer></sd:sidedoernummer> <sd:bynavn></sd:bynavn> <sd:postnummer>9000</sd:postnummer> <sd:postdistrikt>aalborg</sd:postdistrikt> <sd:status>01</sd:status> <sd:gaeldendecpr></sd:gaeldendecpr> <sd:foedselsdato> t00:00:00+01:00</sd:foedselsdato> <sd:stilling></sd:stilling> <sd:vejkode>6125</sd:vejkode> <sd:kommunekode>851</sd:kommunekode> <sd:validfrom> t00:00:00+01:00</sd:validfrom> <sd:validto> t00:00:00+01:00</sd:validto> </sd:person> </content> </entry> <entry> <id>tag:trifork.com,2011:cpr/person/v1/ </id> <title /> <updated> t13:00:43.000z</updated> <content type="application/xml"> <sd:person> Anvenderguide 6

7 </feed> </entry> <sd:cpr> </sd:cpr> <sd:koen>m</sd:koen> <sd:fornavn>hjalts</sd:fornavn> <sd:mellemnavn></sd:mellemnavn> <sd:efternavn>gulbæk-bruun</sd:efternavn> <sd:conavn></sd:conavn> <sd:lokalitet></sd:lokalitet> <sd:vejnavn>nørre Tranders Vej</sd:vejnavn> <sd:bygningsnummer></sd:bygningsnummer> <sd:husnummer>115</sd:husnummer> <sd:etage></sd:etage> <sd:sidedoernummer></sd:sidedoernummer> <sd:bynavn></sd:bynavn> <sd:postnummer>9000</sd:postnummer> <sd:postdistrikt>aalborg</sd:postdistrikt> <sd:status>01</sd:status> <sd:gaeldendecpr></sd:gaeldendecpr> <sd:foedselsdato> t00:00:00+01:00</sd:foedselsdato> <sd:stilling></sd:stilling> <sd:vejkode>6125</sd:vejkode> <sd:kommunekode>851</sd:kommunekode> <sd:validfrom> t00:00:00+01:00</sd:validfrom> <sd:validto> t00:00:00+01:00</sd:validto> </sd:person> </content> Hvis vi havde sat Accept-headeren til application/atom+fastinfoset, havde output været i FastInfoset-format, men med samme struktur som dette eksempel. 5.3 Parsing af output Det mest interessante ved et response er entry -elementerne. Hvert entry -element indeholder et snapshot af en record fra registeret. Med snapshot menes at det var sådan data så ud på et bestemt tidspunkt. Stamdatamodulet bruger fuld historik når man laver et udtræk. Det vil sige at du kan få information om hvordan f.eks. en person-record så ud for 1 år siden med adresse, navn etc. Der er ingen garanti for hvor langt tilbage i tiden Stamdatamodulet har information dette afhænger af den konkrete driftsopsætning. Hvert entry-element har et content -element som indeholder alt domæne-data. I eksemplet ovenfor er det datatypen person som er indeholdt. Afsnit 8 indeholder det præcise indhold for person/cpr. Det er to slags nøgler som identificerer en record: Unikke nøgler og revisionsnumre Unikke nøgler Hver view-type har et eller flere elementer som unikt bestemmer en record. Et eksempel er at i CPR-regsiteret er en person unikt bestemt ved sit CPR-nummer. Derfor vil man, når man persisterer records fra cpr/person/v1 bruge cpr-elementet som unik nøgle. Unikke nøgler for de enkelte views er beskrevet i afsnit Revisionsnumre Anvenderguide 7

8 Revisionsnumre bestemmer en record unikt. Man kan se det som en unik primær nøgle i en database. Et revisionsnummer er også en slags historisk id. Det vil sige at det bestemmer en record unikt i historien, i modsætning til unikke nøgler. Revisionsnummeret kan findes ved at kigge på entry-elementernes id-element. F.eks. i tag:trifork.com,2011:cpr/person/v1/ er revisionsnummeret. Med andre ord bestemmer en unik nøgle en bestemt entitet, mens revisionsnummeret bestemmer et snapshot af den entitet. Begge disse numre er vigtige på flere måder. Den unikke nøgle kan optræde i flere forskellige entry-elementer. Det skyldes at en entitet ændrer sig med tiden, men revisionsnumre vil altid være forskellige. 5.4 Paginering Antallet af records i et register kan være meget stort, i visse tilfælde flere millioner records. Derfor bliver man nødt til at opdele et udtræk i flere pages. Response fra Eksempel 1 er et eksempel på en page. Ved at se på HTTP-headers i responset kan man se at der er en Link-header, gengivet her: Link: <stamdata://cpr/person/v1?offset= >; rel="next" Web Linking er beskrevet i RFC5988. Et link som dette peger på den næste page hvor man skal hente data. URI en skal omdannes til en URL som passer der hvor servicen er placeret. F.eks.: Flowet er beskrevet i diagrammet i afsnit 5.2. Så længe man modtager en Link-header, betyder det at der er flere opdateringer man bør hente. 5.5 Statuskoder Status Beskrivelse 200 OK, alt gik som forventet. 400 Der var en parameter i dit request, f.eks. en query-parameter, som ikke var gyldig xx Der opstod en fejl som har med token og adgangstilladelse at gøre, eller også findes ressourcen ikke. Der opstod en anden fejl. Anvenderguide 8

9 6 Registre Dette afsnit danner et overblik over de forskellige registre der findes i Stamdata. Hvert register kan have mange views (datatyper). Der findes XSD-skemaer for alle views i et register se afsnit Cpr Cpr-data ligger under registret cpr. View Navn Unik nøgle Aktuel civilstand civilstand Cpr Barnrelation barnrelation Cpr, barnets cpr Fødselsregistreringsoplysninger foedselsregistreringsoplysninger Cpr Folkekirkeoplysninger folkekirkeoplysninger Cpr Forældremyndighedrelation foraeldremyndighedsrelation Cpr, mor eller far Hændelse haendelse Unik genereret id Kommunale forhold kommunaleforhold Cpr Mor- og far-oplysninger morogfaroplysninger Cpr, forældertypekode Personoplysninger person Cpr Statsborgerskab statsborgerskab Cpr Udrejseoplysninger udrejseoplysninger Cpr Umyndiggørelse-værge-relation umyndiggoerelsevaergerelation Cpr, typekode Valgoplysninger valgoplysninger Cpr 6.2 Forbrugsinformation Forbrugsinformation ligger under registret usage. View Navn Unik nøgle Klient-specifikt forbrug client Unik genereret id Forbrug på tværs af klienter aggregate Unik genereret id 7 Adgang til test- og udviklingsmiljø Replikeringstjenesten ligger i udviklingsmiljøet her: I testmiljøet tilgås replikeringstjenesten her: Tilgængelighed (oppetidskrav) er angivet i Driftsvejledningen. Miljøerne er tilgængelige indtil 30/ XML schema Følgende udgør skemaet for common (som benyttes i cpr). <?xml version="1.0" encoding="utf-8" standalone="yes"?> Anvenderguide 9

10 <xs:schema version="1.0" targetnamespace=" xmlns:xs=" <xs:complextype name="view" abstract="true"> <xs:all/> </xs:schema> Følgende udgør skemaet for person/cpr. Felterne svarer til de tilsvarende felter fra CPR, undtagen datoer, hvor specielle dato-værdier fra CPR konverteres til gyldige datoer. Se beskrivelsen i Design og Arkitektur for mere information om dette. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema elementformdefault="qualified" version="1.0" targetnamespace=" /stamdata/3.0/cpr" xmlns:ns1=" xmlns:tns=" xmlns:xs=" <xs:import namespace=" schemalocation="common.xsd"/> <xs:element name="barnrelation" type="tns:barnrelation"/> <xs:element name="civilstand" type="tns:civilstand"/> <xs:element name="foedselsregistreringsoplysninger" type="tns:foedselsregistreringsoplysninger"/> <xs:element name="folkekirkeoplysninger" type="tns:folkekirkeoplysninger"/> <xs:element name="foraeldremyndighedsrelation" type="tns:foraeldremyndighedsrelation"/> <xs:element name="haendelse" type="tns:haendelse"/> <xs:element name="kommunaleforhold" type="tns:kommunaleforhold"/> <xs:element name="morogfaroplysninger" type="tns:morogfaroplysninger"/> Anvenderguide 10

11 <xs:element name="person" type="tns:person"/> <xs:element name="statsborgerskab" type="tns:statsborgerskab"/> <xs:element name="udrejseoplysninger" type="tns:udrejseoplysninger"/> <xs:element name="umyndiggoerelsevaergerelation" type="tns:umyndiggoerelsevaergerelation"/> <xs:element name="valgoplysninger" type="tns:valgoplysninger"/> <xs:complextype name="statsborgerskab"> <xs:element name="landekode" type="xs:string" minoccurs="0"/> <xs:element name="statsborgerskabstartdatousikkerhedsmarkering" type="xs:string" minoccurs="0"/> <xs:complextype name="umyndiggoerelsevaergerelation"> <xs:element name="id" type="xs:string"/> <xs:element name="typekode" type="xs:string" minoccurs="0"/> Anvenderguide 11

12 <xs:element name="typetekst" type="xs:string" minoccurs="0"/> <xs:element name="relationcpr" type="xs:string" minoccurs="0"/> <xs:element name="relationcprstartdato" type="xs:datetime" minoccurs="0"/> <xs:element name="vaergesnavn" type="xs:string" minoccurs="0"/> <xs:element name="vaergesnavnstartdato" type="xs:datetime" minoccurs="0"/> <xs:element name="relationstekst1" type="xs:string" minoccurs="0"/> <xs:element name="relationstekst2" type="xs:string" minoccurs="0"/> <xs:element name="relationstekst3" type="xs:string" minoccurs="0"/> <xs:element name="relationstekst4" type="xs:string" minoccurs="0"/> <xs:element name="relationstekst5" type="xs:string" minoccurs="0"/> <xs:complextype name="udrejseoplysninger"> <xs:element name="udrejselandekode" type="xs:string"/> <xs:element name="udrejsedato" type="xs:datetime"/> <xs:element name="udrejsedatousikkerhedsmarkering" type="xs:string" minoccurs="0"/> <xs:element name="udlandsadresse1" type="xs:string" minoccurs="0"/> <xs:element name="udlandsadresse2" type="xs:string" minoccurs="0"/> <xs:element name="udlandsadresse3" type="xs:string" minoccurs="0"/> <xs:element name="udlandsadresse4" type="xs:string" minoccurs="0"/> <xs:element name="udlandsadresse5" type="xs:string" minoccurs="0"/> Anvenderguide 12

13 <xs:complextype name="folkekirkeoplysninger"> <xs:element name="forholdskode" type="xs:string" minoccurs="0"/> <xs:complextype name="civilstand"> <xs:element name="civilstandskode" type="xs:string"/> <xs:element name="aegtefaellepersonnummer" type="xs:string" minoccurs="0"/> <xs:element name="aegtefaellefoedselsdato" type="xs:datetime" minoccurs="0"/> <xs:element name="aegtefaellenavn" type="xs:string" minoccurs="0"/> <xs:element name="separation" type="xs:datetime" minoccurs="0"/> Anvenderguide 13

14 <xs:complextype name="valgoplysninger"> <xs:element name="valgkode" type="xs:string" minoccurs="0"/> <xs:element name="valgretsdato" type="xs:datetime" minoccurs="0"/> <xs:element name="valgkode" type="xs:string" minoccurs="0"/> <xs:complextype name="morogfaroplysninger"> <xs:element name="foraelderkode" type="xs:string"/> <xs:element name="dato" type="xs:datetime" minoccurs="0"/> <xs:element name="foedselsdato" type="xs:datetime" minoccurs="0"/> <xs:element name="navn" type="xs:string" minoccurs="0"/> Anvenderguide 14

15 <xs:complextype name="kommunaleforhold"> <xs:element name="kommunalforholdstypekode" type="xs:string" minoccurs="0"/> <xs:element name="kommunalforholdskode" type="xs:string" minoccurs="0"/> <xs:element name="bemaerkninger" type="xs:string" minoccurs="0"/> <xs:complextype name="person"> <xs:element name="koen" type="xs:string" minoccurs="0"/> <xs:element name="fornavn" type="xs:string" minoccurs="0"/> <xs:element name="mellemnavn" type="xs:string" minoccurs="0"/> <xs:element name="efternavn" type="xs:string" minoccurs="0"/> <xs:element name="conavn" type="xs:string" minoccurs="0"/> <xs:element name="lokalitet" type="xs:string" minoccurs="0"/> <xs:element name="vejnavn" type="xs:string" minoccurs="0"/> <xs:element name="bygningsnummer" type="xs:string" minoccurs="0"/> Anvenderguide 15

16 <xs:element name="husnummer" type="xs:string" minoccurs="0"/> <xs:element name="etage" type="xs:string" minoccurs="0"/> <xs:element name="sidedoernummer" type="xs:string" minoccurs="0"/> <xs:element name="bynavn" type="xs:string" minoccurs="0"/> <xs:element name="postnummer" type="xs:integer" minoccurs="0"/> <xs:element name="postdistrikt" type="xs:string" minoccurs="0"/> <xs:element name="status" type="xs:string" minoccurs="0"/> <xs:element name="gaeldendecpr" type="xs:string" minoccurs="0"/> <xs:element name="foedselsdato" type="xs:datetime" minoccurs="0"/> <xs:element name="stilling" type="xs:string" minoccurs="0"/> <xs:element name="vejkode" type="xs:integer" minoccurs="0"/> <xs:element name="kommunekode" type="xs:integer" minoccurs="0"/> <xs:element name="navnebeskyttelsestartdato" type="xs:datetime" minoccurs="0"/> <xs:element name="navnebeskyttelseslettedato" type="xs:datetime" minoccurs="0"/> <xs:element name="validfrom" type="xs:datetime"/> <xs:complextype name="foedselsregistreringsoplysninger"> <xs:element name="foedselsregistreringsstedkode" type="xs:string"/> <xs:element name="foedselsregistreringstekst" type="xs:string"/> Anvenderguide 16

17 <xs:complextype name="foraeldremyndighedsrelation"> <xs:element name="id" type="xs:string"/> <xs:element name="typekode" type="xs:string" minoccurs="0"/> <xs:element name="typetekst" type="xs:string" minoccurs="0"/> <xs:element name="relationcpr" type="xs:string" minoccurs="0"/> <xs:complextype name="haendelse"> <xs:element name="uuid" type="xs:string"/> <xs:element name="ajourfoeringsdato" type="xs:datetime" minoccurs="0"/> <xs:element name="haendelseskode" type="xs:string" minoccurs="0"/> <xs:element name="afledtmarkering" type="xs:string" minoccurs="0"/> <xs:element name="noeglekonstant" type="xs:string" minoccurs="0"/> Anvenderguide 17

18 <xs:complextype name="barnrelation"> <xs:element name="id" type="xs:string"/> <xs:element name="barncpr" type="xs:string" minoccurs="0"/> </xs:schema> Anvenderguide 18