Suomi.fi-palveluväylä – Käytetyt tunnisteet

1 Johdanto

1.1 Käytetyt tunnisteet

Tässä dokumentissa kuvataan Suomi.fi-palveluväylässä käytetyt tunnisteet. X-Roadin versiossa 6 jokaisella Suomi.fi-palveluväylään liittyneelle organisaatiolle sekä sen Suomi.fi-palveluväylään liittämälle järjestelmälle ja palvelulle annetaan globaalisti uniikki tunniste. Globaalisti uniikin tunnisteen tarkoituksena on tukea X-Roadin federaatio-ominaisuutta, joka mahdollistaa useiden eri X-Road-instanssien liittämisen toisiinsa. X-Roadin sisäinen viestinvälitys ja käyttöoikeuksien hallinta perustuu organisaatioiden, järjestelmien ja palveluiden uniikkeihin tunnisteisiin sekä yksittäisen X-Road-instanssin että monesta eri instanssista muodostuvan kokonaisuuden sisällä.

1.2 Käsitteet

  • Alijärjestelmä on organisaation X-Roadiin liittämä yksittäinen tietojärjestelmä tai looginen palvelu-/järjestelmäkokonaisuus
  • Organisaatio on Suomi.fi-palveluväylään liittynyt organisaatio.
  • Palvelu on alijärjestelmän X-Roadiin julkaisema yksittäinen SOAP-palvelu.
  • Tunniste on jokaiselle palveluväylään liittyneelle organisaatiolle sekä X-Roadinpalveluväylään liittämälle järjestelmälle annettu globaalisti uniikki määrite. Organisaatiokohtaiset tunnisteet muodostuvat kolmesta, järjestelmäkohtaiset neljästä ja palvelukohtaiset kuudesta erillisestä osasta. Tunnisteet ovat hierarkkisia ja järjestelmien tunnisteet sisältävät aina ne omistavan organisaation tunnisteen. Palveluiden tunnisteet sisältävät vastaavasti aina sekä järjestelmän että organisaation tunnisteet.
  • X-Road on Virossa kehitetty ja käytössä oleva ohjelmisto, joka toimii osana kansallisen palveluväylän teknistä ydintä.

3 Tunnisteiden rakenne

Organisaatiokohtaiset tunnisteet muodostuvat kolmesta, järjestelmäkohtaiset neljästä ja palvelukohtaiset kuudesta erillisestä osasta. Tunnisteet ovat hierarkkisia ja järjestelmien tunnisteet sisältävät aina ne omistavan organisaation tunnisteen. Palveluiden tunnisteet sisältävät vastaavasti aina sekä järjestelmän että organisaation tunnisteet.

4 Organisaatioiden tunnisteet (member)

Organisaation yksilöivänä tunnuksena käytetään Y-tunnusta.

X-Roadin versiossa 6 palveluväylään liittyneiden organisaatioiden tunnisteet rakentuvat kolmesta osasta seuraavasti:

Organisaatio:[X-Road instance]/[member class]/[member code]

  • X-Road instance – X-Road-instanssin yksilöivä tunnus. Tunnuksen tulee koostua ISO-standardin mukaisesta maakoodista sekä teknisen ympäristön yksilöivästä liitteestä. Esim. FI-DEV, FI-TEST, FI. Palveluväyläoperaattori asettaa ympäristön tunnuksen keskuspalvelimen asennuksen yhteydessä.
  • Member class – Organisaation tyypin ilmaiseva yksittäisen instanssin sisällä uniikki tunnus. Esim. julkishallinnon organisaatio (GOV), yksityinen yritys (COM), säätiö (ORG) jne. Käytettävät tyypit määritellään instanssin keskuspalvelimella palveluväyläoperaattorin toimesta.
  • Member code – Yksittäisen organisaation yksilöivä tunnus, jonka on oltava uniikki vähintään valitun organisaatiotyypin sisällä. Selkeyden vuoksi on kuitenkin parempi, että käytettävät tunnukset ovat uniikkeja koko instanssin tasolla. Organisaation yksilöivänä tunnuksena käytetään Y-tunnusta.

Esimerkiksi: alla nähtävä tunniste yksilöi FI-DEV-instanssiin kuuluvan yksityisen yrityksen, jonka Y-tunnus on 12345.

Organisaatio: FI-DEV/COM/12345

5 Alijärjestelmien tunnisteet (subsystem)

Palveluväylän kautta tietoja käyttävällä järjestelmällä (consumer) tulee aina olla subsystem-tason tunniste.

