Sidjämförelse

...

SOAP-tjänst för att 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.

Info

Versionshantering av searchPersonsByFile i domänversion 3 och 4

Vid Release 4.8, som införde domänversion 4 av Personuppgiftstjänsten, gjordes en driftsförändring som gav REST-tjänsten för searchPersonsByFile två versioner; en för vardera domänversion.
Läs mer under 2.1.1.2 Version

...

REST-tjänsterna finns i olika version beroende på domänversion

Notera att det i vissa fall finns olika versioner av REST-tjänsterna, för att vara kompatibla med olika domänversioner av Personuppgiftstjänsten. Läs mer under denna sidas avsnitt Versioner samt sidan Livscykel för versioner.

Image Added
Figur: Anrop först till tjänst i NTjP med SOAP och sedan direkt till tjänsten med REST för att hämta resultatet från första anropet.

...

Användningsfall	Syfte	Ingående REST-tjänster
Söka personuppgifter via fil	Begär en sökning på en bifogad lista med identiteter	SearchPersonsByFile GetPersonsByFile Order/Get
Hämta resultatfil från kriteriesökning	Hämta resultat från en sökning kriteriesökning gjord via NTjP tjänstekontrakt som SearchPersonsForProfileByOrder eller SearchPersonsForProfileByOrderUnrestricted, vilket genererat en resultatfil.	Order/Get
Hantering av bilagor för reservidentiteter	Inkludera bilagd fil som styrker en reservidentitet	Attachment/Put Attachment/Get Attachment/Delete

...

Söka personuppgifter via fil: SearchPersonsByFile och GetPersonsByFile
Hämta resultat för asynkron personsökning: SearchPersonsForProfileByOrder, SearchPersonsByFile och SearchPersonsByFileGetPersonsByFile
Hantering av bilagor för reservidentiteter: Hämta, ladda upp samt ta bort

Användningsfall 2 och delvis 3 följer flödet som beskrivs i ARK_0038 Refererad bilaga, medans detta inte är applicerbart i användningsfallen 1 och delvis 3 vid uppladdning av bilagor. Flöden för samtliga användningsfall specificeras i följande avsnitt.

Söka personuppgifter via fil: SearchPersonsByFile och GetPersonsByFile

Funktionen Funktionerna finns endast som restricted-variant. Returnerar alltså inte adress m.m på sekretessmarkerade personposter.

Flödet startar med att att en lista med personidentiteter behöver uppdateras. Listan upprättas som en radbruten CSV-fil där identiteterna anges med personid och personid-typ (OID) separerade med semikolon. Ex: 191212121212;1.2.752.129.2.1.3.1

Filen laddas upp via någon av REST-metoden metoderna SearchPersonsByFile eller GetPersonsByFile som vid lyckad uppladdning returnerar ett Order-Id. Detta Order-Id används som inparameter till tjänsten 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.

OBS: Filer skapade via personsök är garanterat tillgängliga i ett dygn, därefter rensas dom automatiskt bort från Personuppgiftstjänsten. Filer som har hämtats kan rensas bort tidigare.

Den slutgiltiga filen som hämtas är en zippad fil innehållande en XML med det urval som efterfrågats, inbäddade i en GetPersonsForProfileResponse. Notera där följande:

SearchPersonsByFile och getPersonsByFile har ej stöd för sökning mot personposter med testIndicator=true, dvs personidentiteter som i testmiljö kallas testpersoner och i produktionsmiljö kallas valideringspersoner. En sökning mot sådan identitet kommer inte att returnera någon personRecord oavsett om personposten finns i databasen eller ej, dvs svaret ser alltid ut som att ingen träff fanns på denna identitet. För tester av någon av SearchPersonsByFile dessa funktioner behöver istället testpersoner med testIndicator=false användas.

...

Bild: Exempel på ett svar där träff ficks på ett personid.

...

Parametrar

Namn	Beskrivning
profile	Obligatorisk parameter för vilken profil som önskas i svaret. Se TKB för beskrivning av profilerna P1-P5. Observera att profilen skall anges med versalt P. Datatyp: String. Exempel: P1
fromDate	Valfri parameter för det datum man är intresserad av förändringar från och med baserat på fältet version i personposten. Datatyp: LocalDateTime. Exempel: 2021-10-12T00:00:00
maxResultsPerFile	Valfri parameter för max antal personposter per fil. Ej angivet så returneras alltid resultatet i endast en fil. Detta värde får ej vara lägre än 500. Datatyp: Integer. Exempel: 1000
primaryidentity	Valfri parameter som om satt till true gör att endast personposter som är markerad som huvudidentitet inkluderas i svaret. En efterfrågad personpost som inte är en huvudidentitet kommer då varken att generera en requestedPersonalIdentity eller en personRecord i svarsfilen. Om parametern inte sätts alls eller sätts till false så kommer alla identiteter att inkluderas i svaret oavsett om de är huvudidentitet eller ej. Datatyp: Boolean. Exempel: true

