Webservice tjänsten GetPerson Slagning mot befolkningsregister

Transkript

1 B Lundmark 1 (14) TietoEnator HealthCare Sweden AB Carlsgatan 6, Box MALMÖ Telefon Fax E-post bengt.lundmark@tietoenator.com Styrelsens säte Stockholm Org. nr Webservice tjänsten GetPerson Slagning mot befolkningsregister Detta dokument beskriver anrop och hantering av returvärden från webservice tjänsten GetPerson. Detta inkluderar också eventuella felmeddelanden. Programmeringsexempel i C# mot webservicetjänsterna beskrivs i dokumentet PopManWS description and example in C#.pdf. Dessutom finns en fristående wsdl fil som kan användas för att sätta upp tjänsterna. Denna fil erhålls efter begäran från TietoEnator. Tjänsten GetPerson anropar landstingets befolkningsregister och returnerar en XML sträng med anropad persons mantalsskrivningsuppgifter. Om sökt person inte återfinns i registret över aktuell mantalsskrivna personer i upptagningsområdet och om sökt person ej är avliden, så kan tjänsten göra en automatisk sökning mot Skatteverkets befolkningsregister. Detta kräver en utökad behörighet för anropande system. Om anropande system har erforderlig behörighet, så returneras även sökt persons relationer, dvs uppgift om fader, moder, barn samt uppgifter om vårdnadshavare. Det är aktuellt landstings förvaltningsansvarige som tilldelar behörigheter.

2 2 (14) Anrop Anrop mot tjänsten görs via webservice teknik över http. Tjänsten är endast åtkomlig från resp landstings intranät. Det finns ingen åtkomst från Internet. Aktuell http adress, URL, erhålls av förvaltningsansvarig hos rep landsting. Anropet innehåller - en Login klass bestående av Systemid (Username) och ett password, - aktuell persons fullständiga personnummer (ÅÅÅMMDDNNNN) samt - en boolesk variabel (FlagOtherArchive) som anger huruvida anropet skall ha möjlighet att gå vidare mot Skatteverket om sökt person ej återfinns i aktuellt regionalt befolkningsregister. Så här ser ett fullständigt anrop ut: GetPerson(Login, Personnummer, FlagOtherArchive) Tjänsten ovan returnerar adresser enbart i versaler. Om anropande system önskar få namn- och adressuppgifter konverterade till både versaler och gemena så används följande alternativa tjänsteanrop: GetPerson_Konvert(Login, Personnummer, FlagOtherArchive) Login klassen, som skall skickas med i varje anrop består av Username och Password enligt följande: <login> <UserName>string</UserName> <Password>string</Password> </login> Username och Password erhålls av ansvarig på resp landstings IT enhet eller, om landstinget delegerat denna uppgift, av TietoEnator. Personnummer är ett svenskt personnummer enligt format ÅÅÅÅMMDDNNNN. Även s.k. samordningsnummer kan användas för sökning. FlagOtherArchive är en boolesk variabel som anger huruvida anropet skall gå vidare mot Skatteverket för personer som ej återfinns i det regionala befolkningsregistret. True (1) = vill gå vidare ; False (0) = vill ej gå vidare. OBS Även om systemet vill gå vidare mot Skatteverket så krävs att systemet får gå vidare. Behörighet till detta lämnas av förvaltningsansvarig i resp landsting.

