Stöd för utvecklare

Denna sida innehåller information som kan vara av särskilt intresse för tekniker och utvecklare som ska bygga en integration mot Inera Personuppgiftstjänst (PU-tjänsten).

Integration mot Personuppgiftstjänsten

Figuren nedan visar grafiskt hur anropsvägarna ser ut för PU-tjänsten för ett av de vanligaste fallen: en så kallad direktanslutande kund som har ett konsumerande system bakom en egen integrationsplattform. För fler varianter på anslutning, se Anslutningsprocess.

Open

Figur: Anropsvägar för Personuppgiftstjänstens tjänstekontrakt samt REST-tjänster

Under följande delavsnitt kommer de tekniska integrationsmöjligheter som finns mot PU-tjänsten att presenteras. Det handlar dels om så kallade Tjänstekontrakt, vilka är SOAP-tjänster, och dels om ett par REST-tjänster som används för överföring av filer.

Tjänstekontrakt

Åtkomst till Personuppgiftstjänsten ges via den Nationella Tjänsteplattformen (NTjP) som förvaltas av Inera. Genom denna plattform erbjuder Personuppgiftstjänsten ett flertal webbtjänster att anropa, vilka på Inera-språk kallas Tjänstekontrakt. Kommunikation med tjänstekontrakten görs via tekniken SOAP och anrop och svar följer standarden “Regler för Ineroperabilitet inom Vården” (RIV) som också förvaltas av Inera. RIV innehåller även regler och riktlinjer för dig som anslutande part behöver följa, utöver innehållet i anrop och svar.

Personuppgiftstjänsten använder sig av två av NTjP:s miljöer:

• NTjP QA - För testning, inklusive testning som anslutande kund gör inför produktionssättning.

• NTjP Prod - För system i produktion.

En komplett lista på Personuppgiftstjänstens Tjänstekontrakt som erbjuds via NTjP redovisas på hemsidan för RIV: rivta.se/tkview/#/domain/strategicresourcemanagement:persons:person

Notera där att det går att välja Domänversion högst upp på sidan. Detta eftersom det finns äldre versioner av Personuppgiftstjänstens tjänstekontrakt som lever parallellt med de senast tillgängliga versionerna. Se till att använda den version av Personuppgiftstjänsten som aktuell organisation i samråd med förvaltningen för PU-tjänsten har beslutat om.

• Tjänstekontrakten beskrivs i enlighet med standarden för RIV genom de komplementära dokumenten Informationsspecifikation (IS), vilken är verksamhetsnära, samt Tjänstekontraktbeskrivning (TKB) vilken är mer tekniknära. Dessa dokument finns att ladda ned längst ned på hemsidan för RIV enligt länk ovan.

• De mest tekniska filerna som beskriver tjänstekontrakten, schemafilerna, finns tillgängligga i respektive domänversions “Releasepaket” vilket är nedladdningsbart längst ned på hemsidan för RIV enligt länk ovan. På samma sida finns även en länk till “Källkod” vilket är online-repositoryt för Personuppgiftstjänstens releaser.

• I releasepaketet finns även en testsvit innehållandes testanvisningar och tillhörande mock-tjänst för vart och ett av tjänstekontrakten som finns i release-paketet. Mock-tjänsten kan användas för att helt lokalt testa att få till korrekta anrop och hantera svar från PU-tjänsten.
  Exempel-sökvägar för testsviten i release-paketet för tjänstekontraktet GetPersonsForProfile:

  • Testanvisningen ligger i release-paketets fil “\test-suite\GetPersonsForProfileMock\Testanvisning för tjänstekonsumenter av GetPersonsForProfile.html”

  • Installationsinstruktioner för Mock-tjänsten finns i release-paketets fil “\test-suite\GetPersonsForProfileMock\GetPersonsForProfileMock-doc.html”

  • SoapUI projektfil för testsvitens anrop finns i release-paketets fil “\test-suite\GetPersonsForProfile\GetPersonsForProfile-soapui-project.xml”

  • För övriga tjänstekontrakt, se deras respektive mappar enligt samma struktur.

REST-tjänster

