Innehåll
1. Inledning
Dokumentet beskriver hur en lokal PU (LPU) kan nyttja kontrakten SearchPersonsForProfileByOrderUnrestricted och SearchPersonsForProfileByOrder för att hålla en lokal databas uppdaterad med de senaste ändringarna i Ineras Nationella Personuppgiftstjänst (NPU).
Uppdateringar eller Aviseringar
Personuppgiftstjänsten har ingen händelsestyrd aviseringstjänst likt den man får med Skatteverkets aviseringsfiler. Istället erbjuds en Lokal Personuppgiftstjänst att söka efter personposter som matchar olika kriterier och som har förändrats sedan en viss tidpunkt.
Nedan följer några exempel på hur frågor kan utformas för att hämta hem personposter utifrån olika användningsfall. Dessa ska dock endast ses som exempel och ansvaret för att konstruera och testa frågor utifrån sin egen applikations behov ligger på utvecklaren av klientapplikationen.
För att en LPU ska få söka med kontraktet SearchPersonsForProfileByOrderUnrestricted så krävs det att en region äger den lokala tjänsten och därmed är personuppgiftsansvarig (PuA) eller att den som äger LPU har avtal som gör den till personuppgiftsbiträde (PuB).
Följande fyra användningsfall beskrivs.
- Som LPU vill jag hämta de "utomläningar" som har uppdaterats sedan en angiven tid för att ha som backup, alternativt som cache.
- Som LPU vill jag hämta de reservidentiteter som har uppdaterats sedan en angiven tid för att ha som backup, alternativt som cache.
- Som LPU vill jag hämta alla personposter som hör till min(a) region(er) och har uppdaterats sedan en angiven tid, för att ha som backup, alternativt som cache.
- Som LPU vill jag få information om alla de personer som har flyttat ut ur min region sedan en angiven tid. Detta för att jag ska veta att personerna inte längre kommer uppdateras via mina sökfrågor filtrerade på region. Läs mer om begränsningar i tjänstens förmåga att detektera utflyttade i kapitel 4 nedan.
Det krävs att LPU kan ta emot och behandla svaren från NPU som anges i exemplen nedan. Se Tjänstekontraktsbeskrivningen (TKB:n) för fullständig information och strukturen för de anrop och typer som returneras.
Relaterad dokumentation
| Länk | Kommentar |
|---|---|
| TKB | Se beskrivning av domänen strategicresourcemanagement:persons:person på RIVTA |
| SimpleQL | Detaljer om hur en SimpleQL fråga som kan användas i kontrakten konstrueras |
| Filhantering | Detaljer kring filhantering i Nationella Personuppgiftstjänsten |
1.1. Konnektivitet
SOAP-tjänst för att generera filer med sökta personposter och lista tillgängliga filer är tillgängliga via Nationell Tjänsteplattform (NTjP). NTjP saknar dock stöd för REST-baserade tjänster vilket medför att REST-tjänst för att hämta filer (ladda upp/ta bort) enbart är tillgänglig genom direktaccess mot tjänsteproducent.
Anrop mot tjänsterna sker med HTTPS (Mutual-TLS) och validering av certifikatet från tjänstekonsument utförs för att endast tillåta att tjänsten levererar data till tillåtna mottagare. Det är endast beställaren (den som anropat ovan nämnda kontrakt) som kan hämta filerna. Certifikat för upprättande av mTLS-sessionen måste vara ett funtionscertifikat utgivet av SITHS.
Samtliga system som går via NTjP måste kontakta Ineras kundtjänst på kundservice@inera.se för att kunna få direktaccess till filhämtning.
Mejlet ska innehålla följande värden:
- Ämne: "Behörighet för filhämtning PU för miljö: " (TEST eller PROD)
- Anslutande systemets HSA-id på det SITHS-funktionscertifikat som skall användas.
- Relaterat ärendenummer för den TAKning som gjorts i NTjP.
- Systemnamn
- Kontaktuppgifter (e-postadress till funktionsbrevlåda rekommenderas starkt)
1.2. Förändringar av personposter
Tidpunkten för en förändring av en personpost anges i personpostens fält Version. Det finns flera händelser i Personuppgiftstjänsten som orsakar en ny tidsstämpel i detta fält.
- Förändringar hos Skatteverket.
Detta kan ske via de aviseringsfiler som Personuppgiftstjänsten hämtar från Skatteverkets aviseringssystem eller via direktuppslagningar mot Skatteverkets webbservice i Navet. - Förändringar av kontaktuppgifter.
1177 står för merparten av uppdateringarna av personposter då de via invånarsidorna ber de som loggar in att få dela kontaktuppgifter som telefonnummer och e-postadress med vården. - Förändringar av uppgifter på en reservidentitet.
När nya uppgifter sparas för en reservidentitet uppdateras tidsstämpeln i fältet Version. - Kopplingar - OBS! Kommande förändring
I dagens lösning sker ingen uppdatering av fältet Version vid kopplingar av identiteter som t.ex när en reservidentitet kopplas till en personpost som kommer från Skatteverket. Detta kan förstås även det vara av intresse att kunna detektera och förändring av detta planeras att införas under senare delen av 2021.
1.3. Testpersoner
Vid anslutning mot pu.ineratest.org ska frågorna starta med uttrycket includetestidentities = 'true' för att få med de personer som specifikt är markerade som testpersoner, exempelvis:
FROM PersonRecord WHERE includetestidentities = 'true' AND PopulationRegistrationLocality.CountyCode = '3';
Se dokumentationen för SimpleQL för mer information om uppbyggnad av frågor.
2. Grunddataladdning
2.1. Grundladda från geografiskt område
Grundladda det lokala PU-systemet med personer från geografiska områden. Det kan vara allt från en länskod till en blandning av flera läns och kommunkoder.
Vid hämtning av personer som LPU är PuA eller PuB för så får kontraktet med postfix Unrestricted användas.
Detta kontrakt returnerar fullständiga personposter på de som matchar frågan oavsett om de är identitetsskyddade eller inte.
Dela upp sökningen av stora län
Ifall grundladdning ska ske av något av de större länen är det vist att dela upp frågan per kommun istället för att ta hem hela länet i en enda sökning.
Vid uppdelning av en fråga måste man dock tänka på vilken tidsstämpel man använder vid nästa hämtningstillfälle så att man inte missar tiden mellan första och sista frågan i en serie av frågor.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:riv:itintegration:registry:1"
xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderUnrestrictedResponder:3">
<soapenv:Header>
<urn:LogicalAddress>?</urn:LogicalAddress>
</soapenv:Header>
<soapenv:Body>
<urn1:SearchPersonsForProfileByOrderUnrestricted>
<urn1:query>FROM PersonRecord.PopulationRegistrationLocality WHERE (CountyCode IN ("05","06","07") OR (CountyCode = "12" AND MunicipalityCode = "87"));</urn1:query>
<urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
<urn1:profile>P5</urn1:profile>
</urn1:SearchPersonsForProfileByOrderUnrestricted>
</soapenv:Body>
</soapenv:Envelope>
2.2. Grundladda med utomläningar och reservidentiter
I vissa fall vill man hämta personuppgifter på personer som inte är folkbokförda inom sin egen region även kallade "utomläningar" eller så har man en lista på reservidentiteter som man vill hämta hem.
I dessa fall är inte den egna regionen PuA eller PuB för dessa uppgifter och då är det inte tillåtet att nyttja kontraktet med postfix Unrestricted. Data som returneras då kan vara filtrerad p.g.a. identitetsskydd.
Identitetsskydd kan vara i form av sekretessmarkering eller skyddad folkbokföring. Ifall en personpost är skyddsmarkerad på detta sätt filtreras vanligtvis en stor del av personinformationen bort och leveransen sker enligt Profil 1 (se TKB för mer information om profiler).
Begränsa listan med utomläningar
Dela upp sökningen efter utomläningar med max 500 personidentiteter per fråga!
Har er LPU behov av att hämta persondata om reservnummer så kan ni i denna query även skicka in dessa nummer. Då reservidentiteter inte kan identitetsskyddas så vet vi säkert att fullständig data returneras fast än vi inte använder oss av metoden med postfix Unrestricted.
Exempelanrop <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:riv:itintegration:registry:1"
xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderResponder:3">
<soapenv:Header>
<urn:LogicalAddress>?</urn:LogicalAddress>
</soapenv:Header>
<soapenv:Body>
<urn1:SearchPersonsForProfileByOrder>
<urn1:query>FROM PersonRecord.PersonalIdentity WHERE Extension IN ("191212121212","201212121212","199801012392");</urn1:query>
<urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
<urn1:profile>P5</urn1:profile>
</urn1:SearchPersonsForProfileByOrder>
</soapenv:Body>
</soapenv:Envelope>
| Exempelsvar <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SearchPersonsForProfileByOrderResponse
xmlns="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderResponder:3"
xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:3"
xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3.1"
xmlns:ns4="urn:riv:itintegration:registry:1">
<orderId>0118-TO64-12381890</orderId>
</SearchPersonsForProfileByOrderResponse>
</soap:Body>
</soap:Envelope>
|
|---|
Exemplet ovan där SearchPersonsForProfileByOrder anropas returneras ett id på max 36 tecken.
Detta Order-Id används som inparameter till tjänsten GetFilesForOrderId som returnerar ett svar om var den resulterande filen kan hämtas. Ifall ordern inte är redo för nedladdning än så returneras inget svar vilket betyder att anropande tjänst får försöka igen senare.
GetFilesForOrderId returnerar en url som ska användas för att hämta svarsfilen.
Exempelanrop <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:riv:itintegration:registry:1"
xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:GetFilesForOrderIdResponder:3">
<soapenv:Header>
<urn:LogicalAddress>?</urn:LogicalAddress>
</soapenv:Header>
<soapenv:Body>
<urn1:GetFilesForOrderId>
<urn1:orderId>0313-TO69-13130398</urn1:orderId>
</urn1:GetFilesForOrderId>
</soapenv:Body>
</soapenv:Envelope>
| Exempelsvar <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetFilesForOrderIdResponse xmlns="urn:riv:strategicresourcemanagement:persons:person:GetFilesForOrderIdResponder:3"
xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:3"
xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3.1"
xmlns:ns4="urn:riv:itintegration:registry:1">
<multimedia>
<ns2:id>5c41baaa42d8a229f8bf5989</ns2:id>
<ns2:mediaType>application/zip</ns2:mediaType>
<ns2:reference>https://nationellaPU/api/pu/orderedFile/5c41baaa42d8a229f8bf5989</ns2:reference>
</multimedia>
</GetFilesForOrderIdResponse>
</soap:Body>
</soap:Envelope>
|
|---|
REST
| Request | Response |
|---|---|
https://nationellaPU/api/pu/orderedFile/5c41baaa42d8a229f8bf5989 | Statuskod: 200 OK Struktur för filnamn (både ZIP och XML): <orderId>_<datum>_<löpnummer>.zip (samt .xml) Statuskod: 400 BAD_REQUEST Statuskod: 404 NOT FOUND |
Filens innehåll ser ut på samma vis som ett svar från ett vanligt anrop mot SearchPersonsForProfile, specifikationer finns som vanligt i TKB:n.
3. Hämta uppdateringar
Antal uppdateringar per dygn
Antal förändringar per dygn varierar en hel del. Vid ett stickprov för april 2021 så låg antalet förändrade personposter i hela databasen på mellan 20.000 och 120.000 per dygn. Orsaken till de stora mängderna förändringar per dygn är främst uppdateringar av kontaktuppgifter via 1177. Strategier för att få mindre svar kan vara att hämta förändringar flera gånger per dygn eller att dela upp frågan per region.
3.1. Uppdatera personer från ett geografiskt område
Grundladdningsfrågan kan utökas med att endast hämta uppgifter som blivit uppdaterade sedan en viss tidpunkt. Tidpunkten för när en personpost uppdaterades hittar man i fältet Version. Se exempel-frågan nedan.
En personpost får ny version inte bara när Skatteverket gör förändringar utan även när andra förändringar sker som t.ex. förändring av kontaktuppgifter via 1177.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:riv:itintegration:registry:1"
xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderUnrestrictedResponder:3">
<soapenv:Header>
<urn:LogicalAddress>?</urn:LogicalAddress>
</soapenv:Header>
<soapenv:Body>
<urn1:SearchPersonsForProfileByOrderUnrestricted>
<urn1:query>FROM PersonRecord WHERE (PopulationRegistrationLocality.CountyCode IN ("05","06","07") OR (PopulationRegistrationLocality.CountyCode = "12" AND PopulationRegistrationLocality.MunicipalityCode = "87")) AND Version >= "20190220095204";</urn1:query>
<urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
<urn1:profile>P5</urn1:profile>
</urn1:SearchPersonsForProfileByOrderUnrestricted>
</soapenv:Body>
</soapenv:Envelope>
3.2. Uppdateringar på utomläningar och reservidentiteter
På samma sätt som uppdateringar i ett geografiskt område så kan man lägga till villkoret för Version för att hämta utomläningar och reservidentiteter som har uppdaterats sedan sist man frågade.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:riv:itintegration:registry:1"
xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderResponder:3">
<soapenv:Header>
<urn:LogicalAddress>?</urn:LogicalAddress>
</soapenv:Header>
<soapenv:Body>
<urn1:SearchPersonsForProfileByOrder>
<urn1:query>FROM PersonRecord WHERE PersonalIdentity.Extension IN ("191212121212","201212121212","199801012392") AND Version >= "20190220095204";</urn1:query>
<urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
<urn1:profile>P5</urn1:profile>
</urn1:SearchPersonsForProfileByOrder>
</soapenv:Body>
</soapenv:Envelope>
4. Detektera utflyttade från angivna regioner
Personuppgiftstjänsten håller endast totalposter av folkbokföringsregistret och håller inte själv någon förändringshistorik. Det gör det omöjligt att likt Skatteverket leverera aviseringsfiler med enskilda förändringar och orsakskoder för förändringarna.
Det som finns från Skatteverket är deras lista med historiska poster. Problemet med en historisk post från Skatteverket är att de endast innehåller ett folkbokföringsdatum och inte något datum för när den eventuellt slutade gälla.
I ett tidigare försök att lösa detta så lade man i PU på ett datum(localRegistrationTime) som dessutom gjordes sökbart i SimpleQL. Det upptäcktes dock att detta datum hade brister eftersom man egentligen var ute efter när en historisk post slutade gälla.
I version 4.6 har nu även fältet localRegistrationEndTime lagts till och gjorts sökbart i SimpleQL.
Detta fält möjliggör detektering av vilka som flyttat från ett län sedan ett visst datum: "-Ge mig alla personposter som inte är folkbokförd i mina län men har en historisk post i mina län med slutdatum senare än sist jag frågade."
Exempelanropet nedan innehåller en tvådelad SimpleQL-fråga.
Den första delen innan OR-operatorn matchar alla personer(med ett personnummer) som uppdaterats sedan sist jag kollade(20210915162541) förutom personer som är folkbokförda utanför de län jag hanterar.
Den andra delen efter OR-operatorn matchar alla personer(med ett personnummer) som har flyttat från ett av de län jag hanterar till ett av de län jag inte hanterar sedan sist jag kollade(20210915162541).
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:riv:itintegration:registry:1"
xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderResponder:3">
<soapenv:Header>
<urn:LogicalAddress>?</urn:LogicalAddress>
</soapenv:Header>
<soapenv:Body>
<urn1:SearchPersonsForProfileByOrder>
<urn1:query>FROM PersonRecord WHERE ((PopulationRegistrationLocality.CountyCode NOT IN ("01","04") AND Version >= "20210915162541" AND personalidentity.root = 'PNR') OR (PopulationRegistrationLocality.CountyCode IN ("01", "04") AND (PopulationRegistrationRecord.HistoricalRecords.HistoricalRegistrations.CountyCode NOT IN ("01", "04") AND PopulationRegistrationRecord.HistoricalRecords.HistoricalRegistrations.LocalRegistrationEndTime >= "20210915162541" AND personalidentity.root = 'PNR')));</urn1:query>
<urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
<urn1:profile>P5</urn1:profile>
</urn1:SearchPersonsForProfileByOrder>
</soapenv:Body>
</soapenv:Envelope>
Nedan följer ett exempel på den enda historik som finns i en personpost i Personuppgiftstjänsten. Historik som alltså kommer från Skatteverket.
<historicalRecords>
<populationRegistrationLocality>
<populationRegistrationDate>
<format>YYYY-MM-DD</format>
<value>2016-05-31</value>
</populationRegistrationDate>
<countyCode>23</countyCode>
<municipalityCode>80</municipalityCode>
<propertyDesignation>SPRÄNGAREN 6</propertyDesignation>
<populationRegistrationType>FB</populationRegistrationType>
</populationRegistrationLocality>
<populationRegistrationLocality>
<populationRegistrationDate>
<format>YYYY-MM-DD</format>
<value>2005-11-25</value>
</populationRegistrationDate>
<countyCode>23</countyCode>
<municipalityCode>09</municipalityCode>
<propertyDesignation>HÖGSTALÄGDEN 7:1</propertyDesignation>
<populationRegistrationType>FB</populationRegistrationType>
</populationRegistrationLocality>
</historicalRecords>
5. Persistering
Då det finns två kontrakt som returnerar olika mängder data så är det viktigt att anropen mot SearchPersonsForProfileByOrderUnrestricted sker sist i grundladdningen och uppdateringsflödet.
Ett exempel där det annars kan ge oönskade effekter är:
- Avisering på länskod 12 med kontrakt SearchPersonsForProfileByOrderUnrestricted resulterar i att en fullständig personpost hämtas för t.ex 191212121212.
Resulterar i att LPU sparar en fullständig personpost för 191212121212 till sin databas. - Avisering på personer som flyttat från län 12 med kontrakt SearchPersonsForProfileByOrder, 191212121212 har flyttat från län 12 till en ny adress inom län 12. Vi får träff på 191212121212.
Resulterar i att LPU skriver över den fullständiga posten som LPU hade hämtat hem tidigare, 191212121212 riskerar nu att endast innehålla en del av personposten på grund av filtreringen som sker då personen har ett identitetsskydd.