3 3 (14) Returvärden Tjänsten returnerar värden som en XML sträng. Se bilaga 1 för information om vilken information som returneras och hur det formateras i XML. Svaret kan komma från Registret för Aktuell Befolkning (personen är mantalsskriven i regionen/landstinget) eller från Registret för Avregistrerade (personen har varit mantalsskriven i regionen/landstinget men är nu antingen utflyttad eller avliden) Avregistreringsorsaken finns kodad i taggen <CN_SU_CODE> och datum för avregistreringen finns i taggen <CN_CDATE> Möjliga koder för <CN_SU_CODE>: AN = Annan anledning AS = Tekniskt avregistrerad AV = Avliden GN = Gammalt personnummer OB = Obefintlig TA = Tekniskt avregistrerad UF = Utflyttad, markerar att personen flyttat ut ur kundens upptagningsområde. UV = Utvandrad (till annat land) Det är framför allt AV UF o UV som används. Om landstinget har avtal med Skatteverket (SV) kan svaret dessutom komma från deras persondatabas. o Förutsättning för ett svar från Skatteverket är att personen inte återfinns i Aktuell befolkning och ej är avliden, dvs återfinns i Avregistrerade med avliden som avregistreringsorsak. systemet som anropa anger i tjänsteanropet att anropet vill gå vidare mot SV (FlagOtherArchive=true) om personen inte återfinns. systemet som anropar har landstingets tillstånd att slå mot SV Anropande system får information om dessa svarsställen i SOAP-headerns <HeaderInfoValue.SourceName>

4 4 (14) Möjliga värden i <HeaderInfoValue.Source>: Befolkning Avregistrerade Skatteverket Taggen <HeaderInfovalue.RowsCount> innehåller information om antal träffar en sökning resulterade i. För tjänsten GetPerson är värdet alltså antingen 0 eller 1 eftersom svaret endast är för en enda person. Felhantering Samtliga eventuella fel som tjänsterna returnerar finns att avläsa i SOAP-headerns infotag: HeaderErrorInfoValue.Code och HeaderErrorInfoValue.Description OBS! Om felet inte kommer från tjänsten, utan är ett SOAP fel (dvs ett fel som uppstår innan anropet når vår webservertjänst) kommer felmeddelandet att finnas i SOAP envelopets <Fault> tag, där värdena i <faultcode> och <faultstring> kan kontrolleras. Felen från våra tjänster i HeaderErrorInfo.Description lämnas i klartext och kan därför visas för användaren i någon form av Messagebox eller dylikt. Tjänsten lämnar följande typer av fel: Felaktiga eller felaktigt antal argument lämnade till tjänsten Felaktig inloggning (systeminloggning) till tjänsten. Eventuella serverfel

5 5 (14) Checklista av för programmerare för avkodning av svar Följande checklista, dvs arbetsgång, bör följas vid tolkning av svar från tjänsterna: Anropa tjänsten med erforderliga argument och parsa upp svaret Kontrollera om SOAP Headern innehåller en Fault tag. I så fall har svaret inte kommit fram till tjänsten utan ett SOAP fel har uppstått. Kontrollera SOAP Header: Om värdet i <HeaderErrorInfo.Code> = 1 så har ett fel uppstått. Kontrollera då felet i <HeaderErrorInfo.Description>och meddela användaren felet och avbryt avkodning. Kontrollera SOAP Header: Om värdet i <HeaderInfo.RowsCount > är lika med 0 så har inga poster erhållits med angivna sök parametrar Kontrollera SOAP Header: Värdet i <HeaderInfo.SourceName> beskriver varifrån svaret erhålls: - Befolkning = aktuell befolkning i upptagningsområdet (taggarna har då prefix PO_) - Avregistrerade = person som avregistrerats från upptagningsområdet. (taggarna har då prefix CN_) - Skatteverket = svar från Skatteverkets webservice tjänst (taggarna har då prefix PO_) Parsa upp svaret (OBS att svaren från Skatteverket kan utesluta tecken för radbrytning mellan taggarna). OBS att taggarna har olika prefixer och antal beroende på om svaret kommer från Befolkning resp Skatteverket eller Avregistrerade Om svaret kommer från Avregistrerade eller Skatteverket, så kontrollera först taggarna <CN_SU_CODE> om denna tagg innehåller värde så är personen antingen avliden (AV) eller utflyttad det datum som beskriv i <CN_CDATE>

