Suomi.fi-palveluväylä –
Palvelun hakeminen ja käyttöönotto Liityntäkatalogista

Liityntäkatalogissa kuvataan kaikki Suomi.fi-palveluväylän tuotantoympäristöön (FI) liittyneet organisaatiot ja organisaatioiden tarjoamat palvelut. Liityntäkatalogi on tehty helpottamaan erityisesti palveluiden löydettävyyttä. Sen kautta pääsee näkemään helposti mitä palveluita palveluväylän kautta on tarjolla ja ketkä niitä ylläpitävät.

Suomi.fi-palveluväylään liittyneet organisaatiot ja organisaatioiden tarjolla olevat palvelut haetaan katalogiin automaattisesti. Palveluita palveluväylään tarjoavien organisaatioiden (provider) lisäksi myös palveluiden hyödyntäjäorganisaatiot (consumer) listautuvat Liityntäkatalogin organisaatiot-listaan, vaikkei heillä olisikaan omia palveluita tarjolla. Käyttöönottavien organisaatioiden yhteyshenkilöiden velvollisuus on organisaationsa yhteystietojen, sekä palveluun liittyvien hallinnollisten tietojen täyttäminen Liityntäkatalogin hallintasivuston kautta.

Vielä tässä vaiheessa hallintasivustolle saadaan tunnukset Liityntäkatalogin tuoteomistajalta Rosa Arolalta (rosa.arola@vrk.fi).

Liityntäkatalogi (beta) löytyy nyt osoitteesta: https://liityntakatalogi.suomi.fi/.

Haluan ottaa käyttööni Liityntäkatalogin kautta löytyneen palvelun – kuinka toimin?

  • Varmista, että olet onnistuneesti liittynyt Suomi.fi-palveluväylään testi- ja tuotantoympäristöihin (FI-TEST ja FI).
  • Palveluntarjoajalla on yleensä palveluväylän kehitysympäristössä (FI-DEV) tai testiympäristössä (FI-TEST) testipalvelu toiminnan testaamiseksi ennen tuotantoon siirtoa. Tee siis kaikki palvelun testaamiset näissä ympäristöissä ennen varsinaiseen tuotantoympäristöön siirtymistä. 
  • Etsi Liityntäkatalogin sivulta palvelu, jota haluaisit käyttää. Etusivun välilehti ”Liitynnät” listaa kaikki tarjolla olevat palvelut. Vaihtoehtoisesti palvelua voidaan hakea jollain asiasanalla, esimerkiksi sanalla yritys tai YTJ

  • Valitaan listasta haluttu liityntä, esimerkiksi Patentti- ja Rekisterihallituksen (PRH) tarjoamat YTJ-palvelut (YTJ-tiedot).

Hallinnolliset tiedot

  • Aukeaa sivu palveluiden hallinnollisista tiedoista, liitetiedostoista ja lisätiedoista.

  • Sivun alalaidasta Lisätietoja-kentästä löytyy tarvittavia yhteystietoja palvelun ylläpitäjään. Palvelun käytöstä sovitaan aina yhdessä ylläpitäjän kanssa, eikä tätä tarkoitusta varten ole lomakkeita tai valmiksi määriteltyä prosessia. Riippuen palvelusta, voidaan ylläpitäjän kanssa sopia muun muassa SLA-asioista, mahdollisista palvelumaksuista ja yhteyksien avausasioista.
    • Huom! Liityntäkatalogissa on paljon organisaatioita ja palveluita, joilta puuttuu ylläpitäjien yhteystiedot. Jos näin on, ota yhteyttä Suomi.fi-palveluväylän ylläpitoon, niin autamme löytämään oikean yhteyshenkilön: palveluvayla@palveluvayla.fi tai suomi.fi-asiakaspalvelu@vrk.fi
  • Yhteyksien muodostamista varten palvelun ylläpitäjän on tiedettävä:
    • tunnistetiedot palvelun luvittamista varten (alijärjestelmän nimi = X-Road subsystem code) ja
    • kutsuvan liityntäpalvelimen IP tarvittavia porttiaukaisuja varten.
  • Palvelun hyödyntäjän tarvitsee tietää palvelun tarjoajan liityntäpalvelimen IP-osoite tehdäkseen myös samat porttiavaukset (5500 ja 5577). Palvelun ylläpitäjä antaa avauksiin liittyen sinulle lisätietoa.

  • Liitetiedostoihin listautuu kaikki palveluiden rajapintakuvaukset automaattisesti, ellei palveluntarjoaja niitä erikseen estä. Liitetiedostot-kohtaan palveluntarjoaja myös halutessaan lisätä tarkempia palveluun liittyviä teknisiä dokumentaatioita, kuten pdf-tiedostoja.
  • Alla olevassa kuvassa xroadytj-services alijärjestelmälle lisätty WSDL-rajapintakuvaus (kts. lisätietoja WSDL-kuvauksesta) sisältää useampia palvelukuvauksia, kuten GetCompany.v1, SearchCompany.v1 jne.
  • Seuraavaksi klikataan esimerkiksi GetCompany.v1-palvelun tekninen kuvaus auki

