Työeläkejärjestelmän XML-ohjeisto

Versio 2005-09-18

Viimeisin versio löytyy osoitteesta http://ws.tyoelake.fi/ohjeisto/.

Johdanto

Tämä ohjeisto määrittelee, miten XML-teknologioita hyödynnetään eläkevakuuttajien, Arekin ja Eläketurvakeskuksen järjestelmien välisissä yhteyksissä. Ohjeiston ensisijaisena tavoitteena on paras mahdollinen yhteensopivuus eri tietojärjestelmien välillä. Muita tavoitteita ovat tietojen vaihdon hyvä suorituskyky ja implementoinnin helppous.

Työeläkejärjestelmässä ei olla kuvattu kattavaa joukkoa yhteisiä ydintyyppejä, joissa määriteltäisiin esimerkiksi henkilön tai vakuutuksen kaikki ominaisuudet ja tietojen rakenne XML-sanomilla. Lähtökohtana on ollut, että kukin palvelu määrittelee omille kutsu- ja vastaussanomilleen tarvitsemansa tiedot.

XML-rajapintojen ei ole tarkoitus kuvata esim. sanomilla sallittuja arvoja tai niiden muotoja mahdollisimman tarkasti. XML-sanomilla pyritään käyttämään yksinkertaisia perustyyppejä ja tietojen oikeellisuustarkistukset tehdään sovelluslogiikassa.

Tässä ohjeistossa esitetään XML:n käyttöön liittyviä vaatimuksia, suosituksia ja vinkkejä.

Esimerkki vaatimuksesta:

Palveluille ja niihin liittyville skeemoille tulee määritellä nimiavaruudet.

Esimerkki suosituksesta:

Elementtien nimien tulisi olla korkeintaan 32 merkin pituisia.

Esimerkki vinkistä:

Yhteensopivuuden varmistamiseksi ja virheiden ehkäisemiseksi XML-sanoman muodostava osapuoli voi validoida muodostamansa sanoman.

Standardit

Työeläkejärjestelmän XML-ohjeisto pohjautuu pääosin W3C:n suosituksiin. XML-toteutusten on oltava yhteensopivia alla mainittujen suositusten kanssa.

Seuraavista Oasiksen ja WS-I:n standardeista hyödynnetään osia, jotka määritellään tässä dokumentissa.

Lisäksi on hyvä tuntea seuraavat standardit:

WSDL-kuvausten ja SOAP-sanomien rakenne

WSDL-kuvausten rakenne

Yhdessä WSDL-kuvauksessa tulisi kuvata yksi palvelu. Palvelu koostuu tyypillisesti yhden kutsu- ja yhden vastaussanoman muodostamasta operaatiosta, mutta operaatioita voi myös olla useita. Jokaisen sanoman rakenne kannattaa kuvata omassa skeemassaan. Nämä erilliset skeemat liitetään WSDL-kuvaukseen XML Schema -suosituksen import-elementin avulla.

WSDL-kuvauksia ei ainakaan toistaiseksi julkaista UUDI-palvelussa vaan jokainen organisaatio julkaisee rajapintakuvaukset valitsemallaan tavalla. Kaikille palveluille yhteiset skeemat julkaistaan sivustolla ws.tyoelake.fi.

Esimerkki WSDL-palvelukuvauksesta

SOAP-sanomien rakenne

SOAP-sanomat muodostuvat SOAP-standardin mukaisesta Header- ja Body-osasta. Työeläkejärjestelmän XML-sanomilla Body-osaan sijoitetaan kaikille yhteinen vakio-osa, vastaussanomille mahdollisia poikkeustietoja sekä sanomakohtainen liiketoimintaosa. Vakio-osan ja poikkeustietojen rakenne on määritelty yleisissä skeemoissa ja ne on esitelty tämän ohjeiston kappaleessa Yleiset tyypit.

Elementtien ja attribuuttien nimeäminen