6 6 (14) Bilaga 1 Beskrivning av tjänstens XML svar Svaret från GetPerson erhålls som en XML sträng. Denna XML sträng har olika utseende och omfattning beroende på varifrån svaret erhålls. Format för alla datumfält = åååå/mm/dd Befolkning och Skatteverket Om svaret kommer från Befolkning eller Skatteverket erhålls följande taggar med prefix PO_ (för beskrivning av taggarnas betydelse, se bilaga 3) OBS om svaret kommer från Skatteverket erhålls dessutom taggarna <CN_SU_CODE> och <CN_CDATE> så att systemet kan kontrollera om aktuell person är avliden eller utvandrad. Följande exempel är där svar erhålls från Befolkning. <PMDataSet> <PersonInfo> <PO_PNR> </PO_PNR> <PO_TPNR /> <PO_SECRET /> <PO_PPNR /> <PO_TREC/> <PO_DNAME>10</PO_DNAME> <PO_NAME>ELINOR</PO_NAME> <PO_FNAME>ELINOR MARIE</PO_FNAME> <PO_MNAME>BESKERSSON</PO_MNAME> <PO_LNAME>ARMSTÖD</PO_LNAME> <PO_ANAME /> <PO_RDATE>1958/01/01</PO_RDATE> <PO_CNTY>12</PO_CNTY> <PO_MUNI>61</PO_MUNI> <PO_CONGR>01</PO_CONGR> <PO_FK>0</PO_FK> <PO_FO_CO /> <PO_FO_ADDR1 /> <PO_FO_ADDR2>PRÄSTGÅRDSVÄGEN 13 A</PO_FO_ADDR2> <PO_FO_ZCODE>66332</PO_FO_ZCODE> <PO_FO_CITY>KÄVLINGE</PO_FO_CITY> <PO_AFO_ADDR /> <PO_AFO_ZCODE /> <PO_AFO_CITY /> <PO_SP_CO /> <PO_SP_ADDR1 /> <PO_SP_ADDR2 /> <PO_SP_ZCODE /> <PO_SP_CITY /> <PO_ASP_ADDR /> <PO_ASP_ZCODE /> <PO_ASP_CITY /> <PO_UT_ADDR1 /> <PO_UT_ADDR2 /> <PO_UT_ADDR3 /> <PO_UT_CCODE /> <PO_UT_ZCODE />

7 <PO_UT_CTRY /> <PO_UT_CITY /> <PO_MA_DATE>1976/08/18</PO_MA_DATE> <PO_BI_CNTY>12</PO_BI_CNTY> <PO_BI_CONGR>HAMMARÖ</PO_BI_CONGR> <PO_BI_CITY /> <PO_BI_CTRY /> <PO_IM_DATE /> <PO_LOC_TAX /> <PO_P_RDATE /> <PO_P_CNTY /> <PO_P_MUNI /> <PO_P_CONGR /> <PO_SEX>K</PO_SEX> <PO_NT_CODE /> <PO_MS_CODE>G</PO_MS_CODE> <PO_RB_CODE>ZF030I385370</PO_RB_CODE> <PO_P_RB_CODE /> <PO_BDATE>1959/06/20</PO_BDATE> <PO_P_CO /> <PO_P_ADDR1 /> <PO_P_ADDR2 /> <PO_P_ZCODE /> <PO_P_CITY /> <CZ_CTRY>SE</CZ_CTRY> <CZ_CDATE /> <SO_TYPE /> <SO_CODE /> <RB_ECODE>MÖRMON 51:1</RB_ECODE> <PO DELETED>N</PO DELETED> </PersonInfo> </PMDataSet> 7 (14)