...

URL

REST-tjänsten SearchPersonsByFile searchPersonsByFile finns i två versioner och anropas via två , samt en tredje version som döpts om till getPersonsByFile. Dessa anropas via tre olika url:er. Det som skiljer versionerna åt är att de är kompatibla med olika versioner av domänen strategicresourcemanagement:persons:personskiljer versionerna åt är att de är kompatibla med olika versioner av domänen strategicresourcemanagement:persons:person.

URL för Testmiljö

https://api.pu.ineratest.org:443/purest/searchPersonsByFile - kompatibel med domänversion 3.
https://api.pu.ineratest.org:443/purest/v2/searchPersonsByFile - kompatibel med domänversion 4.
https://api.pu.ineratest.org:443/purest/getPersonsByFile - kompatibel med domänversion 5.

URL för Prod-miljö

https://api.pu.inera.se:443/purest/searchPersonsByFile - kompatibel med domänversion 3.
https://api.pu.inera.se:443/purest/v2/searchPersonsByFile - kompatibel med domänversion 4.
https://api.pu.ineratestinera.org:443/purest/searchPersonsByFile - kompatibel med domänversion 3.se:443/purest/getPersonsByFile - kompatibel med domänversion 5.

Exempel

Via cURL

Request

Response

searchPersonsByFile Version 1

curl -X POST \
https://api.pu.ineratest.org:443/purest/

...

Exempel

Via cURL

Request

Response

Version 1searchPersonsByFile \
-H 'content-type: multipart/form-data;' \
-F profile=P1 \
-F fromDate=2021-10-12T00:00:00 \
-F maxResultsPerFile=1000 \
-F primaryidentity=true \
-F file=@bilagan.csv

searchPersonsByFile Version 2

curl -X POST \
https://api.pu.ineratest.org:443/purest/v2/searchPersonsByFile searchPersonsByFile \
-H 'content-type: multipart/form-data;' \
-F profile=P1 \
-F fromDate=2021-10-12T00:00:00 \
-F maxResultsPerFile=1000 \
-F primaryidentity=true \
-F file=@bilagan.csv
Version 2
getPersonsByFile

curl -X POST \
https://api.pu.ineratest.org:443/purest/v2/searchPersonsByFile getPersonsByFile\
-H 'content-type: multipart/form-data;' \
-F profile=P1 \
-F fromDate=2021-10-12T00:00:00 \
-F maxResultsPerFile=1000 \
-F primaryidentity=true \
-F file=@bilagan.csv

Statuskod: 201 CREATED
Content-Type: application/json; charset=ISO-8859-1
Transfer-Encoding: chunked
Content:

{
"orderId": "1028-TO63-15133551"
}

Statuskod: 400 BAD_REQUEST
* Filen är inte av typ CSV
* Filen är tom
* De första raderna innehåller ogiltigt formaterad data
* Den angivna profilen är inte giltig
* Det angivna värdet för max antal personposter per fil är för lågt

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

Statuskod: 500 INTERNAL SERVER ERROR
* Internt oförutsett fel
* Filens storlek i MB överskrider tillåten gräns
* Felaktig datatyp angiven för parameter

...

storlek i MB överskrider tillåten gräns
* Felaktig datatyp angiven för parameter

För att hämta resultatet av sökningen, följ flödet i avsnittet “Hämta resultatet för asynkron personsökning” nedan.

Hämta resultatet för asynkron personsökning

Flödet startar med att ett urval för ett stort antal patienter personer behöver göras. Detta urval sker genom anrop till någon av de asynkron "*ByOrder-tjänsterna" eller SearchPersonsByFile tjänstekontrakten SearchPersonsForProfileByOrder(Unrestricted) (SOAP) eller någon av REST-tjänsterna searchPersonsByFile/getPersonsByFile som alla returnerar ett Order-Id.

...

Detta Order-Id används sedan som inparameter till tjänsten tjänstekontraktet GetFilesForOrderId (SOAP) som returnerar ett svar med en eller flera länkar till resultatfilerna.

Fråga	Svar

Då ordnarna de orders som inkommer via dessa asynkrona tjänster läggs på kö så är det inte säkert att resultatet är färdigt ifall man frågar direkt efter att ordern har lagts. Tiden för orderna att bli klar varierar beroende på last på systemet och storleken på resultatet. Ett frågande system bör dock kunna förvänta sig ett svar inom fyra timmar.

