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

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:

Numbered Headings

Inledning

Om dokumentet

Denna beskrivning är ett tillägg av tjänstekontrakten i tjänstedomänen strategicresourcemanagement:persons:person. Dokumentet beskriver hur tjänstens funktionalitet för att hämta och ladda upp filer är uppbyggd. Funktionaliteten baseras på dokument ARK_0038 enligt RIV-TA standarden och där grundprincipen för att hämta filer bygger på en RIV-tjänst för att lista tillgängliga filer och en REST-tjänst för att hämta de filer som listas via RIV-tjänsten. 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.

Konnektivitet

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

title	Versionshantering av searchPersonsByFile i version 4.8

Vid Release 4.8 gjordes en driftsförändring som gav REST-tjänsten för searchPersonsByFile två versioner. Läs mer under 2.1.1.2 Version

Figur 1.2: 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.

Notering om HSA-id: Personuppgiftstjänstens REST-tjänster kontrollerar vid begäran om filnedladdning att det är systemet med samma HSA-id som beställt filen. Om anropande konsument använder ett mellanlager i anslutning till NTjP, såsom en lokal tjänsteplattform, är det då viktigt för konsumenten att korrekt populera headern x-rivta-originalserviceconsumer-hsaid. Denna header skall ange det ursrungliga konsumerande systemets HSA-id, i enlighet med regel "Bevara ursprunglig avsändares identitet i http header" samt RIVTA Regel 23.

Beställning av behörighet

Personuppgiftstjänstens filhanteringstjänster är REST-tjänster som inte ingår i Inera NTjP. Behörighet för att använda dessa följer därför ett separat beställningsförfarande.

Beställning av behörighet till REST-tjänster görs genom att fylla i följande beställningsformulär, vilket skickas till Ineras kundtjänst på kundservice@inera.se. Ange i mailtexten att det gäller "Beställning av REST-tjänst för Personuppgiftstjänsten – se bilaga."

View file

name	Beställning Inera PU REST-tjänst.docx
height	250

HSA-id: Till skillnad från NTjP-baserade tjänstekontrakt så kommer behörighet till REST-tjänsterna alltid att utgå ifrån HSA-id hos det konsumerande systemet, inte ifrån HSA-id hos eventuellt mellanlager. Ange därför i beställningen av REST-tjänst alltid det konsumerande systemets HSA-id.

Ärendenummer för NTjP tjänstekontrakt: Godkännande av beställning av behörighet för REST-tjänster kräver att beställaren redan har en godkänd beställning av NTjP tjänstekontrakt för Personuppgiftstjänsten. I beställning av REST-tjänst anges därför ärendenumret för denna tidigare "Beställning från beställningsstödet" avseende NTjP tjänstekontrakt.

Användningsfall: Beställning av behörighet för REST-tjänsterna görs utifrån användningsfall enligt tabell nedan. Varje beställt användningsfall ger behörighet till en eller flera ingående REST-tjänster.

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 Order/Get
Hämta resultatfil från kriteriesökning	Hämta resultat från en sökning gjord via NTjP tjänstekontrakt som genererat en resultatfil	Order/Get
Hantering av bilagor för reservidentiteter	Inkludera bilagd fil som styrker en reservidentitet	Attachment/Put Attachment/Get Attachment/Delete

Användningsfall

Filhantering förekommer i följande användningsfall inom Personuppgiftstjänsten:

Söka personuppgifter via fil: SearchPersonsByFile
Hämta resultat för asynkron personsökning: SearchPersonsForProfileByOrder och SearchPersonsByFile
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

Funktionen 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 REST-metoden SearchPersonsByFile 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, GetPersonsForProfileResponse. Notera där följande:

Innehållet kommer att skilja sig från hur svaret ser ut i en GetPersonsForProfileResponse som uppkommit efter fråga mot tjänstekontraktet GetPersonsForProfile, enligt följande: I svaret som genererats via SearchPersonsByFile kommer endast en RequestedPersonRecord att levereras för de personposter som hittades i databasen. Detta i kontrast mot svaren från GetPersonsForProfile, där varje efterfrågad personpost kommer att få en RequestedPersonRecord oavsett om personposten hittades eller ej.
SearchPersonsByFile 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 RequestedPersonRecord oavsett om personposten finns i databasen eller ej. För tester av SearchPersonsByFile behöver istället testpersoner med testIndicator=false användas.

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