8 8 (14) Avregistrerade För personer som antingen är avlidna eller utflyttade (gäller där anrop mot Skatteverket ej görs) erhålls följande taggar (inkl exempel) med prefix CN_: <PMDataSet> <PersonInfo> <CN_PNR> </CN_PNR> <CN_FNAME>LISALOTTA</CN_FNAME> <CN_LNAME>KVARN</CN_LNAME> <CN_SECRET /> <CN_SU_CODE>AV</CN_SU_CODE> <CN_CDATE>2005/01/16</CN_CDATE> <CN_FO_ADDR1 /> <CN_FO_ADDR2>TVÄRGATAN 1 B</CN_FO_ADDR2> <CN_FO_ZCODE>69331</CN_FO_ZCODE> <CN_FO_CITY>STAFFANSTORP</CN_FO_CITY> <CN_UT_ADDR1 /> <CN_UT_ADDR2 /> <CN_UT_ADDR3 /> <CN_UT_CTRY /> <CN_UT_ZCODE /> <CN_UT_CTRY1 /> <CN_UT_CITY /> <CN_P_CO /> <CN_P_ADDR1 /> <CN_P_ADDR2 /> <CN_P_ZCODE /> <CN_P_CITY /> </PersonInfo> </PMDataSet> Ovanstående person är avliden

9 9 (14) Relationer Om anropande system har utökad behörighet för relationer så erhålls även anropad persons relationer inom taggen <PMDataSet>. OBS att detta gäller enbart om svaret kommer från Befolkning. Taggen <Relation> itereras aktuellt antal gånger. Exempel: </PMDataSet> <PersonInfo> Här kommer personens egen information enligt ovan exempel </PersonInfo> <Relation> <TN_CODE>B</TN_CODE> <PO_PNR> </PO_PNR> <BI_TIME /> <PO_NAME>MONA-LISA</PO_NAME> <PO_FNAME>EVA MONA-LISA</PO_FNAME> <PO_MNAME /> <PO_LNAME>BENGTSSON</PO_LNAME> </Relation> <Relation> <TN_CODE>B</TN_CODE> <PO_PNR> </PO_PNR> <BI_TIME /> <PO_NAME>ANDERS</PO_NAME> <PO_FNAME>PER ANDERS</PO_FNAME> <PO_MNAME /> <PO_LNAME> ARMSTÖD</PO_LNAME> </Relation> <Relation> <TN_CODE>B</TN_CODE> <PO_PNR> </PO_PNR> <BI_TIME /> <PO_NAME/> <PO_FNAME/> <PO_MNAME /> <PO_LNAME/> </Relation> <Relation> <TN_CODE>M</TN_CODE> <PO_PNR> </PO_PNR> <BI_TIME /> <PO_NAME>PER</PO_NAME> <PO_FNAME>PER ANDERS</PO_FNAME> <PO_MNAME /> <PO_LNAME> ARMSTÖD</PO_LNAME> </Relation> <Relation> <TN_CODE>VF</TN_CODE> <PO_PNR> </PO_PNR> <BI_TIME /> <PO_NAME>ANDERS</PO_NAME> <PO_FNAME>PER ANDERS</PO_FNAME> <PO_MNAME />

10 10 (14) <PO_LNAME> ARMSTÖD</PO_LNAME> </Relation> </PMDataSet> I ovanstående exempel har sökt person 3 barn (varav 1 antingen är avliden eller utflyttad ur regionen) samt en make registrerad. Av de tre barnen är personen vårdnadshavare över ett. De koder som kan finnas i <TN_CODE> är MO (Moder) FA (Fader) M (Maka / Make) B (Barn) VF (Vårdnadshavare för / eller för barn vem som är vårdnadshavare)

11 11 (14) Bilaga 2 SOAP och XML beskrivning av tjänsten GetPerson Retrieve one person info through a person number SOAP The following is a sample SOAP request and response. The placeholders shown need to be replaced with actual values. Request: POST /popmanweb/wspopman.asmx HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: " <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <GetPerson xmlns=" <login> <UserName>string</UserName> <Password>string</Password> </login> <spnr>string</spnr> <flagotherarchive>boolean</flagotherarchive> </GetPerson> </soap:body> </soap:envelope> Return: HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:header> <HeaderErrorInfo xmlns=" <FunctionName>string</FunctionName> <Severity>None or Critical or Warning or Information</Severity> <ErrorType>string</ErrorType> <ModuleName>string</ModuleName> <Description>string</Description> <Code>long</Code> </HeaderErrorInfo> <HeaderInfo xmlns=" <RowsCount>int</RowsCount> <MaxRows>int</MaxRows> <SourceName>string</SourceName> </HeaderInfo> </soap:header> <soap:body> <GetPersonResponse xmlns=" <GetPersonResult>string</GetPersonResult> </GetPersonResponse> </soap:body> </soap:envelope>