Elementtien ja attribuuttien nimien tulee perustusa suomen kieleen. Ä- ja ö-kirjaimista jätetään pisteet pois. Välilyönnit ja yhdysviivat jätetään nimistä pois, nimissä ei käytetä alaviivoja. Elementtien nimissä käytetään ns. UpperCamelCase-kirjoitustapaa (kaikki sanat alkavat isolla alkukirjaimella) ja attribuuttien nimissä lowerCamelCase-tapaa (ensimmäinen sana alkaa pienellä kirjaimella, muut sanat isoilla).

Elementtien nimien tulisi olla kuvaavia ja ymmärrettäviä. Lyhenteitä tulisi välttää, lukuunottamatta vakiintuneita, kaikille tuttuja lyhenteitä kuten esimerkiksi Pvm. Elementtien nimien tulisi olla korkeintaan 32 merkin pituisia.

Attribuuttien ja elementtien arvojen, jotka muodostavat sanoman sisällön, ei tarvitse noudattaa näitä nimeämissääntöjä.

Palveluun kuuluvan operaation kutsu- ja vastaussanomien SOAP Body -osaan sijoitettavien juurielementtien tulisi kuvata kyseisen operaation toiminta mahdollisimman selväkielisesti. Kutsusanomaan liitetään lisäksi sana Pyynto ja vastaussanomaan Vastaus. Esimerkiksi palvelu HaeHenkilonAnsaintatiedot sisältää yhden operaation, jonka kutsusanoma on HaeHenkilonAnsaintatiedotPyynto ja vastaussanoma HaeHenkilonAnsaintatiedotVastaus. Lisäksi kummallekin sanomalle voidaan liittää palvelutunnus-attribuutti, joka voi sisältää lyhyemmän, operaation yksilöivän koodin.

Esimerkkitiedostossa EsimerkkipalveluVastaus.xsd on esimerkki vastaussanoman skeemasta, jossa juurielementti sisältää vakio-osan, poikkeustiedot ja liiketoimintaosan. Juurielementille on määritelty palvelutunnus-attribuutti. Elementille EsimerkkipalveluVastaus on määritelty oma tyyppi EsimerkkipalveluVastausTyyppi, koska kaikki ohjelmistot eivät hallitse elementin sisällä määriteltyjä anonyymejä complexType-määrityksiä. Vastaussanoman liiketoimintaosa on määritelty erillisessä skeemassa Vastaus.xsd. Skeemalle on määritelty ominaisuus elementFormDefault="qualified", eli skeeman mukaisissa XML-sanomissa elementtien on esiinnyttävä nimiavaruuksien kanssa.

Yleiset tyypit

Perustyypit

Työeläkejärjestelmän XML-sanomille on määritelty vain muutamia, koko järjestelmälle yhteisiä perustyyppejä. Ne on määritelty omassa skeemassaan Perustyypit.xsd. Näitä tyyppejä tulisi käyttää skeemoissa omien tyyppien tai XML Schema -tyyppien sijaan perustyyppien mukaisten tietojen tyyppeinä. Yhteiset tyypit ovat:

ElakejarjestelynumeroTyyppi
Eläkejärjestelynumeron muodon määrittävä tyyppi, jonka rajoite on määritelty säännöllisellä lausekkeella (regular expression). Tyypin mukainen eläkejärjestelynumero on periaatteessa muodoltaan oikea, mutta esimerkiksi tarkistusmerkin oikeellisuutta ei lasketa.
ElakevakuuttajaTyyppi
Eläketurvakeskuksen ylläpitämien eläkevakuuttajanumeroiden (laitosnumeroiden) muodon määrittävä tyypi. Vaikka eläkevakuuttajanumerot koostuvat käytännössä 2 tai 5 numerosta, niitä on perinteisesti välitetty 5-merkkisinä merkkijonoina, mistä syystä niiden tyyppinä XML-sanomilla on 2 - 5-merkkinen merkkijono.
HenkilotunnusTyyppi
Suomalaisen henkilötunnuksen muodon määrittävä tyyppi, jonka rajoite on määritelty säännöllisellä lausekkeella. Tyypin mukainen henkilötunnus on periaatteessa muodoltaan oikea, mutta esimerkiksi tarkistusmerkin oikeellisuutta ei lasketa.
SukupuoliTyyppi
Arvojoukko eli enumeraatio, jonka arvona voi olla joko M tai N. (M = mies, N = nainen.)
YTunnusTyyppi
Suomalaisen yritystunnuksen muodon määrittävä tyyppi, jonka rajoite on määritelty säännöllisellä lausekkeella. Tyypin mukainen Y-tunnus on periaatteessa muodoltaan oikea, mutta esimerkiksi tarkistusmerkin oikeellisuutta ei lasketa.