Under tiden ordern inte är klar returnerar GetFilesForOrderId ett svar utan länkar/<multimedia>-stycke.

OBS: Resultatfilerna är garanterat tillgängliga i ett dygn. Därefter rensas dom automatiskt bort. Filen kan bara hämtas en gång då de efter hämtning rensas bort.

Resultatfilerna är ZIP:ade och innehåller en XML-fil med det urval som efterfrågats. Formatet som specificeras i TKB och XSD för strategicresourcemanagement:persons:person.

...

Exempel

SearchPersonsForProfileByOrder

Request

Response

Kodblock

language	xml

<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>SE165565594230-1000</urn:LogicalAddress>
  </soapenv:Header>
  <soapenv:Body>
    <urn1:SearchPersonsForProfileByOrder>
      <urn1:query>FROM personrecord WHERE name.givenname LIKE 'Daniel%';</urn1:query>
      <urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
      <urn1:profile>P5</urn1:profile>
    </urn1:SearchPersonsForProfileByOrder>
  </soapenv:Body>
</soapenv:Envelope>

Kodblock

language	xml

<S:Envelope
 xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:SearchPersonsForProfileByOrderResponse
     xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderResponder:3"
     xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3"
     xmlns:ns4="urn:riv:itintegration:registry:1">
      <ns2:orderId>0622-TO17-09215997</ns2:orderId>
    </ns2:SearchPersonsForProfileByOrderResponse>
  </S:Body>
</S:Envelope>

GetFilesForOrderId

Request

Response

Kodblock

language	xml

<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>SE165565594230-1000</urn:LogicalAddress>
  </soapenv:Header>
  <soapenv:Body>
    <urn1:GetFilesForOrderId>
      <urn1:orderId>0622-TO17-09215997</urn1:orderId>
    </urn1:GetFilesForOrderId>
  </soapenv:Body>
</soapenv:Envelope>

Resultat ej klart:

Kodblock

language	xml

<S:Envelope
 xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:GetFilesForOrderIdResponse
     xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:GetFilesForOrderIdResponder:3"
     xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3"
     xmlns:ns4="urn:riv:itintegration:registry:1">
    </ns2:GetFilesForOrderIdResponse>
  </S:Body>
</S:Envelope>

Resultat klart:

Kodblock

language	xml

<S:Envelope
 xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:GetFilesForOrderIdResponse
     xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:GetFilesForOrderIdResponder:3"
     xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3"
     xmlns:ns4="urn:riv:itintegration:registry:1">
      <ns2:multimedia>
        <ns3:mediaType>application/zip</ns3:mediaType>
        <ns3:reference>https://api.pu.ineratest.org:443/purest/order/get/fd6a78ee-da71-4ec6-a099-cbccc21fe468</ns3:reference>
      </ns2:multimedia>
    </ns2:GetFilesForOrderIdResponse>
  </S:Body>
</S:Envelope>

Filnedladdning via order/get (REST)

Request

Response

https://api.pu.ineratest.org:443/purest/order/get/fd6a78ee-da71-4ec6-a099-cbccc21fe468

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

...

Uppladdning av bilaga sker genom PUT och föregås av en hämtning av personpost för aktuell reservidentitet. Detta för att säkerställa att identiteten finns.

...

URL

Beror på miljö, men exempelvis: https://api.pu.ineratest.org:443/purest/attachment/put

...

Bilagor erhålls som en referens-URL i svaret från PU-tjänstens. Dessa används sedan som GET anrop för att hämta filerna.

...

URL

Beror på miljö, men exempelvis: https://api.pu.ineratest.org:443/purest/attachment/get/e870cddb-5842-4c72-a804-7d39fa4c5478

...

Flödet förutsätter att bilagan inte har kvar några kopplingar inom reservidentiteten. Dvs flöde för "koppla ifrån bilaga" måste genomföras då det är applicerbart.

...

URL

Beror på miljö, men exempelvis: https://api.pu.ineratest.org:443/purest/attachment/delete

...

Jämförda versioner

Gammal version 46

Ny version 47

Nyckel

Versionshantering av searchPersonsByFile i domänversion 3 och 4

REST-tjänsterna finns i olika version beroende på domänversion

Söka personuppgifter via fil: SearchPersonsByFile och GetPersonsByFile

Parametrar

URL

Exempel

Exempel

Hämta resultatet för asynkron personsökning

Exempel

SearchPersonsForProfileByOrder

GetFilesForOrderId

Filnedladdning via order/get (REST)

URL

URL

URL