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) är enbart tillgänglig genom direktaccess mot tjänsteproducent.

Användningsfall

Filhantering förekommer för tre olika användningsfall inom PU-tjänsten.

Hämta aviseringsfiler
Hämta resultat för personsök (asynkron sökning, SearchPersonsForProfileByOrder)
Hämta, ladda upp samt ta bort bilagor för reservidentitet

Användningsfall 1 & 2 följer flödet enligt ARK_0038 (både SOAP och REST), medans användningsfall(en) för bilagor ej har behov av den listande SOAP-tjänsten. Flöden för samtliga användningsfall specificeras i följande kapitel.

Hämta aviseringsfiler

För att användningsfallet skall applicera så gäller att man först är upplagd i PU-tjänsten som en aviseringskund. Detta sker genom beställning hos Inera Kundservice. När man är upplagd som aviseringskund i PU-tjänsten har man erhållit ett Order-id, vilket är det som används i kommande flödesbeskrivning.

Aviseringsfiler skapas dagligen av PU-tjänsten, efter det datum som en aviseringskund angett som startdatum. Aviseringsdata fås enligt Skatteverkets XML-format definierat i Navetavisering V1. Alla poster i en aviseringsfil är av typen "totalpost".

Flödet för att hämta filer börjar med anrop till SOAP-tjänsten GetFilesForOrderId (via NTjP). Specifikation finns i TKB för strategicresourcemanagement:persons:person (www.rivta.se). En konsument anropar tjänsten med ett OrderId. PU-tjänsten returnerar ett svar innehållande 0..n referenser (unik URL för varje hämtbar fil) som konsumenten kan gå igenom för att hämta varje enskild fil via REST-tjänsten. Referensen som returneras användas i sin helhet för att hämta en fil.

Exempel

GetFilesForOrderId

Request

Response

<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>A123-B123-C123-D12</urn1:orderId>
    </urn1:GetFilesForOrderId>
  </soapenv:Body>
</soapenv:Envelope>

<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://ws.acctest.sakerhetstjanst.inera.se:443/purest/order/get/ed21a53e-09a9-4404-9b80-f2563eb8ebb0</ns3:reference>
      </ns2:multimedia>
    </ns2:GetFilesForOrderIdResponse>
  </S:Body>
</S:Envelope>

REST

Request

Response

https://ws.acctest.sakerhetstjanst.inera.se:443/purest/order/get/ed21a53e-09a9-4404-9b80-f2563eb8ebb0

