Ota Suomi.fi-palveluväylän kautta tarjottava palvelu käyttöön

Tässä ohjeessa kerrotaan, miten Suomi.fi-palveluväylästä löytyvä ja Liityntäkatalogissa esitelty palvelu otetaan käyttöön. Sovi palvelun käyttöönotosta aina erikseen palveluntarjoajan kanssa ja huolehdi sopimuksista ja luvista, joita palvelun käyttöönotto vaatii.

Ennakkovaatimukset:
Organisaatiosi tulee olla liittynyt Palveluväylään ja organisaatiollasi tulee olla toimiva alijärjestelmä, ennen yksittäisen palvelun käyttöluvan hakemista. Huolehdi siis, että liityntäpalvelimellesi on lisätty vähintään yksi alijärjestelmä.

Lue ohjeet alijärjestelmän lisäämiseen.

Voit lisäksi tarkistaa alijärjestelmän olemassa olon Liityntäkatalogista Avautuu uuteen ikkunaan.oman organisaatiosi kohdalta.

LiityntäkatalogiAvautuu uuteen ikkunaan. esittelee Palveluväylään liitetyt alijärjestelmät. Etsi palveluita Liityntäkatalogista -sivu neuvoo, miten voit etsiä palveluita Liityntäkatalogista.

Kun haluat ottaa Liityntäkatalogista löytämäsi palvelun käyttöön, etene seuraavasti:

1. Liitä organisaatiosi Suomi.fi-palveluväylään - jos se ei siellä vielä ole
2. Tutustu palveluun, sen käyttöehtoihin ja teknisiin tietoihin Liityntäkatalogissa
3. Hae palvelun käyttölupaa
4. Yhdistä organisaatiosi ja palveluntarjoajan tietojärjestelmät

1. Liitä organisaatiosi Suomi.fi-palveluväylään

Jos organisaatiosi aikoo hyödyntää Palveluväylän kautta tarjottavia palveluita, täytyy sen olla Palveluväylän tuotantoympäristössä. Palveluväylään liittyminen on ohjeistettu kokonaisuudessaan Palveluväylän käyttöönotto -sivuilla. Liityntäprosessiin on hyvä varata noin 1–3 kuukautta.

Liityntäprosessiin kuuluu:

• Liityntäprosessin ja palveluiden ylläpidon suunnittelu
• Liityntäpalvelinratkaisun käyttöönotto sekä käyttöluvan hakeminen
• Testiympäristöön liittyminen
• Toimivuuden testaaminen testiympäristössä
• Tuotantoympäristöön siirtyminen

Suosittelemme, että testaatte alijärjestelmienne yhteensopivuutta palveluntarjoajan kanssa jo testiympäristöön liittymisen yhteydessä. Näin varmistutte siitä, että viestit kulkevat organisaatiosi ja palveluntarjoajan palvelun välillä ongelmitta. Lisäohjeita testaamiseen löydät tästä artikkelista.

2. Tutustu palveluun, sen käyttöehtoihin ja teknisiin tietoihin Liityntäkatalogissa

Palvelua tarjoava organisaatio kertoo palvelustaan alijärjestelmän kuvauksessaan. Katso esimerkiksi Digi- ja väestötietoviraston VTJ-rajapinnan kuvausAvautuu uuteen ikkunaan..

Jos alijärjestelmän kuvauksesta puuttuu jotain tarvitsemiasi tietoja, pyydä puuttuvia tietoja palveluntarjoajalta.

Varmista, että käyttöönotto on mahdollista

Varmista, että palvelun käyttöönotto on organisaatiosi kohdalla mahdollista

• käyttöehtojen puolesta ja
• teknisestä näkökulmasta.

Käyttöehdot

Palveluiden käyttöönottoon ja käyttöön saattaa liittyä rajoituksia, lupahakemuksia ja maksuja. Palvelukohtaiset käyttöehdot löydät Liityntäkatalogista löytyvistä alijärjestelmän kuvauksista.

Tekniset tiedot

Palvelun tarkemmat rajapintatiedot löydät alijärjestelmän liitetiedostoista. Jos palvelu pohjautuu SOAP-protokollaan, palvelun tiedot esitetään WSDL-tiedostona. REST-malliin pohjautuvissa palveluissa tiedosto on useimmiten JSON-muotoinen. Palveluntarjoaja on voinut myös lisätä Liitetiedostot-kohtaan muita palveluun liittyviä teknisiä dokumentteja, jotka voivat olla esimerkiksi PDF-tiedostoja.

Liityntäkatalogissa esitellään sekä SOAP-protokollaan (Simple Object Access Protocol) että REST-malliin (Representational State Transfer) pohjautuvia palveluita. Se, onko palvelu SOAP- vai REST-pohjainen, vaikuttaa siihen, millaisia teknisiä ratkaisuja palvelun käyttöönottoon liittyy. Esimerkiksi niin sanottua sovitinpalvelua ei tarvita REST-rajapintojen kanssa. REST on yleisesti ottaen SOAPia kevyempi ratkaisu, koska se on kevyemmin standardisoitu.