Som ett komplement till tjänstekontrakten erbjuder Personuppgiftstjänsten även ett antal webbtjänster som ej formellt följer RIV och därför tillgängliggörs utanför NTjP, vilkas syften är att genom filhantering möjliggöra bulkslagningar av stora informationsmängder samt hantering av bilagor på ett sätt som RIV ej har stöd för. Anrop mot dessa tjänster görs alltså inte via NTjP, utan direkt mot PU-tjänsten, och det är inte alla kunder till PU-tjänsten som har behov av dessa. Kommunikation med dessa webbtjänster görs via tekniken REST.

Sökvägar och anropsbehörigheter

För att kunna anropa Personuppgiftstjänsten behöver den anropande parten vara vitlistad för detta hos Inera. Vitlistningen görs till de anropande systemens tilldelade funktionscertifikat via det unika HSA-id som är knutet till certifikatet. Ansökan om vitlistning görs som en administrativ del i anslutningsprocessen, och har två separata komponenter:

1. SOAP-tjänster: Anropsbehörighet för Tjänstekontrakt (SOAP), vilket ges via en administrativ process som hos Inera heter TAK-ning. Det är den anslutande kunden som ansöker om TAK-ning i systemet Beställningsstödet.

2. REST-tjänster: Anropsbehörighet för REST-tjänster, vilket ges via en administrativ process som också initeras av den anslutande kunden, men som på grund av att REST-tjänster inte formellt ingår i RIV/NTjP så används inte Beställningsstödet utan ett separat word-formulär som skickas in via en e-tjänst.

Olika certifikat, och därmed separat vitlistning, används för testmiljö respektive produktionsmiljö.

Sökvägar för anrop till SOAP-tjänster och REST-tjänster beror dels på miljö, dels vilken version av
Tjänstekontrakt eller REST-tjänst som ska anropas, och slutligen huruvida anropet ska ske över vanliga Internet eller hälso- och sjukvårdens särskilda Sjunet.

Anropsmönster

Beroende på behoven hos verksamheten som ansluter till Personuppgiftstjänsten kan olika typer av anrop göras, och för vissa användningsfall behöver flera av tjänsterna användas i en kedja. Nedan visas fyra sätt att hämta personposter, det vill säga information om personer som finns registrerade i personuppgiftstjänsten.

Open

Fall 1: Användaren känner till ett id-nummer (personnummer, samordningsnummer eller reservidentitet) och vill hämta uppgifter från Personuppgiftstjänsten om denna specifika person. Det aktuella tjänstekontraktet ger dock även möjliget att hämta uppgifter på upp till 500 id-nummer samtidigt.
För detta användningsfall krävs endast ett anrop mot tjänstekontraktet GetPersonsForProfile.

Fall 2: Användaren söker efter en eller maximalt 500 personer som uppfyller vissa kriterer. Kriterierna kan vara till exempel namn, bostadslän/kommun, födelsedatum eller del av id-nummer. För detta användningsfall krävs endast ett anrop mot tjänstekontraktet SearchPersonsForProfile, som använder sig av SQL-liknande frågor

Fall 3: Användaren vill göra en anpassad sökfråga som i föregående fall, men med möjliget att få stora mängder personposter i svaret. Denna möjlighet används ofta för att uppdatera lokala register genom att söka inom ett bostadslän/kommun samt att ändringar ska ha skett på personposten sedan en viss tidpunkt.

För detta användningsfall används en kedja av anrop.

Viktigt att tänka på här är att PU-tjänsten endast tillåter att filnedladdning av resultatfiler görs av det system (HSA-id) som genererade filen genom det ursprungliga anropet till SearchPersonsForProfileByOrder. Läs mer om detta i dokumentationen om REST-tjänster för filhangering.

Fall 4: Användaren vill söka på ett stort antal kända id-nummer. Denna möjlighet används ofta för att uppdatera lokala register genom att låta Personuppgiftstjänsten leta efter uppdateringar hos hela eller delar av det befintliga lokala registret.

För detta användningsfall används en kedja av anrop.

Viktigt att tänka på här är att PU-tjänsten endast tillåter att filnedladdning av resultatfiler görs av det system (HSA-id) som genererade filen genom det ursprungliga anropet till SearchPersonsForProfileByOrder. Läs mer om detta i dokumentationen om REST-tjänster för filhangering.

