Page tree

Skip to end of metadata
Go to start of metadata

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).

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ör de regioner som ska aviseras.


Följande tre 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 få information om alla de personer som har flyttat ut ur min region sedan en angiven tid, för att jag ska veta att personerna inte längre kommer uppdateras via mitt aviseringsflöde.
  • 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.


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änkKommentar
TKBSe strategicresourcemanagement:persons:person under Tjänstekontrakt för aktuell TKB
SimpleQLDetaljer om hur en SimpleQL fråga som kan användas i kontrakten konstrueras
FilhanteringDetaljer 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) är enbart 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 kontrakten) som kan hämta filerna.

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:

  • Anslutande systemets HSA-id
  • Systemnamn
  • Kontaktuppgifter

2. Grunddataladdning

2.1. Grundladda med utomläningar och reservidentiter

Dessa personer ska vara utomläningar eller reservidentiteter, dvs att LPU inte är PuA eller PuB för dem.
I detta fall är det inte tillåtet att nyttja kontraktet med postfix Unrestricted, datat som returneras kan vara filtrerad p.g.a. identitetsskydd.
Identitetsskydd kan vara i form av sekretessmarkering eller skyddad folkbokföring, har en person något av dessa värden filtreras vanligtvis en stor del av personinformationen bort enligt profil 1, se TKB.


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.

Exempel anrop
<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>
Exempel svar
<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änster GetFilesForOrderId som returnerar ett svar om var den resulterande filen kan hämtas.
Om ordern inte är redo för nedladdning än så returneras inget svar, försök senare.
Då ordern läggs på kö så kan väntetiden variera mycket. Kontakta supporten om din order inte är redo efter 24h.

GetFilesForOrderId returnerar en url som ska användas för att hämta svarsfilen.

Exempel anrop
<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>
Exempel svar
<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

RequestResponse
https://nationellaPU/api/pu/orderedFile/5c41baaa42d8a229f8bf5989

Statuskod: 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="<filnamn>"
Transfer-Encoding: chunked
Content: fil (zippat xmldata enligt strategicresourcemanagement:persons:person)

Struktur för filnamn (både ZIP och XML): <orderId>_<datum>_<löpnummer>.zip (samt .xml)
Exempel: 0622-TO17-09215997_20170622_1.zip

Statuskod: 400 BAD_REQUEST
* Ogiltig context path
* HSA-id för konsument saknas
* Certifikat för OrderId matchar inte certifikat som används vid hämtning av fil
* Filen har redan hämtats

Statuskod: 401 UNAUTHORIZED
* Konsumenten saknar behörighet till tjänsten

Statuskod: 404 NOT FOUND
* Begärd referens (GUID) existerar inte

Statuskod: 500 INTERNAL SERVER ERROR
* Internt oförutsätt fel



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.