Alijärjestelmällä tarkoitetaan organisaation X-Roadiin liittämää yksittäistä tietojärjestelmää tai loogista palvelu-/järjestelmäkokonaisuutta. Alijärjestelmän tunniste koostuu sen omistavan organisaation tunnisteesta ja alijärjestelmän sen omistaman organisaation tasolla yksilöivästä tunnuksesta. Alijärjestelmille annettavat tunnukset ovat organisaatioiden itsensä päätettävissä. Suosituksena kuitenkin on CamelCase-tyyppisen nimeämiskäytännön käyttö alijärjestelmien nimissä. Käytännössä tämä tarkoittaa useista eri sanoista muodostuvien alijärjestelmien nimien kirjoittamista siten, että sanat on kirjoitettu yhteen isoin alkukirjaimin. Esim. TestSystem.

Alijärjestelmä: [subsystem owner]/[subsystem code].

Esimerkiksi: alla nähtävä tunniste yksilöi HighSecurity nimisen alijärjestelmän, joka kuuluu edellisessä esimerkissä esitetylle organisaatiolle (Organisaatio: FI-DEV/COM/12345).

Alijärjestelmä: FI-DEV/COM/12345/HighSecurity

6 Palveluiden tunnisteet (service)

Suomi.fi-palveluväylän kautta tietoja tarjoavalla palvelulla (provider) tulee aina olla alijärjestelmän sisältävä service-tason tunniste

Palvelulla tarkoitetaan alijärjestelmän X-Roadiin julkaisemaa yksittäistä SOAP-palvelua. Palvelun tunniste koostuu sen julkaisseen alijärjestelmän tunnisteesta sekä palvelun yksilöivästä tunnuksesta sekä palvelun versionumerosta.

Versionumeron käyttö on pakollista ja sitä käytetään erottamaan palvelun eri versiot toisistaan. Palvelun tunnuksen on oltava uniikki sen julkaisseen alijärjestelmän tasolla. Palvelun tunnus on vapaasti julkaisijan itsensä päätettävissä ja niiden määrittely tapahtuu liitettyjen palveluiden rajapintakuvaukset sisältävissä WSDL-kuvauksissa. Versionumero muodostuu v-kirjaimesta ja versionumeron ilmaisevasta kokonaisluvusta.

Palvelu: [service provider]/[service code]/[version]

Esimerkiksi: alla nähtävä tunniste yksilöi getSecureData-palvelun version v1, joka kuuluu edellisessä esimerkissä esitetylle alijärjestelmälle (Alijärjestelmä: FI-DEV/COM/12345/HighSecurity)

Palvelu: FI-DEV/COM/12345/HighSecurity/getSecureData/v1

7 Tunnisteiden käyttö

Kaikki Suomi.fi-palveluväylään liitettävät tietoa tarjoavat palvelut (provider) sekä tietoa käyttävät järjestelmät (consumer) tulee liittää Suomi.fi-palveluväylään alijärjestelmien kautta. Palvelujen liittäminen suoraan organisaatioiden alle tai palvelujen kutsuminen organisaationa on teknisesti mahdollista, mutta alijärjestelmien käyttö mahdollistaa käyttöoikeuksien hienojakoisemman määrittelyn. Lisäksi alijärjestelmien käytöllä varmistetaan mahdollisimman yhtenäinen rakenne Suomi.fi-palveluväylään liitettyjen järjestelmien ja palveluiden tunnisteissa.

Suomi.fi-palveluväylän kautta tietoja käyttävällä järjestelmällä tulee aina olla subsystem-tason tunniste ja tietoja tarjoavalla palvelulla alijärjestelmän sisältävä service-tason tunniste. Liityntäpalvelimen omistajaksi merkitylle organisaatiolle riittää sen sijaan member-tason tunniste, mikäli organisaatio ei käytä tai tarjoa tietoja Suomi.fi-palveluväylään. Suomi.fi-palveluväylään liittymisen yhteydessä kaikki organisaatiot saavat ensin member-tason tunnisteen, jonka jälkeen uusien alijärjestelmien ja palveluiden lisääminen ja niiden edellyttämien tunnisteiden luominen on mahdollista.

Alla muutamia esimerkkejä.

Member-taso:

[X-Road instance]/[member class]/[member code]

Subsystem-taso:

[X-Road instance]/[member class]/[member code]/[subsystem code]

Service-taso:

[X-Road instance]/[member class]/[member code]/[subsystem code]/[service code]/[version]

VersioMitä tehty / muutettuPvm/
henkilö
1.0Dokumentti julkaistu eSuomessa15.09.15 / NP

Yksilöintitunnus: JPVT91