Tekniset tiedot

  • Palvelukuvaukseen aukeaa automaattisesti haettu WSDL-kuvaus, jonka näkee sivulla valmiiksi jäsenneltynä WSDL-välilehdellä, tai tekstimuotoisena Teksti-välilehdellä. Sivulta myös voi ladata WSDL:n tekstitiedostona suoraan omalle koneelle.
  • Sivuotsikon alapuolelta ilmenee SOAP-kutsussa (kts. lisätietoja SOAP-protokollasta) tarvittavat tunnistetiedot eli:
    • ympäristö (FI),
    • organisaatiotyyppi (GOV),
    • organisaation Y-tunnus (0244683-1),
    • alijärjestelmätunnus (xroadytj-services),
    • palvelun nimi (GetCompany) ja
    • palvelun versio (v1)
      Palvelun nimeä ja versiota lukuunottamatta tunnistetidot näkyvät myös hallinnollisten kuvausten lisätiedoissa (Xroad-etuliitteillä)
  • HuomWSDL:ään määritelty Location tai tarkemmin Teksti-välilehdellä addresslocation (tässä tapauksessa https://dataservices.ytj.local:8091/CompanyQuery/CompanyQueryServiceAdapter.ashx) ei ole avoin osoite, joka olisi suoraan kutsuttavissa ilman liityntäpalvelimia. Palvelukutsut tehdään aina omalle liityntäpalvelimen osoitteeseen, jota kautta kutsu välittyy palveluntarjoajan liityntäpalvelimelle ja lopulta kyseessä olevalle palvelulle.

  • WSDL-välilehden GetCompany kohdasta löytyy muun muassa tietoa parametreista, joilla palvelua kutsutaan ja mitä se palauttaa. Lisätietoa palvelusta kannattaa kysyä suoraan palvelun ylläpitäjältä.

  • Kun tarvittavat palomuuriavaukset ja palveluluvitukset on tehty, voi liityntäpalvelinten välisiä yhteyksiä, sekä palvelun toimintaa lähteä testaamaan. Sanomakutsun kokeilu onnistuu kevyesti esimerkiksi SoapUI-työkalulla: https://www.soapui.org/. SoapUI clientilla sanomakutsu lähetetään kutsujan (consumer) liityntäpalvelimelle, joka sitten välittää kutsun eteenpäin väylän yli palveluntarjoajan (provider) liityntäpalvelimelle ja sieltä edelleen varsinaiselle palvelulle.
  • Jotta palvelua voisi hyödyntää omassa taustajärjestelmässä, on mahdollistettava kutsujen lähettäminen ja vastaanottaminen X-Road-protokollan mukaisesti (kts. X-Road tiedonsiirtoprotokolla). Tämä saattaa vaatia jonkinlaisen sovitinratkaisun luomista, jotta protokollan vaatimukset täyttyisivät. (kts. sovitinpalvelu)

Print Friendly, PDF & Email

VersioMitä tehty / muutettuPvm/
henkilö
1.0Dokumentti julkaistu.02.06.17 / HH

Yksilöintitunnus: 12345