Vakio-osa

Kaikille työeläkejärjestelmän XML-sanomille liitettävän vakio-osan rakenne on määritelty omassa skeemassaan VakioOsa.xsd. Vakio-osan tietoja käytetään sanomilla seuraavasti:

Aikaleima
Aikaleima-elementin arvon tulee olla XML-sanoman muodostamisajankohta. Pyyntö- ja vastaussanomalla tulee olla omat aikaleimansa. Aikaleimaa käytetään lähinnä ongelmien selvittelyyn, mutta sitä voidaan hyödyntää myös tietojenantokirjauksissa tai esimerkiksi silloin, kun halutaan varmistaa sanomien käsittelyn tapahtuvan tietyssä järjestyksessä. Aikaleima on xs:dateTime-tyyppinen ja se tulisi asettaa mahdollisimman tarkasti - mielellään millisekunnin tarkkuudella.
LahettavaElakevakuuttaja
Kutsusanoman lähettävän eläkevakuuttajan eläkevakuuttajanumero (laitosnumero). Tätä tietoa voidaan hyödyntää esimerkiksi
LahettajanHoitavaToimija
Lähettävän eläkevakuuttajan hoitavan toimijan eläkevakuuttajanumero (laitosnumero). Tämä tieto esiintyy vakio-osalla, jos lähettävä eläkevakuuttaja ei ole itse muodostanut XML-sanomaa vaan joku toinen eläkevakuuttaja hoitaa lähettävän eläkevakuuttajan asioita. Eläketurvakeskuksen YELA-järjestelmästä voidaan tarkistaa, onko lähettävän eläkevakuuttajan ja lähettäjän hoitavan toimijan välillä voimassa oleva hoitosuhde. Lähettäjän hoitava toimija ei tarkoita järjestelmien teknisestä ylläpidosta tai kehityksestä vastaavaa ohjelmistotaloa tai palvelukeskusta.
LahettajanOhjelma
Tietoa kutsusanoman lähettäjän ohjelmasta käytetään lähinnä ongelmatilanteiden selvittelyssä. Tieto on korkeintaan 40 merkin mittainen ja se voi olla ohjelman tekninen koodi tai selväkielinen, ohjelman käyttötarkoitusta kuvaava nimi.
LahettajanKayttajatunnus
Tietoa kutsusanoman lähettäjän käyttäjätunnuksesta käytetään lähinnä ongelmatilanteiden selvittelyssä, mutta se voi toimia myös suuntaa-antavana vihjeenä käyttäjän henkilöllisyydestä tietojenantokirjauksissa. Työeläkejärjestelmän yhteistä käyttövaltuushallintaa hyödyntävät järjestelmät (www-käyttöliittymät) voivat laittaa tähän käyttäjän KVH-uid:n. Keskuskonejärjestelmistä syntyville kutsusanomille voidaan laittaa käyttäjän RACF-tunnus. Eräajoissa voidaan käyttää eräohjelman nimeä (sama kuin LahettajanOhjelma) tai jotakin eräohjelman suoritukseen liittyvää tarkentavaa tietoa. Käyttäjätunnus on korkeintaan 64 merkin pituinen.
LahettajanViite
Lähettäjän tulee antaa jokaiselle lähettämälleen kutsusanomalle sanoman yksilöivä tunniste, lähettäjän viite. Elementtien LahettavaElakevakuuttaja ja LahettajanViite tulee olla uniikki yhdistelmä. Lähettäjän viitteeseen kannattaa varmuuden ja selkeyden vuoksi laittaa tieto, josta lähettäjä voidaan tunnistaa. (Esimerkiksi Arekin viitteet alkavat aina A-kirjaimella.) Viite on korkeintaan 30 merkin mittainen.
VastaanottavaElakevakuuttaja
Kutsusanoman vastaanottavan eläkevakuuttajan eläkevakuuttajanumero (laitosnumero). Tätä tietoa voidaan käyttää esimerkiksi organisaation sisäisessä reitityksessä kertomaan, mille eläkevakuuttajalle kutsusanoma tulee toimittaa tai pääteltäessä, miltä eläkevakuuttajalta vastaussanoma on peräisin. (Organisaatioiden välisessä tietoliikenteessä ei ainakaan toistaiseksi ole mitään sanoman sisältöön perustuvaa reititystä vaan kukin palvelun käyttäjä kutsuu itse suoraan palvelun tarjoajan palvelua.)
VastaanottajanHoitavaToimija
Vastaanottavan eläkevakuuttajan hoitavan toimijan eläkevakuuttajanumero (laitosnumero). Jätetään pois sanomalta, jos arvoa ei ole. Tietoa voidaan hyödyntää sisäisessä reitityksessä samaan tapaan kuin vastaanottavaa eläkevakuuttajaa.
VastaanottajanViite
Tieto on vakio-osalla pakollinen, eli sen on esiinnyttävä sekä kutsu- että vastaussanomilla. Kutsusanomilla sen sisällön tulisi kuitenkin olla tyhjä merkkijono. Palvelun ei tarvitse käsitellä kutsusanomalle asetettua vastaanottajan viitettä millään tavalla. Vastaussanomalle tulee asettaa tunniste, joka yksilöi sanoman yhdessä elementin VastaanottavaElakevakuuttaja sisällön kanssa. Viite on korkeintaan 30 merkin mittainen.