Statuskod: 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="<filnamn>"
Transfer-Encoding: chunked
Content: fil (zippat xmldata enligt SKV's navetavisering-schema)

Schema för innehåll i zippad XML-fil följer Skatteverkets XSD Navetavisering V1
Struktur för filnamn (både ZIP och XML): <orderId>_<datum>_<löpnummer>.zip (samt .xml)
Exempel: A123-B123-C123-D12_20170622_1.zip

Statuskod: 204 NO CONTENT
* Efterfrågad fil är inte färdig för nerladdning än

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

Hämta resultat för personsök

Flödet startar med att ett urval för ett stort antal patienter behöver göras (exempelvis alla 40-åriga män inom länet). Detta urval sker genom anrop till tjänsten SearchPersonsForProfileByOrder som i sin tur returnerar ett Order-Id.

Detta Order-Id används som inparameter till tjänster GetFilesForOrderId som returnerar ett svar om var den resulterande filen kan hämtas.

Den slutgiltiga filen som hämtas är en zippad fil innehållande en XML med det urval som efterfrågats. Innehållet i XML-filen följer det format som specificeras i TKB för strategicresourcemanagement:persons:person.

Exempel

SearchPersonsForProfileByOrder

Request

Response

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

<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

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

<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://ws.acctest.sakerhetstjanst.inera.se:443/purest/order/get/fd6a78ee-da71-4ec6-a099-cbccc21fe468</ns3:reference>
      </ns2:multimedia>
    </ns2:GetFilesForOrderIdResponse>
  </S:Body>
</S:Envelope>

REST

Request

Response

https://ws.acctest.sakerhetstjanst.inera.se: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: 204 NO CONTENT
* Efterfrågad fil är inte färdig för nerladdning än

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

Bilagor för reservidentitet

En reservidentitet kan i PU-tjänsten ha 0..n bilagor. Dessa används för att styrka identiteten och kan vara exempelvis en kopia på ett pass. Bilagan kan laddas upp till reservidentiteten och senare kopplas till en specifik uppgift om styrkning av identitet. All operationer gällande bilagor görs med fördel i det av PU-tjänsten tillhandahålla GUI't, men kan vid behov hanteras av integrerande tjänster. För hantering av bilagor via GUI hänvisas till Användarhanboken för PU. Nedan beskrivs de flöden som appliceras vid integration av konsument.

Enbart exempel för REST-tjänster redovisas i följande kapitel. För information om användandet av RIV-tjänsterna hänvisas till TKB.

Ladda upp bilaga

Uppladdning av bilaga sker genom PUT eller POST 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://ws.acctest.sakerhetstjanst.inera.se:443/purest/attachment/put

Parametrar

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
file	bilagan

Exempel

Via cURL

Request

Response

curl -X PUT \
https://ws.acctest.sakerhetstjanst.inera.se:443/purest/attachment/put \
-H 'content-type: multipart/form-data; \
-F actorRoot=HSAID \
-F actorExtension=SE123456789 \
-F actorProfessionalRoot=HSAID \
-F actorProfessionalExtension=SE987654321 \
-F patientRoot=1.2.752.74.9.1 \
-F patientExtension=00002040AA11 \
-F file=@bilagan.jpg

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

{
"id": "36a7068d-172b-4fee-bed5-13ecbdfa7ff2",
"mediaType": "image/jpeg",
"value": null,
"reference": "https://ws.acctest.sakerhetstjanst.inera.se:443/purest/attachment/get/36a7068d-172b-4fee-bed5-13ecbdfa7ff2"
}

Statuskod: 400 BAD_REQUEST
* Ogiltig context path
* HSA-id för konsument saknas
* Ogiltig patientidentitet / parametrar

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

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

Koppla / Koppla ifrån bilaga

Dessa operationer är rena RIV-tjänster och beskrivs i TKB.

Hämta bilaga

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://ws.acctest.sakerhetstjanst.inera.se:443/purest/attachment/get/e870cddb-5842-4c72-a804-7d39fa4c5478

Parametrar

Bilagans referensID som en del av URL

Exempel

Via cURL

Request

Response

curl -X GET \
https://ws.acctest.sakerhetstjanst.inera.se:443/purest/attachment/get/e870cddb-5842-4c72-a804-7d39fa4c5478

Statuskod: 200 OK
Content-Type: <aktuell MIME-type>
Content-Disposition: attachment; filename="<filnamn>"
Transfer-Encoding: chunked
Content: filen

Statuskod: 400 BAD_REQUEST
* Ogiltig context path
* HSA-id för konsument saknas

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

Ta bort bilaga

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://ws.acctest.sakerhetstjanst.inera.se:443/purest/attachment/delete

Parametrar

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

Exempel

Via cURL.

Request

Response

curl -X DELETE \
https://ws.acctest.sakerhetstjanst.inera.se:443/purest/attachment/delete \
-H 'content-type: multipart/form-data; \
-F actorRoot=HSAID \
-F actorExtension=SE123456789 \
-F actorProfessionalRoot=HSAID \
-F actorProfessionalExtension=SE987654321 \
-F patientRoot=1.2.752.74.9.1 \
-F patientExtension=00002040AA11 \
-F referenceId=e870cddb-5842-4c72-a804-7d39fa4c5478

Statuskod: 200 OK
Content-Type: text/plain; charset=iso-8859-1
Transfer-Encoding: chunked
Content:

File with id: e870cddb-5842-4c72-a804-7d39fa4c5478 was successfully deleted.

Statuskod: 400 BAD_REQUEST
* Ogiltig context path
* HSA-id för konsument saknas
* Ogiltig patientidentitet / parametrar

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

TKB strategicresourcemanagement:persons:person

Se: https://bitbucket.org/rivta-domains/riv.strategicresourcemanagement.persons.person

Öppen info: Personuppgiftstjänsten

3.0 Filhantering

Inledning

Om dokumentet

Konnektivitet

Användningsfall

Hämta aviseringsfiler

Exempel

GetFilesForOrderId

REST

Hämta resultat för personsök

Exempel

SearchPersonsForProfileByOrder

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

URL

Parametrar

Exempel

TKB strategicresourcemanagement:persons:person