XML:n käyttötavat työeläkejärjestelmässä 10.1.2005
XML-sanomastandardi 2(35) 1 Johdanto... 4 2 Standardi lyhyesti... 5 3 Skeemojen toteutuksesta... 6 3.1 Yleistä... 6 3.2 Kieli... 6 3.3 Merkistö... 6 3.4 Nimeämistapa... 7 3.5 Nimien pituus ja lyhentäminen... 7 3.6 Tietotyypit ja tarkistukset skeemassa... 7 3.6.1 Rahatieto... 8 3.6.2 Päivämäärätieto... 8 3.6.3 Henkilötunnus... 9 3.6.4 Vakuutusnumero... 9 3.7 Validointi... 9 3.8 Versiointi... 9 3.9 Jakelu... 10 4 Sovellussanoma... 11 4.1 Yleistä... 11 4.2 Vakio-osa... 12 4.2.1 Aikaleima... 12 4.2.2 Laitostiedot... 12 4.2.3 Viitteet... 13 4.2.4 Lähettäjän ohjelma... 13 4.2.5 Lähettäjän käyttäjätunnus... 13 4.3 Poikkeustiedot... 14 4.3.1 Poikkeustiedot ja Poikkeus... 14 4.3.2 Taso... 14 4.3.3 Koodi... 15 4.3.4 Selite... 15 4.3.5 Kohde... 15 4.4 Sovelluskohtainen osa... 15 5 SOAP-sanoma... 16 5.1 Yleistä... 16 5.2 SOAP-sanoma... 16 5.2.1 SOAP Header... 17
XML-sanomastandardi 3(35) 5.2.2 SOAP Body... 17 5.3 WSDL-kuvaus... 18 5.4 UDDI-rekisteri... 18 5.5 Tietoturva... 18 5.6 Virhekäsittely... 19 LIITTEET: A) Perustiedot B) Sanomapari C) VakioOsa D) Poikkeustiedot E) Virhe- ja huomautuskoodeja F) Sovellussanoma
XML-sanomastandardi 4(35) 1 Johdanto Keväällä 2002 valmistui silloisen XML-sanasto- ja sanomastandardityöryhmän työn tuloksena ehdotus sanomastandardiksi. Viimeisen kahden vuoden aikana yleiset XML:ään liittyvät standardit ovat kypsyneet ja niistä on saatu käytännön kokemuksia. Erittäin tärkeä asia on myös uusi ansaintajärjestelmä, jota Arek rakentaa ja jossa XML on yksi avainkäsitteistä. Havaittiin, että omaa XML-standardia vuodelta 2002 on syytä muuttaa, jotta se soveltuisi paremmin käytännön työhön. Vuoden 2002 standardi tehtiin puhdasoppiseksi ja sovelluksia kehitettäessä on havaittu, että sen noudattaminen lisää työmääriä. Suurin syy tähän on se, etteivät sovelluskehitysvälineet tue täysin XML-standardeja (esimerkiksi kansallisen merkistön käyttäminen saattaa aiheuttaa ongelmia joissakin sovellusympäristöissä). Standardin hierarkkisuus saattoi lisäksi aiheuttaa suorituskykyongelmia. Kesäkuussa 2004 aloitti työnsä XML-jatkokehitys -työryhmä tehtävänään läpikäydä aikaisempi sanomastandardi ja päättää muutoksista kehitystyössä tehtyjen havaintojen pohjalta. Työryhmä kokoontui 2 kertaa kesäkuussa ja 5 kertaa elo-marraskuussa. Syksyllä pidettiin myös muutamia pienryhmäkokouksia, aiheina olivat tekninen sanomakehys ja sanoman rakenne. Työssä olivat mukana Kirsi Lehikoinen ja Markku Hiilinen Esy:stä, Ari Likki ja Jukka Miettinen Eterasta, Kimmo Pulkki, Jouko Katainen ja Seppo Rinne Ilmarisesta, Juha Helansuo KELAsta, Eero Renkonen KEVAsta, Timo Franssila Porastosta, Liisa Parkkonen ja Seppo Sutinen Tieto-Tapiolasta, Jussi Ahtikari, Harri Härkönen, Petri Alapiessa ja Tom Isaksson TKP Tiedosta, Heikki Auvinen Arek:sta sekä Arsi Virta, Samuel Rinnetmäki ETK:sta ja konsulttina Lasse Akselin TietoEnatorilta. Puheenjohtajana toimi Erkki Tenkula ETK:sta ja sihteerinä Ari Kunelius Heliasta. Lisäksi kuultiin asiantuntijoina Tomas Björnfotia SysOpenilta sekä Rauli Oinosta, Ari Vainiota ja Tommi Pystystä Accenturelta. Uudistettu standardi on sanomarakenteiden osalta aikaisempaa kevyempi ja painottunut enemmän tietojen välittämiseen. Toteutuksen tekniikkana käytetään web-palvelua, mikä toi standardiin mukaan lisää teknisyyttä.
XML-sanomastandardi 5(35) 2 Standardi lyhyesti Työeläkejärjestelmän sanomastandardissa sovelletaan seuraavia yleisiä suosituksia ja standardeja: Extensible Markup Language (XML) 1.0 (Third Edition) o http://www.w3c.org/tr/2004/rec-xml-20040204 XML Schema Part 0: Primer Second Edition o http://www.w3c.org/tr/2004/rec-xmlschema-0-20041028 XML Schema Part 1: Structures Second Edition o http://www.w3c.org/tr/2004/rec-xmlschema-1-20041028 XML Schema Part 2: Datatypes Second Edition o http://www.w3c.org/tr/2004/rec-xmlschema-2-20041028 Simple Object Access Method (SOAP) 1.1 o http://www.w3c.org/tr/2000/note-soap-20000508 WS-I Basic Profile Version 1.0 o http://www.ws-i.org/profiles/basicprofile-1.0-2004-04-16.html Standardin keskeiset suositukset ovat: merkistö on UTF-8 elementtien ja attribuuttien nimeämisessä käytetään suomen kieltä käytetyt nimet kuvaavat sisältöä nimeämisessä ei käytetä skandinaavisia merkkejä tai erikoismerkkejä nimeämistapa on elementeille UpperCamelCase ja attribuuteille lowercamelcase nimien suositeltu, muttei ehdoton enimmäispituus on 32 merkkiä skeemoissa käytettään pääasiassa XML Schema suosituksen perustyyppejä, omia ydintietotyyppejä määritetään vain rajoitetusti XML Scheman perustyyppiä olevien elementtien sisältöä rajoitetaan pääasiassa vain tietotyypillä ja pituusmäärityksillä jokaisella pyyntö- ja vastaussanomalla on oma skeema sekä jokaisella pyyntö/vastausparilla eli palvelulla oma WSDL- eli palvelukuvaus jokaisella palvelulla on yksilöivä nimi, joka on myös alkuosana ko. palvelun sovellussanomien juurielementin nimissä skeemojen muutokset versioidaan nimiavaruuksilla, pienemmät muutokset sovellussanomien attribuutilla skeemat ja WSDL-kuvaukset jaetaan extranet-osoitteessa ws.tyoelake.fi
XML-sanomastandardi 6(35) 3 Skeemojen toteutuksesta 3.1 Yleistä Ansaintajärjestelmän XML-dokumentit noudattavat W3C:n suositusta: Extensible Markup Language (XML) 1.0 (Third Edition) o http://www.w3c.org/tr/2004/rec-xml-20040204 Käytettävä XML:n versio 1.0 ilmaistaan dokumentin xml-tunnisteessa: <?xml version= 1.0?> Dokumenttien rakennemäärittelyssä noudatetaan suosituksia ( XML Schema 1.0 ) XML Schema Part 0: Primer Second Edition o www.w3c.org/tr/2004/rec-xmlschema-0-20041028 XML Schema Part 1: Structures Second Edition o www.w3c.org/tr/2004/rec-xmlschema-1-20041028 XML Schema Part 2: Datatypes Second Edition o www.w3c.org/tr/2004/rec-xmlschema-2-20041028 3.2 Kieli Nimeämisessä käytetään suomen kieltä. Englannin kielen käyttö helpottaisi kanssakäyntiä EU:n kanssa ja ulkomaisten asiantuntijoiden käyttöä tietoteknisissä hankkeissa. Työeläkejärjestelmässä on kuitenkin paljon vaikeasti käännettävää termistöä, koska eri maiden lainsäädännöt eroavat toisistaan. Samaa asiaa tarkoittava käsite, esimerkiksi osoite, voi myös olla rakenteeltaan erilainen eri kielissä. Suomen kielen kielioppia ei seurata pedanttisesti. Yhdysviivaa tai skandinaavisia merkkejä ei käytetä (3.4 Nimeämistapa ). 3.3 Merkistö XML-standardissa käytetään UTF-8 eli Unicode-merkistöä. <?xml version= 1.0 encoding= UTF-8?> Aiempi merkistö ISO-8859-1 on kansainvälisessä käytössä liian suppea ja EU:n laajenemisen myötä tilanne huononee entisestään.
XML-sanomastandardi 7(35) 3.4 Nimeämistapa Elementtien ja attribuuttien nimet kuvaavat sisältöään. Suomalaiset yhdyssanat käsitetään yhdeksi sanaksi (Yhdyssana ) Yhdysviivaa vaativat yhdyssanat käsitetään kahdeksi sanaksi ( VakioOsa ). Nimissä ei käytetä skandinaavisia merkkejä. Skandinaavisten merkkien käyttö elementtien nimissä olisi mahdollista, mutta aiheuttaisi lisätyötä. Kaikkien osapuolten olisi varauduttava merkkeihin omissa järjestelmissään. Sovelluskehitysvälineiden avulla voidaan generoida esim. Java-luokkamäärityksistä XML-rakenteita. Koska useat sovelluskehitysvälineet eivät tue skandinaavisia merkkejä, vaatisi skandinaavisten merkkien käyttö manuaalisia muutoksia sovelluskehitysvälineiden generoimaan koodiin tai manuaalista koodausta. Ongelma vältetään, kun ei käytetä skandinaavisia merkkejä. Nimissä ei käytetä erikoismerkkejä. Yhdysviivan ja muiden erikoismerkkien välttämistä puoltaa mahdollisuus, että jokin sovellus tai työkalu ei ymmärrä erikoismerkkejä elementtien nimissä. Elementtien nimet alkavat isolla kirjaimella ja attribuuttien nimet pienellä kirjaimella. Nimeen kuuluvat sanat aloitetaan ensimmäisen sanan jälkeen aina isolla kirjaimella. Tätä UpperCamelCase/lowerCamelCase tapaa nimeämisessä suosittaa mm. ebxml:ää kehittävä yhteisö tulevassa Naming Rules suosituksessaan. <ElementtiNimi attribuuttinimi= xxx > 3.5 Nimien pituus ja lyhentäminen Elementtien ja attribuuttien nimien suositeltava maksimipituus on 32 merkkiä. Nimen pituus voi joissakin tapauksissa ylittää suosituksen, Nimen ymmärrettävyys on tärkeämpää kuin suosituspituus. VakuutuksenAlkamisPvm ( suositeltava ) VakAlkPvm ( ei suositeltava ) 3.6 Tietotyypit ja tarkistukset skeemassa Elementin sisältöä rajoittaa käytetty tietotyyppi sekä mahdolliset rajoitukset sisällön pituuteen tai arvoon. Elementtien maksimipituudet määritetään mahdollisimman tarkasti hyödyntävän sovelluksen rajoitusten mukaan.
XML-sanomastandardi 8(35) Elementin sisältöä ei yleensä rajoiteta luettelemalla sallittuja arvoja (enumeration). Luettelointi voidaan tehdä, kun arvoja on vähän ja ne ovat luonteeltaan muuttumattomia. ( esim. 4.3.2 Taso ) XML-dokumentin validointi on vapaaehtoista. XML:n perusperiaatteita on mahdollisuus määrittää skeemaan rajoitteita elementtien sallitulle sisällölle ja tarkastaa dokumentin sisältö näitä rajoitteita vasten eli validoida dokumentti paitsi rakenteen myös sisällön suhteen ( 3.8 Validointi ) Työryhmän mielestä skeeman tulee pitäytyä rakenteen kuvaamisessa eikä puuttua tietosisältöön, joka kuitenkin tarkistetaan sanomia käsittelevissä sovelluksissa. Ryhmässä todettiin, että skeeman validointi on hyvä ominaisuus sovelluksen kehitysvaiheessa, jolloin validointi mahdollistaa kevyen testauksen ilman täydellistä sovelluskoodia. Tuotannossa skeeman validointi hidastaa suoritusta. Koska työeläkejärjestelmän sovellukset tyypillisesti välittävät oikeanmuotoista tietoa ja virheellisetkin tiedot saatetaan haluta ottaa vastaan, ei ole perusteltua käyttää skeeman validointia tuotantoympäristössä. Skeemoissa käytetään pääasiassa XML Schema suosituksen sisäisiä tietotyyppejä string Eläkeläinen integer 205 date 2004-11-10 datetime 2004-11-10T15:30:01.123456 Omia tietotyyppejä määritetään vain rajoitetusti Omat tietotyypit nimetään nimeämiskäytännön mukaisesti ymmärrettävällä nimellä, jonka perään lisätään sana Tyyppi. Omat tietotyypit on määritelty skeemassa Perustyypit.xsd ( LIITE A ) 3.6.1 Rahatieto Rahatietojen tietotyyppi on XML Schema suosituksen integer -tyyppi. Rahatiedot ilmaistaan sentteinä ilman välimerkkejä. Sovellusten tulisi tyypillisesti tukea 11 numeron käyttöä henkilökohtaisissa tiedoissa ja 13 numeron käyttöä laitoskohtaisissa tiedoissa. 3.6.2 Päivämäärätieto Päivämäärien tietotyyppi on XML Schema suosituksen date -tyyppi. Tyyppi vastaa ISO 8601-standardia, jossa päivämäärä ilmaistaan muodossa vsvu-kk-pv Tästä tyypistä sovelluskehitysvälineet mahdollistavat eri esitysmuotojen käytön.
XML-sanomastandardi 9(35) Vajaat päivämäärät ilmaistaan merkkijonoina. Esimerkiksi kuolinpäivästä saatetaan tietää vain vuosi ja kuukausi. 3.6.3 Henkilötunnus Henkilötunnusten tietotyyppi on oma tyyppi HenkilotunnusTyyppi. Henkilötunnusten pituus on aina 11 merkkiä. HenkilotunnusTyyppi on rajoitettu merkkijono, jossa jokaisen merkin sallittu arvo on rajoitettu vastaamaan suomalaisen henkilötunnuksen mahdollisia arvoja samassa merkkipositiossa. ( LIITE A ) Esimerkiksi: 010100-001Y oikein 012100-001Z väärin ( 3. merkki voi olla vain 0 tai 1, tarkistusmerkki ei voi olla Z ) 3.6.4 Vakuutusnumero Vakuutusnumeroiden tietotyyppi on oma tyyppi VakuutusnumeroTyyppi. Vakuutusnumeroiden pituus on aina 11 merkkiä. VakuutusnumeroTyyppi on rajoitettu merkkijono, joka vastaa muotoa 99-99999999 tai 99999-99999, jossa 9 tarkoittaa mitä tahansa numeroa nollasta yhdeksään. ( LIITE A ) Esimerkiksi: 12-12345678 oikein 1234-123456 väärin ( väliviiva väärässä paikassa ) 3.7 Validointi Järjestelmän SOAP-sanomat ja palvelukuvaukset vastaavat määritystä: WS-I Basic Profile Version 1.0 o www.ws-i.org/profiles/basicprofile-1.0-2004-04-16.html Näin voidaan varmistaa eri välineillä tuotettujen tiedostojen keskinäinen yhteensopivuus. XML-dokumenttien validointi on toimijoiden oman harkinnan varassa. 3.8 Versiointi Skeemojen muutokset versioidaan päivämäärän sisältävillä nimiavaruuksilla:
XML-sanomastandardi 10(35) sijainti/vuosi/kuukausi/päivä/skeemanimi W3C käyttää versioinnissaan samantapaista ratkaisua. http://www.w3.org/tr/2000/rec-xml-20001006 o W3C Recommendation 6 October 2000 http://www.w3.org/tr/2003/per-xml-20031030/ o W3C Proposed Edited Recommendation 30 October 2003 http://www.w3.org/tr/2004/rec-xml-20040204/ o W3C Recommendation 4 February 2004 Versioinnin toteutuksesta ei ole varsinaista suositusta. Versio ilmaistaan skeeman schema-elementin targetnamespace attribuutilla: <schema targetnamespace= https://ws.tyoelake.fi/2004/11/04/tutkionkohenkilotunnistettu > Pienemmät sovellusmuutokset, jotka eivät vaadi muutosta skeemoihin, ilmaistaan palvelutunnuksen attribuuttina numero-piste-numero notaatiolla. <TutkiOnkoHenkiloTunnistettuPyynto sanomaversio= 2.11 > 3.9 Jakelu Skeemat ja palvelukuvaukset ( 5.3 WSDL-kuvaus ) jaetaan osoitteesta ws.tyoelake.fi https://ws.tyoelake.fi/versiotieto/skeema/skeema.xsd https://ws.tyoelake.fi/versiotieto/palvelukuvaus/palvelukuvaus.wsdl Esimerkiksi https://ws.tyoelake.fi/2004/12/03/vakioosa/vakioosa.xsd
XML-sanomastandardi 11(35) 4 Sovellussanoma 4.1 Yleistä Ansaintajärjestelmän palvelut perustuvat sanomien pyyntö/vastauspareihin. <PalvelutunnusPyynto> <VakioOsa /> <SovelluskohtainenOsa /> </PalvelutunnusPyynto> <PalvelutunnusVastaus> <VakioOsa /> <Poikkeustiedot /> <SovelluskohtainenOsa /> </PalvelutunnusVastaus> Sovellussanoma on järjestelmässä liikkuva yksittäinen pyyntö- tai vastaussanoma. Eräajoissa ja on-line-ohjelmissa käsitellään samoja sanomia. Järjestelmän kannalta erona on vain kerralla siirrettävien sovellussanomien määrä ja niiden siirtotapa. Palvelutunnuksena käytetään palvelua kuvaavaa pitkää nimeä ja se on samalla osa palvelusanoman juurielementin nimeä. Tunnus on erilainen paitsi eri palveluiden välillä, myös saman palvelun pyyntöja vastaussanomille. Palvelun tekninen nimi annetaan palvelutunnuksen attribuuttina ja on sama sekä pyyntö- että vastaussanomille. Tekninen nimi ei ole pakollinen. <TutkiOnkoHenkiloTunnistettuVastaus palvelutunnus= PH802 > <VakioOsa /> <Poikkeustiedot /> <SovelluskohtainenOsa /> </TutkiOnkoHenkioTunnistettuVastaus> Jokaisella sanomaparilla on oma skeemansa pyyntö- ja vastaussanomalle: /TutkiOnkoHenkiloTunnistettu/TutkiOnkoHenkiloTunnistettuPyynto.xsd /TutkiOnkoHenkiloTunnistettu/TutkiOnkoHenkiloTunnistettuVastaus.xsd Esimerkki sanomaparista skeemoineen löytyy liitteestä B Sanomapareissa hyödynnettäviksi on määritelty seuraavat yleiskäyttöiset skeemat VakioOsa.xsd o kaikissa sanomissa tarvittaville ohjaustiedoille Poikkeustiedot.xsd
XML-sanomastandardi 12(35) o vastaussanomien virhetietojen välittämiseen Perustyypit.xsd o määritykset omille ydintyypeille 4.2 Vakio-osa Vakio-osassa välitetään eri sanomille yhteisiä ohjaustietoja, joita ovat: Aikaleima LahettavaElakevakuuttaja LahettajanHoitavaToimija LahettajanOhjelma LahettajanKayttajatunnus LahettajanViite VastaanottavaElakevakuuttaja VastaanottajanHoitavaToimija VastaanottajanViite Vakio-osa on määritetty skeemassa VakioOsa.xsd ( LIITE C ). 4.2.1 Aikaleima Aikaleimojen tietotyyppi on XML Schema suosituksen datetime -tyyppi. Aikaleima-elementti on pakollinen. Suosituksena on käyttää aikaleimaa 6 desimaalin tarkkuudella. Kukin laitos täyttää aikaleiman teknisten mahdollisuuksiensa mukaisesti. 4.2.2 Laitostiedot LahettavaElakevakuuttaja LahettajanHoitavaToimija VastaanottavaElakevakuuttaja VastaanottajanHoitavaToimija Laitostietojen tietotyyppi on XML Schema suosituksen string tyyppi.
XML-sanomastandardi 13(35) Laitostieto-elementit ovat pakollisia. Laitostieto esitetään laitosnumerona, joka on joko 2 tai 5-merkkinen laitosnumero. Laitosten nimiä ei käytetä. 4.2.3 Viitteet LahettajanViite VastaanottajanViite Viitteiden tietotyyppi on XML Schema suosituksen string tyyppi. Viite-elementit ovat pakollisia. Viitteen muoto on vapaa. Pyyntösanomassa oleva lähettäjän viite säilyy LahettajanViite-elementissä myös vastaussanomassa. Viitteidensä avulla lähettäjä ja vastaanottaja voivat yksilöidä sanoman ja liittää sen muihin loogisiin kokonaisuuksiin. 4.2.4 Lähettäjän ohjelma LahettajanOhjelma Tietotyyppi on XML Schema suosituksen string tyyppi. Elementti on pakollinen, mutta voi olla tyhjä. Kutsuvan palvelun tai ohjelman nimi tai tunnus. Käytetään virheenselvittelyssä sekä valvonnan ja laskutuksen tietojenantokirjauksiin. 4.2.5 Lähettäjän käyttäjätunnus LahettajanKayttajatunnus Tietotyyppi on XML Schema suosituksen string tyyppi. Elementti on pakollinen. Tietoa käytetään tietojenannon seurantaan ja tarvittaessa lähettävä eläkelaitos voi identifioida varsinaisen lähettäjän. Lähettäjä vastaa sisällön oikeellisuudesta.
XML-sanomastandardi 14(35) 4.3 Poikkeustiedot Poikkeustiedot määritetään skeemassa Poikkeustiedot.xsd ( LIITE D ) Poikkeustiedoilla tarkoitetaan tietoja, jotka ovat yhteisiä kaikille sanomille, mutta eivät esiinny kaikissa sanomissa, esimerkiksi virhetiedot. Sanomassa voi esiintyä virhetietoja 0-n kappaletta <Poikkeustiedot> <Poikkeus> <Taso /> <Koodi /> <Selite /> <Kohde /> </Poikkeus> </Poikkeustiedot> 4.3.1 Poikkeustiedot ja Poikkeus Poikkeustiedot on sovellussanomissa valinnainen elementti. Poikkeus-elementti on pakollinen. 4.3.2 Taso Tietotyyppi on XML Schema suosituksen string tyyppi. Taso-elementti on pakollinen. Tiedolla on 3 sallittua merkkimuotoista arvoa. Sallitut arvot ja niiden merkitykset ovat: Virhe o Kutsuttua palvelua ei pystytty suorittamaan Varoitus o Palvelu suoritettiin, mutta tulokseen sisältyy varoituksia, joihin liittyvät ongelmat ovat palvelun kutsujan vastuulla Huomautus o Palvelu suoritettiin, mutta tulokseen sisältyy huomautuksia, joihin liittyvät ongelmat ovat palvelun tarjoajan vastuulla <Taso>Varoitus</Taso> Sallitut arvot määritetään skeemassa elementin sisäisenä rajoituksena.
XML-sanomastandardi 15(35) 4.3.3 Koodi Tietotyyppi on XML Schema suosituksen string tyyppi. Koodi-elementti on pakollinen. Kooditieto on vapaamuotoinen, sovelluskohtainen virhekoodi. Esimerkkejä ETK:n käyttämistä virhekoodeista löytyy liitteestä E 4.3.4 Selite Tietotyyppi on XML Schema suosituksen string tyyppi. Selite-elementti on pakollinen. Selite on vapaamuotoinen ja voi sisältää tietoa virheen tai huomautuksen laadusta, vihjeen siitä, mikä pyyntö- tai vastaussanoman elementti liittyy virheeseen tai ohjeen palvelun kutsujalle, miten kutsua pitäisi muokata. 4.3.5 Kohde Tietotyyppi on XML Schema suosituksen string tyyppi. Kohde-elementti on pakollinen, mutta voi olla tyhjä. Poikkeukseen liittyvän XML-elementin id-attribuutin arvo. Voi viitata joko pyyntö- tai vastaussanoman elementtiin. Hyödyllinen lähinnä toistuvissa rakenteissa, joissa vain tietty elementti aiheutti ongelman. Esimerkiksi tästä syystä pyyntösanomien toistuville elementeille tulee määritellä id-attribuutti. 4.4 Sovelluskohtainen osa Sovelluskohtaisessa osassa välitetään sanomittain muuttuvat tiedot, TEL-ilmoitus on erilainen kuin selvityspyyntö. Sovellussanoman juurielementin nimi on palvelutunnuksen nimi lisättynä sanalla Pyynto tai Vastaus. <TutkiOnkoHenkiloTunnistettuPyynto /> <TutkiOnkoHenkiloTunnistettuVastaus /> Jokaisella sanomaparilla on oma skeema pyyntö- ja vastaussanoman sovelluskohtaiselle osalle: /TutkiOnkoHenkiloTunnistettu/Pyynto.xsd /TutkiOnkoHenkiloTunnistettu/Vastaus.xsd Sovelluskohtaisen osan määrittely on sovelluskehitysprojektin tehtävä. Tässä standardissa ei ole määritelty sovelluskohtaisen osan rakennetta. Esimerkki pyyntö- ja vastaussanomista skeemoineen löytyy liitteestä F
XML-sanomastandardi 16(35) 5 SOAP-sanoma 5.1 Yleistä Ansaintajärjestelmän XML-pohjaisen sanomavälityksen tekniikaksi on valittu web-sovelluspalvelu (Web Service). Web-sovelluspalvelut edustavat XML:ään perustuvaa standardoitua tekniikkaa. Tämän tekniikan kolme ydinkäsitettä ovat SOAP-sanoma, WSDL-kuvaus ja UDDI-rekisteri. 5.2 SOAP-sanoma SOAP on kevyt XML:ään perustuva tiedonvälityksen protokolla, joka on tarkoitettu rakenteisen ja tyypitetyn tiedon, kuten XML-dokumenttien välittämiseen jonkin toisen protokollan, esimerkiksi HTTP:n avulla. SOAP-sanoma on protokollan liikennöintiyksikkö. Web-palvelussa palvelun käyttäjä ja tarjoaja kommunikoivat keskenään määrämuotoisilla SOAP-sanomilla. SOAP-sanoman rakenne: SOAP:Envelope SOAP:Header SOAP:Body TutkiOnkoHenkiloTunnistettuPyynto Sama XML-muodossa: :
XML-sanomastandardi 17(35) <SOAP:Envelope> <SOAP:Header /> <SOAP:Body> <TutkiOnkoHenkiloTunnistettuPyynto palvelutunnus= PH802 /> </SOAP:Body> </SOAP:Envelope> Sanoman sisältö eli sovellussanoma sijoitetaan runko-osaan (SOAP:Body). Sanomaan voidaan lisätä otsikko-osa (SOAP:Header). Otsikko- ja runko-osa paketoidaan vielä kirjekuoreen (SOAP:Envelope) ja sanoma on valmis siirrettäväksi valitun alemman tason protokollan avulla. SOAP-sanoma on kokonaan merkkimuotoista tietoa. Protokollaan on sisäänrakennettuna tuki XML:n tietotyyppien muuntamiseksi merkkimuotoon. 5.2.1 SOAP Header SOAP standardi ei määrittele otsikko-osan sisältöä, vaan sisältö voidaan määrittää sovelluskohtaisesti Työeläkejärjestelmässä otsikkotiedoissa välitetään järjestelmän autentikointiin liittyviä tietoja, kuten sähköinen allekirjoitus ( 5.5 Tietoturva ). <SOAP:Header> <Security /> </SOAP:Header> 5.2.2 SOAP Body Sovelluskohtaiset palvelupyynnöt ja -vastaukset välitetään SOAP-sanoman runko-osassa. Runko-osa on SOAP-sanomassa aina pakollinen. <SOAP:Body> <TutkiOnkoHenkiloTunnistettuPyynto palvelutunnus= PH802 sanomaversio= 2.11 > <VakioOsa> </VakioOsa> <Pyynto> </Pyynto> </TutkiOnkoHenkiloTunnistettuPyynto> </SOAP:Body>
XML-sanomastandardi 18(35) 5.3 WSDL-kuvaus Jokaista työeläkejärjestelmän palvelua varten tehdään erillinen palvelu- eli WSDL-kuvaus. WSDL on kieli, jolla kuvataan toteutettuja SOAP-palveluita. Palvelukuvaus on XML-dokumentti, jossa kerrotaan tietyn SOAP-palvelun URL-osoite, palvelun tukemat metodit (TutkiOnkoHenkiloTunnistettuPyynto) sekä metodien kutsuparametrit. Palvelukuvaus siis kertoo sitä ymmärtävälle sovellukselle, mistä jokin SOAP-palvelu löytyy ja mitä palveluita se tukee. Sovellussanoma voi muuttua esimerkiksi lakimuutoksen takia niin paljon, että sanomaan liittyvistä skeemoista on laadittava uudet versiot. Rakennemuutosten lisäksi muuttuvat myös skeemojen nimiavaruudet. Tällöin kyseisiä skeemoja käyttävien palveluiden WSDL-kuvaukset on päivitettävä vastaamaan uusia nimiavaruuksia. 5.4 UDDI-rekisteri Palvelun tarjoaja voi julkaista palvelukuvauksensa julkisessa UDDI-rekisterissä, josta kuvaus on kenen tahansa palvelua etsivän saatavissa. Rekisteripalveluja tarjoavat useat alan toimijat mm IBM ja Microsoft, tai palveluntarjoaja voi perustaa oman rekisterinsä, jonka kautta jakelee palvelukuvauksensa. Tekniseltä kannalta UDDI on rajapinta, jonka avulla palveluita voi hakea erilaisilla hakukriteereillä jostakin keskitetystä rekisteristä. Työeläkejärjestelmän web-palvelujen käyttäjäkunta on hyvin rajallinen. Palvelukuvauksia ei julkaista UDDI-rekistereissä, vaan jakelu hoidetaan extranet-ratkaisulla. 5.5 Tietoturva Tiedon salaus fyysisen siirron aikana hoidetaan kutsujan ja vastaajan välisellä salatulla yhteydellä. Sanoma autentikoidaan ja eheys varmistetaan digitaalisella allekirjoituksella. Allekirjoitus toteutetaan soveltamalla valikoidusti standardeja SOAP Message Security 1.0 (WS-Security 2004) o http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security- 1.0.pdf X.509 Certificate Token Profile o http://docs.oasis-open.org/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf WS-I Basic Security Profile o http://www.ws-i.org/profiles/basicsecurityprofile-1.0-2004-05-12.html Standardien tuettavista ominaisuuksista ei ole vielä lopullista päätöstä.
XML-sanomastandardi 19(35) Allekirjoitus välitetään SOAP-sanoman otsikko-osaan liitettävässä WS-Security 2004 standardin mukaisessa Security elementissä. <SOAP:Header> <Security> <Timestamp /> <BinarySecurityToken /> <Signature /> </Security> </SOAP:Header> Timestamp-elementti sisältää kaksi elementtiä Created luontiaika Expires vanhenemisaika BinarySecurityToken-elementti sisältää lähettäjän X.509 sertifikaatin, joka puolestaan sisältää mm. lähettäjän julkisen avaimen sertifikaatin varmentajan allekirjoituksen teknisiä tietoja, kuten käytetyt algoritmit Signature-elementistä löytyvät allekirjoitettujen osien tiivisteet sekä itse allekirjoitus. Allekirjoitettavat osat ovat: Timestamp BinarySecurityToken SOAP:Body Osat allekirjoitetaan kokonaisina alku- ja lopputageineen. Sanoman vastaanottaja tarkastaa, että allekirjoitus täsmää sanoma ei ole vanhentunut vaaditut osat on allekirjoitettu sanoman mukana vastaanotettu sertifikaatti on luotettu 5.6 Virhekäsittely
XML-sanomastandardi 20(35) Palvelun käytössä voi tapahtua kolmenlaisia virheitä: sovelluslogiikan virhe tekninen virhe viestinvälityksen virhe Sovelluslogiikkaan liittyvät virheet lisätään vastaussanomiin poikkeustietoina. ( 4.3 Poikkeustiedot ) Tekniset virheet palautetaan SOAP-protokollan mukaisina SOAP-Faulteina. Viestinvälitykseen liittyvät virheet palautetaan HTTP:n virhekoodeina tai SOAP-Faulteina.
XML-sanomastandardi 1 LIITE A Perustyypit Perustyypit.xsd <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace="https://ws.tyoelake.fi/2004/12/28/perustyypit" xmlns="http://www.w3.org/2001/xmlschema" xmlns:perus="https://ws.tyoelake.fi/2004/12/28/perustyypit" elementformdefault="qualified"> <simpletype name="henkilotunnustyyppi"> <restriction base="string"> <pattern value="[0-3]\d[01]\d{3}[+\-a]\d{3}[0-9a-fhj-npr-y]"/> <simpletype name="vakuutusnumerotyyppi"> <restriction base="string"> <maxlength value="11"/> <minlength value="11"/> <pattern value="\d{2,5}\-\d{5,8}"/> </schema> Käyttö skeemoissa: <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace= "https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettupyynto" xmlns:perus="https://ws.tyoelake.fi/2004/11/24/perustyypit" xmlns="http://www.w3.org/2001/xmlschema" elementformdefault="qualified"> <import namespace="https://ws.tyoelake.fi/2004/11/24/perustyypit" schemalocation="../../../../2004/11/24/perustyypit/perustyypit.xsd"/>... <element name= Henkilotunnus type= perus:henkilotunnustyyppi />... </schema>
XML-sanomastandardi 1 LIITE B Sanomapari Pyyntösanoma: Skeema: <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace= "https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettu/pyyntosanoma" xmlns:pyynto="https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettupyynto" xmlns:vakio="https://ws.tyoelake.fi/2004/11/29/vakioosa" xmlns:poikkeus="https://ws.tyoelake.fi/2004/11/17/poikkeustiedot" xmlns="http://www.w3.org/2001/xmlschema" elementformdefault="qualified"> <import namespace="https://ws.tyoelake.fi/2004/11/29/vakioosa" schemalocation="../../../../2004/11/29/vakioosa/vakioosa.xsd"/> <import namespace="https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettupyynto" schemalocation="./pyynto.xsd"/> <element name="tutkionkohenkilotunnistettupyynto"> <complextype> <sequence> <element ref="vakio:vakioosa"/> <element ref="pyynto:pyynto"/> </sequence> <attribute name="palvelutunnus" type="string" use="required" fixed="ph802"/> <attribute name="sanomaversio" type="string" /> </complextype </schema> Malli: <sanoma:tutkionkohenkilotunnistettupyynto xmlns:sanoma= "https//ws.tyoelake.fi/2004/11/29/tutkionkohenkilotunnistettu/pyyntosanoma" xmlns:pyynto= "https://ws.tyoelake.fi/2004/11/29/tutkionkohenkilotunnistettupyynto" xmlns:vakio="https://ws.tyoelake.fi/2004/11/29/vakioosa" palvelutunnus="ph802" sanomaversio="" > <vakio:vakioosa > </vakio:vakioosa> <pyynto:pyynto> </pyynto:pyynto> Katso LIITE C: Malli - Pyyntö Katso LIITE F: Malli - Pyyntö <sanoma:tutkionkohenkilotunnistettupyynto>
XML-sanomastandardi 2 LIITE B Vastaussanoma: Skeema: <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace= "https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettu/vastaussanoma" xmlns="http://www.w3.org/2001/xmlschema" xmlns:poikkeus="https://ws.tyoelake.fi/2004/11/17/poikkeustiedot" xmlns:vakio="https://ws.tyoelake.fi/2004/11/29/vakioosa" xmlns:vastaus= "https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettuvastaus" elementformdefault="qualified"> <import namespace="https://ws.tyoelake.fi/2004/11/29/vakioosa" schemalocation="../../../../2004/11/29/vakioosa/vakioosa.xsd"/> <import namespace="https://ws.tyoelake.fi/2004/11/17/poikkeustiedot" schemalocation="../../../../2004/11/17/poikkeustiedot/poikkeustiedot.xsd"/> <import namespace="https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettuvastaus" schemalocation="./vastaus.xsd"/> <element name="tutkionkohenkilotunnistettuvastaus"> <complextype> <sequence> <element ref="vakio:vakioosa"/> <element ref="poikkeus:poikkeustiedot" minoccurs="0" /> <element ref="vastaus:vastaus"/> </sequence> <attribute name="tunnus" type="string" use="required" fixed="ph802"/> </complextype> </schema> Malli: <sanoma:tutkionkohenkilotunnistettuvastaus xmlns:sanoma= "https//ws.tyoelake.fi/2004/11/29/tutkionkohenkilotunnistettu/vastaussanoma" xmlns:vastaus= "https://ws.tyoelake.fi/2004/11/29/tutkionkohenkilotunnistettuvastaus" xmlns:poikkeus="https://ws.tyoelake.fi/2004/11/17/poikkeustiedot" xmlns:vakio="https://ws.tyoelake.fi/2004/11/29/vakioosa" palvelutunnus="ph802" sanomaversio="" > <vakio:vakioosa > </vakio:vakioosa> <poikkeus:poikkeustiedot> </poikkeus:poikkeustiedot> <vastaus:vastaus> </vastaus:vastaus> <sanoma:tutkionkohenkilotunnistettuvastaus> Katso LIITE C: Malli - Vastaus Katso LIITE D: Malli Katso LIITE F: Malli - Vastaus
XML-sanomastandardi 1 LIITE C Skeema: VakioOsa <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace="https://ws.tyoelake.fi/2004/11/29/vakioosa" xmlns:perus="https://ws.tyoelake.fi/2004/11/24/perustyypit" xmlns:vakio="https://ws.tyoelake.fi/2004/11/29/vakioosa" xmlns="http://www.w3.org/2001/xmlschema" elementformdefault="qualified" version="1.0"> <import namespace="https://ws.tyoelake.fi/2004/11/24/perustyypit" schemalocation="../../../../2004/11/24/perustyypit/perustyypit.xsd"/> <element name="vakioosa" type="vakio:vakioosatyyppi"> <complextype name="vakioosatyyppi"> <sequence> <element name="aikaleima" type="datetime"> Mahdollisimman tarkasti (mikrosekuntien tarkkuudella). <element name="lahettavaelakevakuuttaja" > <restriction base="string" > <minlength="5" /> <maxlength="5" /> Eläkelaitosnumero (2 tai 5 numeroa). Tasataan oikealle, täytetään välilyönneillä <element name="lahettajanhoitavatoimija" minoccurs="0"> <restriction base="string" > <minlength="5" /> <maxlength="5" /> Eläkelaitosnumero (2 tai 5 numeroa). Tasataan oikealle, täytetään välilyönneillä <element name="lahettajanohjelma" type="string"> Pakollinen tieto, mutta voi olla tyhjä. Kutsuvan ohjelman/palvelun nimi tai tunnus. Käytetään virheenselvittelyssä sekä valvonnan ja laskutuksen tietojenantokirjauksiin.
XML-sanomastandardi 2 LIITE C <element name="lahettajankayttajatunnus" type="string"> Kutsuvaa ohjelmaa/palvelua käyttävän käyttäjän käyttäjätunnus tai yksilöivä numero. Käytetään virheenselvittelyssä sekä valvonnan ja laskutuksen tietojenantokirjauksiin. <element name="lahettajanviite" type="string"> Lähettäjän pyyntösanomalle antama viite. Jos palvelun A kutsuminen saa palvelun A kutsumaan palvelua B, palvelu A voi laittaa kutsusanomalle alkuperäisen viitteen, jolloin saman asian käsittelyyn liittyvät sanomat voidaan yhdistää. Vastaussanomalla palautetaan sama tieto kuin kutsusanomalla oli. Lähettäjä saa määritellä viitteen muodon haluamakseen. <element name="vastaanottavaelakevakuuttaja" > <restriction base="string" > <minlength="5" /> <maxlength="5" /> Tiedon vastaanottaja ei vältämättä aina ole sama taho kuin missä sanoman vastaanottava palvelu sijaitsee. Vastaanottava laitos on tiedon lopullinen vastaanottaja. Eläkelaitosnumero, 2 tai 5 merkkiä. ). Tasataan oikealle, täytetään välilyönneillä <element name="vastaanottajanhoitavatoimija" minoccurs="0"> <restriction base="string" > <minlength="5" /> <maxlength="5" /> Vastaanottajan hoitava laitos on tiedon lopullisen vastaanottajan hoitava laitos. Eläkelaitosnumero (2 tai 5 numeroa). Tasataan oikealle, täytetään välilyönneillä <element name="vastaanottajanviite" type="string"> Vastaanottajan vastaussanomalle antama viite ("vastaussanoman lähettäjän viite"). Vastaanottaja saa määritellä viitteen muodon haluamakseen. </sequence> </complextype> </schema>
XML-sanomastandardi 3 LIITE C Malli - Pyyntö: <vakio:vakioosa> <vakio:aikaleima>2004-12-17t09:30:47.123456</vakio:aikaleima> <vakio:lahettavaelakevakuuttaja> 90</vakio:LahettavaElakevakuuttaja> <vakio:lahettajanohjelma>vare</vakio:lahettajanohjelma> <vakio:lahettajankayttajatunnus>t8gj</vakio:lahettajankayttajatunnus> <vakio:lahettajanviite>v500</vakio:lahettajanviite> <vakio:vastaanottavaelakevakuuttaja> 15</vakio:VastaanottavaElakevakuuttaja> <vakio:vastaanottajanviite></vakio:vastaanottajanviite> </vakio:vakioosa> Malli - Vastaus: <vakio:vakioosa> <vakio:aikaleima>2004-12-17t09:33:15</vakio:aikaleima> <vakio:lahettavaelakevakuuttaja> 90</vakio:LahettavaElakevakuuttaja> <vakio:lahettajanohjelma>vare</vakio:lahettajanohjelma> <vakio:lahettajankayttajatunnus>t8gj</vakio:lahettajankayttajatunnus> <vakio:lahettajanviite>v500</vakio:lahettajanviite> <vakio:vastaanottavaelakevakuuttaja> 15</vakio:VastaanottavaElakevakuuttaja> <vakio:vastaanottajanviite>v0500222</vakio:vastaanottajanviite> </vakio:vakioosa>
XML-sanomastandardi 1 LIITE D Poikkeustiedot Skeema: <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace="https://ws.tyoelake.fi/2004/11/29/poikkeustiedot" xmlns:tns="https://ws.tyoelake.fi/2004/11/29/poikkeustiedot" xmlns="http://www.w3.org/2001/xmlschema" elementformdefault="qualified" version="1.0" > <element name="poikkeustiedot" type="tns:poikkeustiedottyyppi"/> <complextype name="poikkeustiedottyyppi"> <sequence> <element name="poikkeus" type="tns:poikkeustyyppi" maxoccurs="unbounded"> Poikkeus-elementti on pakollinen, mutta itse Poikkeustiedot tulisi määritellä valinnaiseksi elementiksi sanomalle. </sequence> </complextype> <complextype name="poikkeustyyppi"> <sequence> <element name="taso"> Voi olla yksi seuraavista: Virhe (kutsuttua palvelua ei pystytty suorittamaan) Varoitus (palvelu suoritettiin, mutta tulokseen sisältyy varoituksia Huomautus - varoituksiin liittyvät mahdolliset ongelmat ovat palvelun kutsujan vastuulla) (palvelu suoritettiin, mutta tulokseen sisältyy huomautuksia - huomautuksiin liittyvät mahdolliset ongelmat ovat palvelun tarjoajan vastuulla) <restriction base="string"> <enumeration value="virhe"/> <enumeration value="varoitus"/> <enumeration value="huomautus"/> <element name="koodi" type="string"> Virhekoodi voidaan määritellä sovelluskohtaisesti. Vanhan sanomastandardin mukainen koodi on muotoa SSnnnT, jossa SS on sovellustunnus, nnn kyseisen sovelluksen sisällä uniikki numero ja T virheen tyyppi: V = virhe H = huomautus I = informatiivinen tiedotus A = hälytys
XML-sanomastandardi 2 LIITE D <element name="selite" type="string"> Virheen selite voi sisältää tietoa virheen tai huomautuksen laadusta, vihjeen siitä, mikä pyyntö- tai vastaussanoman elementti liittyy virheeseen tai ohjeen palvelun kutsujalle, miten kutsua pitäisi muokata. <element name="kohde" type="string"> Poikkeukseen liittyvän XML-elementin id-attribuutin arvo. Voi viitata joko pyyntö- tai vastaussanoman elementtiin. Hyödyllinen lähinnä toistuvissa rakenteissa, joissa vain tietty elementti aiheutti ongelman. Esimerkiksi tästä syystä pyyntösanomien toistuville elementeille tulee määritellä id-attribuutti. </sequence> </complextype> </schema> Malli: <poikkeus:poikkeustiedot> <poikkeus:poikkeus> <poikkeus:taso>virhe</poikkeus:taso> <poikkeus:koodi>he120v</poikkeus:koodi> <poikkeus:selite>henkilön tunnus on virheellinen</poikkeus:selite> <poikkeus:kohde></poikkeus:kohde> </poikkeus:poikkeus> </poikkeus:poikkeustiedot>
XML-sanomastandardi 1 LIITE E Virhe- ja huomautuskoodeja ETK:n koodeja: XX999T XX sovellusalue TS = tyosuhdesovellus HE = henkilotunnistus YL = vakio-osan tai sanoman tietoryhmien tarkistus 999 virhekoodi 001-600 = sanomatarkistuksissa havaittu virhe tai huomautus 601-999 = rekisteröinnissä havaittu virhe tai huomautus T virhetaso V = tarkistuksissa havaittu rekisteröinnin estävä virhe H = ilmoitus rekisteröity, mutta tarkistuksissa havaittu huomautettavaa lievä huomautus I = ilmoitus rekisteröity, mutta tarkistuksissa havaittu huomautettavaa tiedoksi Esimerkkejä: TS012V TS100H TS631V TS632H HE023V HE104I HE120V Suhteen alkamissyy puuttuu Tarkista rahastoitu eläke Vakuutusjaksoa ei löydy rekisteristä Rekisterissä päällekkäinen työsuhde samalla eläkejärjestelynumerolla Henkilöä ei ole rekisterissä Tunnus mitätöity, tunnistuu voimassaolevaan Henkilön tunnus on virheellinen Arek:n koodeja: SOV_MOD_9999 SOV_ sovellustaso Se Meridea Design Centerin (MDC) sovellustason tunnus, johon koodin määritellyt sovellus(moduuli) kuuluu. Esim. ANS, YLE _MOD_ moduulitunnus Sovelluksen moduulitunnus MDS:ssä. Esim. IH, OHJ Esimerkkejä: _9999 virhenumero Sovelluksen vapaasti määrittämä numerokoodi ANS_IH_0220 YLE_OHJ_0102
XML-sanomastandardi 1 LIITE F Pyyntösanoma: Sovellussanoma Skeema: <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace= "https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettupyynto" xmlns:perus="https://ws.tyoelake.fi/2004/11/24/perustyypit" xmlns="http://www.w3.org/2001/xmlschema" elementformdefault="qualified"> <import namespace="https://ws.tyoelake.fi/2004/11/24/perustyypit" schemalocation="../../../../2004/11/24/perustyypit/perustyypit.xsd"/> <element name="pyynto"> "Arek käyttää Hesun tunnistusta henkilön tunnistamiseen saadakseen selville henkilön surrogaatin sekä henkilötietojen hakemiseen." Lisäksi Hesu-palveluille pitää välittää tietoja kutsuvasta laitoksesta (mm. käytetyn ohjelman tunnus ja käyttäjän käyttäjätunnus)! <complextype> <sequence> <element name="henkilotunnus" minoccurs="0"> Voi olla virallinen VRK:n myöntämä henkilötunnus (ei muodostaja-attribuuttia) tai ETK:n myöntämä ns. ETK-tunnus (muodostaja="10"). <complextype> <simplecontent> <extension base="perus:henkilotunnustyyppi"> <attribute name="muodostaja" use="optional"> <restriction base="string" > <minlength="5" /> <maxlength="5" /> </attribute> </extension> </simplecontent> </complextype> <element name="syntymaaika" type="date" minoccurs="0"> Oltava oikea kalenteripäivämäärä.
<element name="sukupuoli" minoccurs="0"> <restriction base="string"> <enumeration value="m"> <enumeration value="n"> M = mies, N = nainen. <element name="sukunimi" minoccurs="0"> Suuraakkosin? Korkeintaan 40 merkkiä? <restriction base="string"> <maxlength value="40"/> <element name="etunimet" minoccurs="0"> Suuraakkosin? Korkeintaan 40 merkkiä? <restriction base="string"> <maxlength value="40"/> XML-sanomastandardi 2 LIITE F <element name="surrogaatti" type="integer" minoccurs="0"> ETK:n surrogaatti. Pituus 9 merkkiä. <element name="kuolinpaiva" minoccurs="0"> Esiintyy vain, jos henkilö on kuollut. Voi olla muotoa YYYY, YYYY-MM tai YYYY-MM-DD? (Jos voi, date ei kelpaa tietotyypiksi.) <restriction base="string"> <maxlength value="10"/> <element name="kuolemanvahvistustapa" minoccurs="0">
LIITE F Esiintyy vain, jos henkilö on kuollut. Ilmoitetaan koodilla: 1 = todettu 2 = julistettu 3 = vahvistamaton <restriction base="string"> <maxlength value="10"/> XML-sanomastandardi 3 <element name="tietojenantokielto" minoccurs="0"> tyhjä = ei tietojenantokieltoa K = otepalvelun tietojenantokielto (henkilölle ei saa lähettää työeläkeotetta), korkeintaan 1 merkki <restriction base="string"> <maxlength value="1"/> <element name="toimenpide" type="string" minoccurs="0"> HAE = henkilön haku TUNNISTA = Henkilön tunnistus (vastaussanomalla palautetaan koodina HH tai HT) Ei pakollinen tieto? Miten itse asiassa vaikuttaa palvelun toimintaan??? <element name="tunnuksentila"> Ilmoitetaan koodilla: 1 = tunnus voimassa 2 = voimaanjäävä tunnus (tunnuksen korjaus tekeillä) 6 = mitätöitävä tunnus (tunnuksen korjaus tekeillä) <restriction base="string"> <maxlength value="1"/> </sequence> </complextype> </schema> Malli Pyyntö: <Pyynto> <Henkilotunnus>010100-001Y</Henkilotunnus> <Syntymaaika>2000-01-01</Syntymaaika> <Sukupuoli>M</Sukupuoli>
LIITE F <Sukunimi>MEIKÄLÄINEN</Sukunimi> <Etunimet>MATTI</Etunimet> <Tietojenantokielto></Tietojenantokielto> <Toimenpide>TUNNISTA</Tunnista> <TunnuksenTila>2</TunnuksenTila> </Pyynto> Vastaussanoma: Skeema: <?xml version="1.0" encoding="utf-8"?> XML-sanomastandardi 4 <schema targetnamespace= "https://www.etk.fi/2004/11/29/tutkionkohenkilotunnistettuvastaus" xmlns="http://www.w3.org/2001/xmlschema" xmlns:perus="https://ws.tyoelake.fi/2004/11/24/perustyypit" elementformdefault="qualified"> <import namespace="https://ws.tyoelake.fi/2004/11/24/perustyypit" schemalocation="../../../../2004/11/24/perustyypit/perustyypit.xsd"/> <element name="vastaus"> "Arek käyttää Hesun tunnistusta henkilön tunnistamiseen saadakseen selville henkilön surrogaatin sekä henkilötietojen hakemiseen." <complextype> <sequence> <element name="henkilotunnus" type="henkilotunnustyyppi" > <element name="syntymaaika" type="date"> Oltava oikea kalenteripäivämäärä. <element name="sukupuoli" minoccurs="0"> <restriction base="string"> <enumeration value="m"> <enumeration value="n"> M = mies, N = nainen. <element name="sukunimi" type="string"> <restriction base="string"> <maxlength value="40"/>
XML-sanomastandardi 5 Suuraakkosin, korkeintaan 40 merkkiä. LIITE F <element name="etunimet"> <restriction base="string"> <maxlength value="40"/> Suuraakkosin, korkeintaan 40 merkkiä. <element name="surrogaatti" type="integer"> ETK:n surrogaatti. Pituus 9 merkkiä. <element name="kuolinpaiva" type="string" minoccurs="0"> <restriction base="string"> <maxlength value="10"/> Esiintyy vain, jos henkilö on kuollut. Voi olla muotoa YYYY, YYYY-MM tai YYYY-MM-DD? (Jos voi, date ei kelpaa tietotyypiksi.) <element name="kuolemanvahvistustapa" type="string" minoccurs="0"> <restriction base="string"> <maxlength value="10"/> Esiintyy vain, jos henkilö on kuollut. Ilmoitetaan koodilla: 1 = todettu 2 = julistettu 3 = vahvistamaton <element name="tietojenantokielto" type="string"> <restriction base="string"> <maxlength value="10"/> tyhjä = ei tietojenantokieltoa
XML-sanomastandardi 6 LIITE F K = otepalvelun tietojenantokielto (henkilölle ei saa lähettää työeläkeotetta), korkeintaan 1 merkki <element name="toimenpide" type="string"> Pyyntökoodi HH = HAE HT = TUNNISTA (Huom! Pyyntösanomalla vastaavaan elementtiin on määritelty tuo pitkä stringi, vastaussanomalle 2- merkkinen koodi. Miksi?!) <element name="tunnuksentila" type="string"> <restriction base="string"> <maxlength value="1"/> Ilmoitetaan koodilla: 1 = tunnus voimassa 2 = voimaanjäävä tunnus (tunnuksen korjaus tekeillä) 6 = mitätöitävä tunnus (tunnuksen korjaus tekeillä) <element name="linkitettyhenkilotunnus" type="string" minoccurs="0"> Tunnuksen korjaustilanteessa korjauksen ollessa kesken kertoo toisen tunnuksen. </sequence> </complextype> </schema> Malli Vastaus: <Vastaus> <Henkilotunnus>010100-001Y</Henkilotunnus> <Syntymaaika>2000-01-01</Syntymaaika> <Sukupuoli>M</Sukupuoli> <Sukunimi>MEIKÄLÄINEN</Sukunimi> <Etunimet>MATTI</Etunimet> <Surrogaatti>123456789</Surrogaatti> <Tietojenantokielto></Tietojenantokielto> <Toimenpide>HT</Toimenpide> <TunnuksenTila>2</TunnuksenTila> </Vastaus>