Huomaa! Vastaussanomalla esiintyvä LahettavaElakevakuuttaja on kutsusanoman lähettäjä eli vastaussanoman vastaanottaja. Sama koskee elementtejä LahettajanHoitavaToimija, LahettajanOhjelma, LahettajanKayttajatunnus, LahettajanViite, VastaanottavaElakevakuuttaja ja VastaanottajanHoitavaToimija, eli näiden arvot ovat aina vastaussanomalla samat kuin pyynnöllä. Sen sijaan elementtien Aikaleima ja VastaanottajanViite tulisi saada vastaussanomalla eri arvot kuin pyynnöllä.

Poikkeustiedot

XML-vastaussanomalla voi vakio-osan ja liiketoimintaosan lisäksi esiintyä poikkeustietoja. Poikkeustietojen palvelu voi palauttaa virhe- ja huomautustietoja odottamattomista tilanteista. Poikkeustietoelementin rakenne on määritelty omassa skeemassaan Poikkeustiedot.xsd. Kyseisessä skeemassa määrittellään elementti Poikkeustiedot, joka tulee asettaa vastaussanomalle valinnaiseksi elementiksi (ks. EsimerkkipalveluVastaus.xsd). Poikkeustiedot-elementti voi sisältää useita Poikkeus-elementtejä, joista jokainen sisältää seuraavat tiedot:

Taso
Tasolla on 3 sallittua arvoa. Sallitut arvot ja niiden merkitykset ovat:
Virhe Kutsuttua palvelua ei pystytty suorittamaan
Varoitus Palvelu suoritettiin, mutta tulokseen sisältyy varoituksia, joihin liittyvät ongelmat ovat palvelun kutsujan vastuulla
Huomautus Palvelu suoritettiin, mutta tulokseen sisältyy huomautuksia, joihin liittyvät ongelmat ovat palvelun tarjoajan vastuulla
Koodi
Palvelun palauttama virhe-, varoitus- tai huomautuskoodi. Palvelun tarjoaja voi määritellä palvelujensa koodit vapaasti, kunhan ne ovat korkeintaan 20 merkin mittaisia. Koodien merkitykset tulee dokumentoida samalla tavoin kuin esimerkiksi palvelun syöte- ja vastaustiedoissa välitettävien koodien sallitut arvot.
Selite
Selite voi sisältää tarkentavaa tietoa virheestä. Selitteen ei ole tarkoitus olla virhekoodin kuvaus (esim. Virheellinen henkilötunnus) vaan sen tulisi antaa tapauskohtaista lisätietoa (Henkilötunnuksen 010101-010X tarkistusmerkki X on väärä. Pitäisi olla 1).
Kohde
Mikäli poikkeukseen liittyvällä elementillä on elementin yksilöivä id-attribuutti, se voidaan kertoa poikkeuksen Kohde-elementissä. Tämä auttaa poikkeustiedon tulkitsijaa paikantamaan poikkeuksen syyn.