12 12 (14) Bilaga 3 Förklaring till termerna i taggarna Obs de taggar som aldrig används förklaras ej Befolkning och Skatteverket PO_PNR PO_TPNR PO_SECRET PO_PPNR PO_TREC PO_DNAME PO_NAME PO_FNAME PO_MNAME PO_LNAME PO_RDATE PO_CNTY PO_MUNI PO_CONGR PO_FO_CO PO_FO_ADDR1 PO_FO_ADDR2 PO_FO_ZCODE Personnummer (ÅÅÅÅMMDDNN) Temporärt personnummer, används t ex vid immigrering Flagga för att identifiera sekretess ( J = Sekretess, i detta fall finns ingen adressinformation registrerad för personen) Innehåller tidigare, nu ej giltigt, personnummer Flagga som visar om total info erhållits från Skatteverket (används som regel ej). Kod som visar vilket av förnamnen som är tilltalsnamn. Exempel: 10 betecknar att endas första namnet är tilltalsnamn, 11 = första och andra namnet, 20 = endast andra namnet. Kan vara tomt om personen ej anmält tilltalsnamn Tilltalsnamn enligt PO_DNAME Kan vara tomt om personen ej anmält tilltalsnamn Samtliga förnamn Eventuellt mellannamn till efternamnet Efternamn Registreringsdatum i Skatteverket Länskod Kommunkod Församlingskod Mantalsskrivningsadress, Care of Adress (används som regel ej) Adress (denna används som regel) Postnummer

13 13 (14) PO_FO_CITY PO_SP_CO PO_SP_ADDR1 PO_SP_ADDR2 PO_SP_ZCODE PO_SP_CITY PO_UT_ADDR1 PO_UT_ADDR2 PO_UT_ADDR3 PO_UT_CCODE PO_UT_ZCODE PO_UT_CTRY PO_UT_CITY PO_MA_DATE PO_BI_CNTY PO_BI_CONGR PO_BI_CITY PO_BI_CTRY PO_IM_DATE PO_SEX PO_NT_CODE Postadress Särskild postadress, Care of Särskild postadress (används som regel ej) Särskild postadress Särskild postadress, postnummer Särskild postadress, postadress Utlandsadress Utlandsadress Utlandsadress Utlandsadress, landskod Utlandsadress, postnummer motsv Utlandsadress, land Utlandsadress, postadress ort Datum för ändrat civilstånd Födelselän Födelseförsamling Födelseort Födelseland Immigrerings datum Kön (M/K) Icke territoriell Församlingskod PO_MS_CODE Civilstånd (kod: OG, G, G, S, Ä) PO_RB_CODE PO_BDATE CZ_CTRY CZ_CDATE Fastighetskod Födelsedatum (åååå/mm/dd) Medborgarland Datum för medborgarskap

14 14 (14) SO_TYPE SO_CODE RB_ECODE Statistisk områdestyp Statistisk områdeskod Fastighetsbeteckning För svar erhållna från Skatteverket tillkommer dessutom taggarna CN_SU_CODE CN_CDATE Kod för ev avregistrering Datum för ev avregistrerig Svar från Avregistrerade innehåller taggar med prefix CN_ Dessa motsvarar i princip informationen från PO_ taggar. CN_FO_ADDR2 etc CN_FO taggar innehåller senast kända adress i regionen innan utflyttning/dödsfall.