Yksittäisen palvelun käyttöönotto
Tällä sivulla on kuvattu, miten Palveluväylän kautta tarjottavan palvelun käyttöönotto tapahtuu, kun organisaatio on jo liittynyt Palveluväylään ja organisaatiolla on toimiva liityntäpalvelin.
- Tutustu palveluun, sen käyttöehtoihin ja teknisiin tietoihin Liityntäkatalogissa
- Hae palvelun käyttölupaa (alijärjestelmän käyttölupa)
- Yhdistä organisaatiosi ja palveluntarjoajan tietojärjestelmät
Huomaa, että yksittäisen palvelun käyttöönotto riippuu aina palveluntarjoajasta. Varmista palvelukohtaiset ohjeet tarvittaessa palvelua tarjoavalta organisaatiolta.
Ennakkovaatimukset:
Ennen yksittäisen palvelun käyttöluvan hakemista organisaatiosi tulee olla liittynyt Palveluväylään ja organisaatiollasi tulee olla toimiva alijärjestelmä. Huolehdi siis, että liityntäpalvelimellesi on lisätty vähintään yksi alijärjestelmä.
- Voit lisäksi tarkistaa alijärjestelmän olemassaolon LiityntäkatalogistaAvautuu uuteen ikkunaan. oman organisaatiosi kohdalta.
Huom! Jos alijärjestelmä lisätään liityntäpalvelimeen, joka ei vielä ole käytössä Palveluväylässä, tulee tällöin noudattaa Palveluväylään liittymisen ohjeita Liity testiympäristöön -ohjesivusta eteenpäin. 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 Käyttöönotto-sivulla.
1. Tutustu palveluun, sen käyttöehtoihin ja teknisiin tietoihin Liityntäkatalogissa
Palvelua tarjoava organisaatio kertoo palvelustaan alijärjestelmän kuvauksessaan LiityntäkatalogissaAvautuu uuteen ikkunaan..
- 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.
2. Hae palvelun käyttölupaa (alijärjestelmän käyttölupa)
Palveluiden käyttö saattaa edellyttää alijärjestelmän käyttöluvan hakemista. Riippuen käyttöönotettavasta palvelusta, käyttölupaa voi hakea joko Liityntäkatalogissa Avautuu uuteen ikkunaan.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
Jos käyttöönottamasi palvelun käyttölupaa ei voi hakea Liityntäkatalogissa, ota yhteyttä suoraan 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..
Testaaminen on mahdollista, kun alijärjestelmä on lisätty liityntäpalvelimelle ja alijärjestelmälle on myönnetty käyttölupa. 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. Lue testaamisesta tarkemmin.
3. 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ä.
Palveluväylän käyttöoikeuksien määrittely tapahtuu alijärjestelmätasolla, jonka vuoksi tulisi lähtökohtaisesti käyttää asiakasjärjestelmäkohtaisia alijärjestelmiä. Joissain tapauksissa myös useat, yhden loogisen kokonaisuuden muodostavat asiakasjärjestelmät voivat hyödyntää samaa alijärjestelmää palveluiden kutsumiseen.
Käytännössä liityntäpalvelimen käyttöön ottaminen ja alijärjestelmän lisääminen tapahtuvat osana Palveluväylään liittymistä.
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:
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.
Huom.! Jos alijärjestelmän käyttöluvan myöntämisen ja porttiavausten jälkeen organisaatiosi ja palveluntarjoajan välisessä yhteydessä on ongelmia, tarkista liityntäpalvelimen virhelokit.
- NIIS:n tukiartikkeli auttaa virheilmoitusten tulkitsemisessa: How to Interpret Security Server Proxy Error Messages? - X-Road Knowledge Base - NIIS ConfluenceAvautuu uuteen ikkunaan.