Omien tyyppien käyttö

XML Schema -suositus määrittelee laajan joukon perustyyppejä (string, int, boolean jne.), joita XML-skeemoissa voi hyödyntää. Työeläkejärjestelmän XML-sanomia varten on kehitetty muutamia perustyyppejä. Näiden lisäksi kukin palvelun tarjoaja voi määritellä uusia tyyppejä omia palvelujaan varten. Omat tyypit voivat olla organisaatio-, palvelu- tai sanomakohtaisia. Tyyppien nimien tulee päättyä sanaan Tyyppi. [esimerkkejä]

Skeeman tulisi kuvata tiedon rakenne, mutta ei liiketoimintalogiikan tarkistuksia. Merkkijonotyyppisten elementtien suurimmat sallitut arvot kannattaa merkitä määrittelemällä oma simpleType, joka lisää string-perustyypille maxLength-rajoitteen (restriction). Omia tyyppejä ei kannata käyttää tietyn tiedon sallittujen arvojen määrittelyyn. Arvojoukot kuvataan erillisessä dokumentaatiossa ja niiden oikeellisuus tarkistetaan sovelluslogiikassa. Näin esimerkiksi uuden arvon lisääminen sallittujen arvojen joukkoon ei edellytä skeeman muuttamista ja kaikkien sen perusteella generoitujen ohjelmakomponenttien päivitystä.

Koska sanomien kutsu- ja vastauselementeillä on omat rakenteensa, niillä on omat tyyppinsä. Elementin tyyppi voidaan määritellä elementtimäärityksen sisällä ns. anonyymina complexTypenä, mutta kaikki ympäristöt eivät tue näitä täysin. Parempaan yhteensopivuuteen päästään määrittelemällä nimetyt tyypit ja viittaamalla elementtimäärityksissä niihin.

Useilla sanomilla tai useissa palveluissa uudelleen käytettäväksi tarkoitetuista ydintyypeistä voi muodostaa omia ydintyyppikirjastojaan. Tällöin kannattaa kuitenkin pidättäytyä tyypeissä, joita käytetään kaikilla sanomilla täsmälleen samanlaisina. Tyyppejä muodostettaessa kannattaa välttää syviä rakenteita, koska syvät hierarkiat heikentävät ohjelmistojen suorituskykyä sanomaa muodostettaessa ja luettaessa.

XML Schema -perustyypeistä choice on toistaiseksi heikosti tuettu ja yhteensopivuuden vuoksi on suotavaa määritellä sen sijaan sequence, joka sisältää kaikki vaihtoehdot valinnaisina elementteinä (minOccurs="0"). Tällöin palvelun liiketoimintalogiikan on tarkistettava, että sanomalla elementeistä esiintyy täsmälleen yksi.

Rahamäärät

Rahamäärät ilmoitetaan työeläkejärjestelmän XML-sanomilla sentteinä. Rahamäärän ilmaisemiseen soveltuvat XML Schema -perustyypit int ja long. Skeemaan kannattaa erikseen laittaa huomautus siitä, että tiedon yksikkö on sentti eikä euro.

Päiväykset ja kellonajat

Päiväykset kannattaa määritellä XML Schema -perustyypillä date ja kellonajan sisältävät tiedot tyypillä dateTime. XML-sanomilla tiedot esitetään aikavyöhyketiedon kanssa.

Versiointi

Palveluille ja niihin liittyville skeemoille tulee määritellä nimiavaruudet. Nimiavaruudet ovat HTTP-osoitteita ja niissä tulee esiintyä palvelua tarjoavan organisaation tunniste, päivämäärä muodossa VVVV/KK/PV sekä palvelun tai skeeman nimi. Päivämäärä voi olla esimerkiksi skeeman luontiajankohta, palvelun suunniteltu tuotantoonsiirtopäivä tai skeemaan muutoksen aiheuttaneen lakimuutoksen päivä. Tärkeintä on, että samalla organisaatiolla voi olla samasta palvelusta useita eri versioita, joilla jokaisella on oma nimiavaruutensa.