Exempel filinnehåll
<?xml version='1.0' encoding='UTF-8'?>
<ns2:SearchPersonsForProfileResponse xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileResponder:3" 
xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3" 
xmlns:ns4="urn:riv:itintegration:registry:1">
	<ns2:personRecord>
		<ns3:personalIdentity>
			<ns3:root>1.2.752.129.2.1.3.1</ns3:root>
			<ns3:extension>198602212394</ns3:extension>
		</ns3:personalIdentity>
		<ns3:gender>1</ns3:gender>
		<ns3:protectedPersonIndicator>false</ns3:protectedPersonIndicator>
		<ns3:testIndicator>false</ns3:testIndicator>
		<ns3:primaryIdentity>true</ns3:primaryIdentity>
		<ns3:version>20190117180851</ns3:version>
		<ns3:name>
			<ns3:givenNameIndicator>10</ns3:givenNameIndicator>
			<ns3:givenName>
				<ns3:name>Moltas</ns3:name>
			</ns3:givenName>
			<ns3:surname>
				<ns3:name>Lundgren</ns3:name>
			</ns3:surname>
		</ns3:name>
		<ns3:birth>
			<ns3:dateOfBirth>
				<ns3:format>YYYY-MM-DD</ns3:format>
				<ns3:value>1986-02-21</ns3:value>
			</ns3:dateOfBirth>
			<ns3:birthAbroad>
				<ns3:placeOfBirthAbroad>
					<ns3:placeOfBirthAbroad>QUEBEC</ns3:placeOfBirthAbroad>
				</ns3:placeOfBirthAbroad>
				<ns3:countryOfBirth>KANADA</ns3:countryOfBirth>
			</ns3:birthAbroad>
		</ns3:birth>
		<ns3:populationRegistrationLocality>
			<ns3:populationRegistrationDate>
				<ns3:format>YYYY-MM-DD</ns3:format>
				<ns3:value>2007-08-10</ns3:value>
			</ns3:populationRegistrationDate>
			<ns3:countyCode>01</ns3:countyCode>
			<ns3:municipalityCode>80</ns3:municipalityCode>
			<ns3:propertyDesignation>BLÅKLINTEN 3</ns3:propertyDesignation>
			<ns3:fictitiousPropertyNumber>0</ns3:fictitiousPropertyNumber>
		</ns3:populationRegistrationLocality>
		<ns3:populationRegistrationRecord>
			<ns3:syncronizationTime>2019-01-17T18:08:51.000+01:00</ns3:syncronizationTime>
			<ns3:notificationCase>
				<ns3:modificationTime>2007-09-04T01:21:11.000+02:00</ns3:modificationTime>
			</ns3:notificationCase>
			<ns3:historicalRecords>
				<ns3:populationRegistrationLocality>
					<ns3:populationRegistrationDate>
						<ns3:format>YYYY-MM-DD</ns3:format>
						<ns3:value>2007-08-10</ns3:value>
					</ns3:populationRegistrationDate>
					<ns3:countyCode>01</ns3:countyCode>
					<ns3:municipalityCode>80</ns3:municipalityCode>
					<ns3:propertyDesignation>BLÅKLINTEN 3</ns3:propertyDesignation>
					<ns3:populationRegistrationType>FB</ns3:populationRegistrationType>
				</ns3:populationRegistrationLocality>
			</ns3:historicalRecords>
		</ns3:populationRegistrationRecord>
		<ns3:addressInformation>
			<ns3:residentialAddress>
				<ns3:postalAddress2>KAMMAKARGATAN 3</ns3:postalAddress2>
				<ns3:postalCode>11140</ns3:postalCode>
				<ns3:city>STOCKHOLM</ns3:city>
			</ns3:residentialAddress>
			<ns3:nationalKeys>
				<ns3:propertyId>100014022</ns3:propertyId>
				<ns3:addressPlaceId>491</ns3:addressPlaceId>
				<ns3:apartmentId>25605931</ns3:apartmentId>
			</ns3:nationalKeys>
		</ns3:addressInformation>
		<ns3:maritalStatus>
			<ns3:maritalStatusCode>OG</ns3:maritalStatusCode>
		</ns3:maritalStatus>
		<ns3:immigration>
			<ns3:immigrationDate>
				<ns3:format>YYYY-MM-DD</ns3:format>
				<ns3:value>2007-08-10</ns3:value>
			</ns3:immigrationDate>
		</ns3:immigration>
		<ns3:citizenship>
			<ns3:citizenshipCountryCode>
				<ns3:countryCode>SE</ns3:countryCode>
			</ns3:citizenshipCountryCode>
		</ns3:citizenship>
	</ns2:personRecord>
	<ns2:personRecord>
		<ns3:personalIdentity>
			<ns3:root>1.2.752.129.2.1.3.1</ns3:root>
			<ns3:extension>198602072392</ns3:extension>
		</ns3:personalIdentity>
		<ns3:gender>1</ns3:gender>
		<ns3:protectedPersonIndicator>false</ns3:protectedPersonIndicator>
		<ns3:testIndicator>false</ns3:testIndicator>
		<ns3:primaryIdentity>true</ns3:primaryIdentity>
		<ns3:version>20190108110923</ns3:version>
		<ns3:name>
			<ns3:givenNameIndicator>10</ns3:givenNameIndicator>
			<ns3:givenName>
				<ns3:name>Jens</ns3:name>
			</ns3:givenName>
			<ns3:surname>
				<ns3:name>Lööf</ns3:name>
			</ns3:surname>
		</ns3:name>
		<ns3:birth>
			<ns3:dateOfBirth>
				<ns3:format>YYYY-MM-DD</ns3:format>
				<ns3:value>1986-02-07</ns3:value>
			</ns3:dateOfBirth>
			<ns3:birthAbroad>
				<ns3:placeOfBirthAbroad>
					<ns3:placeOfBirthAbroad>GDANSK</ns3:placeOfBirthAbroad>
				</ns3:placeOfBirthAbroad>
				<ns3:countryOfBirth>POLEN</ns3:countryOfBirth>
			</ns3:birthAbroad>
		</ns3:birth>
		<ns3:populationRegistrationLocality>
			<ns3:populationRegistrationDate>
				<ns3:format>YYYY-MM-DD</ns3:format>
				<ns3:value>2007-08-22</ns3:value>
			</ns3:populationRegistrationDate>
			<ns3:countyCode>01</ns3:countyCode>
			<ns3:municipalityCode>82</ns3:municipalityCode>
			<ns3:propertyDesignation>SLUT 1:10</ns3:propertyDesignation>
			<ns3:fictitiousPropertyNumber>0</ns3:fictitiousPropertyNumber>
		</ns3:populationRegistrationLocality>
		<ns3:populationRegistrationRecord>
			<ns3:syncronizationTime>2019-01-08T11:09:23.000+01:00</ns3:syncronizationTime>
			<ns3:notificationCase>
				<ns3:modificationTime>2007-09-11T10:53:18.000+02:00</ns3:modificationTime>
			</ns3:notificationCase>
			<ns3:historicalRecords>
				<ns3:populationRegistrationLocality>
					<ns3:populationRegistrationDate>
						<ns3:format>YYYY-MM-DD</ns3:format>
						<ns3:value>2007-08-22</ns3:value>
					</ns3:populationRegistrationDate>
					<ns3:countyCode>01</ns3:countyCode>
					<ns3:municipalityCode>82</ns3:municipalityCode>
					<ns3:propertyDesignation>SLUT 1:10</ns3:propertyDesignation>
					<ns3:populationRegistrationType>FB</ns3:populationRegistrationType>
				</ns3:populationRegistrationLocality>
			</ns3:historicalRecords>
		</ns3:populationRegistrationRecord>
		<ns3:addressInformation>
			<ns3:residentialAddress>
				<ns3:postalAddress2>FINNBODAVÄGEN 2</ns3:postalAddress2>
				<ns3:postalCode>13131</ns3:postalCode>
				<ns3:city>NACKA</ns3:city>
			</ns3:residentialAddress>
			<ns3:nationalKeys>
				<ns3:propertyId>100294037</ns3:propertyId>
				<ns3:addressPlaceId>1259</ns3:addressPlaceId>
				<ns3:apartmentId>25717466</ns3:apartmentId>
			</ns3:nationalKeys>
			<ns3:district>
				<ns3:districtCode>101259</ns3:districtCode>
			</ns3:district>
		</ns3:addressInformation>
		<ns3:maritalStatus>
			<ns3:maritalStatusCode>OG</ns3:maritalStatusCode>
		</ns3:maritalStatus>
		<ns3:immigration>
			<ns3:immigrationDate>
				<ns3:format>YYYY-MM-DD</ns3:format>
				<ns3:value>2007-08-22</ns3:value>
			</ns3:immigrationDate>
		</ns3:immigration>
		<ns3:citizenship>
			<ns3:citizenshipCountryCode>
				<ns3:countryCode>SE</ns3:countryCode>
			</ns3:citizenshipCountryCode>
		</ns3:citizenship>
	</ns2:personRecord>