3. Hae palvelun käyttölupaa

Palveluiden käyttö saattaa edellyttää käyttöluvan hakemista. Riippuen käyttöönotettavasta palvelusta, käyttölupaa voi hakea joko Liityntäkatalogissa tai ottamalla yhteyttä palveluntarjoajaan.

Hae käyttölupaa Liityntäkatalogissa

Liityntäkatalogissa voi hakea käyttölupaa alijärjestelmän ja palveluiden käyttöön, jos palveluntarjoaja on ottanut toiminnon käyttöönsä. Käyttölupaa voit hakea myös välitoimijana toisen organisaation puolesta. Kun palveluntarjoaja on ottanut toiminnon käyttöönsä, Liityntäkatalogissa näkyy sisäänkirjautuneille käyttäjille alijärjestelmän sivulla erillinen osio Pyydä lupaa tämän alijärjestelmän käyttöön. Lisätietoja palvelun käyttöluvan hakemisesta Liityntäkatalogissa.

Ota yhteyttä palveluntarjoajaan

Kun löydät Liityntäkatalogista palvelun, jonka haluaisit ottaa käyttöön, ota yhteyttä palvelua tarjoavaan organisaatioon.

Palveluntarjoajan yhteystiedot löydät Liityntäkatalogista alijärjestelmän tiedoista. Jos yhteystietoja ei löydy, voit pyytää apua Liityntäkatalogin ylläpidolta: palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan..

4. Yhdistä organisaatiosi ja palveluntarjoajan tietojärjestelmät

Organisaatiosi tietojärjestelmä liitetään Palveluväylään liityntäpalvelimen ja alijärjestelmän kautta

Huomioi, että kun palvelun hyödyntäjän (sinun) ja palveluntarjoajan tietojärjestelmiä aletaan yhdistää, täytyy sinun asiakasjärjestelmäsi olla jo liitettynä Palveluväylään.

Organisaatiosi asiakasjärjestelmä, eli tietojärjestelmä, johon aiot tuoda tietoja Palveluväylän muista palveluista, liitetään Palveluväylään liityntäpalvelimen kautta. Alijärjestelmä taas toimii liityntäpalvelimen ja asiakasjärjestelmän välisenä rajapintana. Tiedon hakeminen asiakasjärjestelmääsi Palveluväylään liitetystä toisesta tietojärjestelmästä tapahtuu siis organisaatioiden alijärjestelmien välillä.

Käytännössä liityntäpalvelimen käyttöön ottaminen ja alijärjestelmän lisääminen tapahtuvat osana Palveluväylään liittymistä.

Lue ohjeet liityntäpalvelimen käyttöönotosta ja alijärjestelmän lisäämisestä:

• Liityntäpalvelimen tekniset vaatimukset
• Liityntäpalvelinohjelmiston asennusohjeet RHEL 7 -liityntäpalvelimille
• Liityntäpalvelinohjelmiston asennusohjeet Ubuntu-liityntäpalvelimille
• Liityntäpalvelimen liittäminen testi- tai tuotantoympäristöön
• Uuden alijärjestelmän liittäminen liityntäpalvelimeen ja sen poistaminen

Testaa tietojärjestelmien yhdistämistä ensin testiympäristössä

Ennen kuin yhdistätte tietojärjestelmänne Palveluväylän tuotantoympäristössä, teidän täytyy testata yhdistämistä testiympäristössä. Sovi testauksesta palvelua tarjoavan organisaation kanssa.

Kirjaa testauksen aikana havaitut virheet ylös ja korjaa ne ennen tuotantoympäristöön siirtymistä. Kun kaikki toimii ongelmitta testiympäristössä, voitte aloittaa tietojärjestelmien yhdistämisen tuotantoympäristössä.

Lue ohjeet testiympäristöstä ja testaamisesta:

• Palveluväylän ja Liityntäkatalogin ympäristöt
• Palveluväylän testipalvelut

Tietojärjestelmien yhdistämisessä huomioitavaa

Kun aloitatte tietojärjestelmienne yhdistämisen, palveluntarjoaja tarvitsee sinulta ainakin:

• alijärjestelmäsi tunnistetiedot palvelun luvittamista varten (alijärjestelmän nimi = X-Road subsystem code)
• liityntäpalvelimesi IP-osoitteen tarvittavia porttiaukaisuja (5500 ja 5577) varten.

Organisaatiosi tarvitsee tiedon palveluntarjoajan liityntäpalvelimen IP-osoitteesta, jotta voitte tehdä samat porttiavaukset.

Tarkista myös, että liityntäpalvelimen hallintakäyttöliittymän Diagnostics-valikon näkymässä yhteyksien statusvalo on vihreä (toimiva) kohdissa:

• Global Conf
• TSA timestamping
• OCSP (G3).