Nimiavaruuksiin perustuvan versioinnin lisäksi pieniä muutoksia, jotka eivät riko rajapinnan taaksepäin yhteensopivuutta voidaan ilmaista asettamalla palvelun juurielementille string-tyyppinen attribuutti sanomaversio, joka voi olla muotoa X.y. Tämän attribuutin avulla palvelua kutsuva asiakasohjelma voi kertoa, mitä sanomaversiota se käyttää.

Tietoturva

Työeläkejärjestelmän XML-sanomilla noudatetaan WS Security -standardin mukaisia allekirjoituksia tietojen muuttumattomuuden ja lähettäjän varmentamiseksi. Tietoja ei kryptata. Toistaiseksi allekirjoituksiin käytetään UsernameToken-profiilin mukaista tunnusta ja salasanaa, mutta jatkossa on tarkoitus siirtyä X.509 Certificate Token -profiilin käyttöön.

SOAP-sanomien välitys

Merkistö ja pakkaus

SOAP-sanomilla sisällön merkistöpakkauksena tulee käyttää UTF-8:aa. Kaikkien XML-jäsentimien tulee osata käsitellä UTF-8:aa ja UTF-16:tta. UTF-16:lle ei ole tarvetta työeläkejärjestelmän XML-sanomilla ja työkalujen tuki UTF-8:lle on huomattavasti parempi.

Aikavyöhyketieto

XML Schema -tyyppien date ja dateTime sekä näistä johdettujen tyyppien mukaiset tiedot on välitettävä sanomilla aikavyöhyketiedon kanssa.

Suositeltava tapa liittää kellonaikaan aikavyöhyketieto on muuntaa tieto UTC-aikaan ja merkitä aikavyöhykkeeksi Z.

Oman ympäristön aikavyöhykkeen käsittelyä voi testata esimerkkitiedostolla aikaleimatesti.xml. (Testin suorittamiseen tarvitaan myös skeema aikaleimatesti.xsd.)

Tyhjän tiedon välittäminen

Mikäli elementin esiintyminen sanomalla on skeeman mukaan valinnaista (minOccurs="0") ja elementillä ei ole arvoa, koko elementti alku- ja lopputageineen tulisi jättää pois sanomalta.

Validointi

Yhteensopivuuden varmistamiseksi ja virheiden ehkäisemiseksi XML-sanoman muodostava osapuoli voi validoida muodostamansa sanoman. Myös vastaanottava osapuoli voi validoida sanomat. Testiympäristöissä validointi on suotavaa tehdä kummassakin päässä, mutta suorituskykysyistä tuotantoympäristössä validointi voidaan kytkeä pois päältä.

Esimerkki

Esimerkki SOAP-kutsusta

Eräkäsittely

Palveluntarjoaja voi tarjota palvelulleen myös eräkäsittelyrajapintaa. Eräkäsittelyssä useita kutsusanomia yhdistetään peräkkäin yhden SOAP Envelope -kirjekuoren Body-osaan. Erätiedostot välitetään FTP:llä.

Jokaisella kutsusanomalla on oma vakio-osansa. Lisäksi koko erälle voidaan asettaa yhteiset erän tiedot. Tässä ohjeistossa ei määritellä koko erää koskevien yhteisten tietojen rakennetta tai sisältöä vaan kukin palveluntarjoaja päättää ne itse.

Esimerkki

[Esimerkki erätiedostosta]

Tämän ohjeiston muutokset

Tämä ohjeisto korvaa edellinen XML-ohjeiston, joka on edelleen luettavissa osoitteessa ws.tyoelake.fi/2005/01/10/tel-xml.pdf. Tämä versio on kirjoitettu kokonaan uudelleen alusta alkaen.

Muutokset versiosta 10.1.2005 versioon 18.9.2005

Muutokset 18.9.2005 jälkeen

Jatkossa muutokset merkitään seuraavaan taulukkoon.

PäivämääräMitä muutettu
18.9.2005Ensimmäinen uuden mallin mukainen versio