Kriteriesökningar med SimpleQL

Förutom tjänster som möjliggör sökningar på kända identitetsnummer erbjuder PU-tjänsten även flera möjligheter till kriteriesökningar där identitetsnumret inte behöver vara känt, utan där det går att väldigt fritt definiera vilka kriterier som ska vara uppfyllda. Till exempel att förnamnet ska börja på “A”, personen ska vara född 1950 och vara folkbokförd i ett visst län. Dessa tjänster för kriteriesökning benämns generellt genom att de heter “Search…” snarare än “Get…”. Sökkriterierna anges genom det SQL-lika men PU-tjänstespecifika språket SimpleQL.

Verksamhetsramverk

Förutom de regler som finns för respektive tjänstekontrakt eller REST-tjänst, skall användande av Personuppgiftstjänsten även följa de verksamhetsramverk som tagits fram för specifika användningsområden. Observera att i dessa verksamhetsramverk kan begränsningar anges för hur vissa attribut ska användas, och dessa begränsningar kan vara hårdare än vad det underliggande tjänstekontraktet eller REST-tjänsten tillåter rent tekniskt.

Testdata

Detta avsnitt beskriver vilken testdata som finns tillgänglig i PU-tjänsten; både gällande testpersoner i testmiljön (åtkomst via NTjP QA) samt så kallade valideringspersoner i produktionsmiljön (åtkomst via NTjP Prod).

Testmiljöns testpersoner

Beroende på om behoven är mycket enkla eller mer komplexa finns olika alternativ när det gäller vilka testpersoner som kan användas i PU-tjänstens testmiljö.

För enkla, generiska behov av läsning:

Det finns en uppsättning så kallade nationella testpersoner, vilka är personposter som inte kan bokas av någon och inte heller får ändras av någon. Dessa personposter är därmed tillgängliga att göra läsande operationer mot utan att ha gjort någon bokning, och de ska returnera den information som redovisas i dokumentationen av dem.

För läsande operationer är det tillåtet att göra läsning mot vilka personposter som helst i testmiljön, även de som inte bokats av er. Ni behöver dock vara medvetna om att den organisation som har bokat en testperson har rätt att göra ändringar i den personposten när som helst, vilket då kan ge påverkan på era tester mot dessa.

För specifika behov av läsning, eller behov av skrivning:

Om det finns behov av att göra läsningar mot testpersoner som måste ha specifik data på sina personposter för att uppfylla vissa testscenarier så går det att reservera (boka) testpersoner. Ineras testspecialister hjälper sedan till att förse dessa personposter med den data ni behöver.

Om skrivande operationer ska testas måste ni alltid först boka de testpersoner ni ska använda, så att ni inte förstör någon annan organisations tester.

Det är viktigt att förstå att ingen teknisk begränsning finns som förhindrar att någon gör en skrivning mot en testperson som de inte har bokat. Det är därmed ert ansvar som anslutande part att endast göra skrivningar mot de testpersoner ni verifierat är bokade för er.

Produktionsmiljöns valideringspersoner

I produktonsmiljön har ett antal så kallade valideringspersoner gjorts tillgängliga. Dessa är till för att validera att system som gått i produktion har korrekt uppsatta integrationer. Valideringspersonerna får endast användas för läsande operationer, aldrig skrivande operationer.

Valideringspersoner känns igen på att attributet testIndicator har värdet true på personposten.

Frågor under utveckling eller integration

Om du har frågor som bör besvaras av Ineras förvaltning av Personuppgiftstjänsten, kontakta oss genom någon av följande kontaktvägar:

1. Via inloggning i Inera Kundportal. Fördelen är då att dina kontaktuppgifter följer med när du ställer frågor: https://www.inera.se/kontakta-oss/ineras-kundportal/

2. Genom telefon till Kundtjänst eller via e-tjänsteformulär: https://www.inera.se/kontakta-oss/avtal-bestallning-anslutning/fragor-under-teknisk-anslutning/

Det är bättre att fråga en gång för mycket, än en gång för lite.