PlantUML Macro

@startuml

'skinparam handwritten true

skinparam sequence {
	ArrowColor #9C9C9C
	ActorBorderColor #9C9C9C
	LifeLineBorderColor #9C9C9C
	LifeLineBackgroundColor #F5F5F5
	
	ParticipantBorderColor<<Consumer>> #E3B549
	ParticipantBackgroundColor<<Consumer>> #FFE6CC
	ParticipantBorderColor<<Ntjp>> #6C8EBF
	ParticipantBackgroundColor<<Ntjp>> #DAE8FC
	ParticipantBorderColor<<Producer>> #82B366
	ParticipantBackgroundColor<<Producer>> #D5E8D4
	
	StereotypeFontColor white
	StereotypeFontSize 0
	
}

participant "Tjänstekonsument" as A<<Consumer>>
participant "Virtuell tjänst (NTjP)" as tp<<Ntjp>>
participant "Tjänsteproducent - PU" as pu<<Producer>>

activate A
A -> pu : Ladda upp fil\n//SearchPersonsByFile (REST)//
activate pu
pu -> pu : (Interna operationer)
pu -> A : Resultat\n//OrderId//
deactivate pu

A -> tp : Lista tillgängliga filer\n//GetFilesForOrderId (SOAP)//
activate tp
tp -> pu: //GetFilesForOrderId (SOAP)//
activate pu
pu -> pu : (Interna operationer)
pu -> tp : Resultat\n//0..* Filreferens (URL)//
deactivate pu
tp -> A : Resultat\n//0..* Filreferens (URL)//
deactivate tp

A -> pu : Hämta fil\n//URL (REST)//
activate pu
pu -> pu : (Interna operationer)
pu -> A : Resultat\nZIP-fil
deactivate pu

deactivate A

@enduml

Parametrar

Image Added

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
primaryidentities	Valfri parameter som om satt 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. Datatyp: Boolean. Exempel: true

Version

REST-tjänsten SearchPersonsByFile finns i två versioner och anropas via två olika url:er. Det som skiljer versionerna åt är att de är kompatibla med olika versioner av domänen strategicresourcemanagement:persons:person.

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.

Exempel

Via cURL

Namn

Beskrivning

profile

fromDate

Request

Response

Version 1

curl -X POST \
https://api.pu.ineratest.org:443/purest/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

curl -X POST \
https://api.pu.ineratest.org:443/purest/v2/searchPersonsByFile \
-H 'content-type: multipart/form-data;' \
-F profile=P1 \
-F fromDate=

2021-10-12T00:00:00 \
-F 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

primaryidentities Valfri parameter som om satt 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.
Datatyp: Boolean.

Exempel: true

Namn	Beskrivning
actorRoot	root (OID) för aktör
actorExtension	värde för aktör
actorProfessionalRoot	root (OID) för aktörens organisation/vårdgivare
actorProfessionalExtension	värde för aktörens organisation/vårdgivare
patientRoot	root (OID) för patientidentitet
patientExtension	värde patientidentitet
file	bilagan

Namn	Beskrivning
actorRoot	root (OID) för aktör
actorExtension	värde för aktör
actorProfessionalRoot	root (OID) för aktörens organisation/vårsgivare
actorProfessionalExtension	värde för aktörens organisation/vårsgivare
patientRoot	root (OID) för patientidentitet
patientExtension	värde patientidentitet
referenceId	bilagans id

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 33

New Version Current

Key

Inledning

Om dokumentet

Konnektivitet

Beställning av behörighet

Användningsfall

Söka personuppgifter via fil: SearchPersonsByFile

Parametrar

Parametrar

Version

Exempel

Version

Exempel

Hämta resultat för personsök

Hämta resultat för personsök

Exempel

SearchPersonsForProfileByOrder

GetFilesForOrderId

Exempel

SearchPersonsForProfileByOrder

REST

GetFilesForOrderId

REST

Bilagor för reservidentitet

Ladda upp bilaga

URL

Parametrar

Exempel

Koppla / Koppla ifrån bilaga

Hämta bilaga

URL

Parametrar

Exempel

Ta bort bilaga

Bilagor för reservidentitet

Ladda upp bilaga

URL

Parametrar

Exempel

Koppla / Koppla ifrån bilaga

Hämta bilaga

URL

Parametrar

Exempel

Ta bort bilaga

URL

Parametrar

Exempel