</ns2:SearchPersonsForProfileResponse>

2.2. 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 många 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, oavsett om de är identitetsskyddade eller inte.

Det här flödet ser ut på samma vis som det tidigare.
Det som skiljer är innehållet i den query vi skickar in, här anges regionen som aviseringen sker på med hjälp av läns och kommunkoder.

Exempel anrop
<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>

3. Aviseringar

3.1. Avisera på utomläningar, reservidentiteter och personer som flyttat

För att avisera på utomläningar och reservidentiter kan samma instruktion som för grundladdning utföras med ett undantag, den query som anges ska inkludera en tidsstämpel (ÅÅÅÅMMDDhhmmss) så att endast de personer som uppdaterats sen den senaste lyckade körningen (förslagsvis aviserar LPU varje dygn).

I detta anrop kan vi även söka efter flyttposter.
Då personerna kan ha flyttat ur de angivna länen/kommunerna så finns det risk att LPU inte längre är PuA/PuB för dessa personer längre.
I detta fall är det inte tillåtet att nyttja kontraktet med postfix Unrestricted, datan som returneras kan vara filtrerad p.g.a. identitetsskydd.
Dessa svar av personer som flyttat kommer endast returneras en gång, då det anges ett nytt datum vid nästa körning. En lokal PU kan därför vilja spara person id för de returnerade personerna som är aktiva patienter i ett register med utomläningar.
Denna fråga kommer även returnera personer som har flyttat inom samma län/kommun och det är en begränsning i frågespråket som inte stödjer "not equals".

Exempel anrop
<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") OR 
			(PopulationRegistrationRecord.HistoricalRecords.HistoricalRegistrations.CountyCode IN ("05","06","07") AND PopulationRegistrationRecord.HistoricalRecords.HistoricalRegistrations.LocalRegistrationTime >= "20190220095204") OR 
			(PopulationRegistrationRecord.HistoricalRecords.HistoricalRegistrations.CountyCode = "12" AND PopulationRegistrationRecord.HistoricalRecords.HistoricalRegistrations.MunicipalityCode = "87" AND 
			PopulationRegistrationRecord.HistoricalRecords.HistoricalRegistrations.LocalRegistrationTime >= "20190220095204"));</urn1:query>
		 <urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
         <urn1:profile>P5</urn1:profile>
      </urn1:SearchPersonsForProfileByOrder>
   </soapenv:Body>
</soapenv:Envelope>

3.2. Avisera på personer från ett geografiskt område

För att avisera på län kan samma instruktion som för grundladdning utföras, med ett undantag. Den query som anges ska inkludera en tidsstämpel så att endast de personer som uppdaterats sen den senaste lyckade körningen (förslagsvis aviserar LPU varje dygn).

Exempel anrop
<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>

4. 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 aviseringarna.
Ett exempel där det annars kan ge oönskade effekter är:

  1. 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.
  2. 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.



  • No labels