Ohje ylläpitäjälle

Tietojen täydentäminen Palveluväylän Liityntäkatalogiin

                                                                             

Sisältö

1 Liityntäkatalogin liityntäkuvaukset ovat oleellisia Palveluväylän käytettävyyden kannalta

2 Organisaation ja käyttäjän tiedot

3 Liitynnän kuvaustiedot kertovat, mitä liityntä tarjoaa ja miten sen voi ottaa käyttöönsä

4 Liitetiedoston kuvaustiedot ohjeistavat yksittäisen rajapinnan teknisessä käyttöönotossa

5 Liityntäkatalogin tietomalli ja käsitteitä

 

 

1 Liityntäkatalogin liityntäkuvaukset ovat tärkeitä Palveluväylän käytettävyyden kannalta

Liityntäkatalogissa on koottuna Suomi.fi-Palveluväylän kautta tarjottavat liitynnät eli rajapintapalvelut sekä niiden ylläpitäjät. Liityntäkatalogin avulla Palveluväylän rajapintapalveluiden käyttöönottoa suunnittelevat organisaatiot näkevät, mitä liityntöjä ja tietoa Palveluväylässä on tarjolla. Katalogissa kuvatun liitynnän voi ottaa käyttöönsä sopimalla siitä liitynnän ylläpitäjän kanssa.

Tietojen täydentäminen Liityntäkatalogiin

Liityntöjen rajapintatiedot, kuten esimerkiksi nimi ja rajapintakuvaukset, päivittyvät päivittäin automaattisesti Palveluväylästä Liityntäkatalogiin.

Liityntöjä kuvaavat tiedot (ns. metatiedot) organisaatioiden ylläpitäjien tulee kuitenkin täydentää itse Liityntäkatalogin 

käyttöliittymässä.

Esimerkiksi liityntöjen yleistajuiset kuvaukset ja ylläpitäjän yhteystiedot ovat tällaisia metatietoja. Liityntöjen kuvaukset ovat oleellisia Liityntäkatalogin ja koko Palveluväylän käytettävyyden kannalta, sillä ne kertovat katalogia selaavalle, minkälaisia liityntöjä Palveluväylän kautta on tarjolla.

 

Liitynnän tietojen täydentäminen ohjeistetaan luvussa 2.

 

Oikealla on esimerkkinä VRK:n VTJ-rajapinta-liitynnän kuvaus Liityntäkatalogissa. Kuvauksessa on kerrottu lyhyesti:

  • mitä tietosisältöjä liitynnästä voi saada
  • mitä ehtoja tai rajoituksia sen käytössä on
  • miten tulee edetä, jos liitynnän haluaa käyttöönsä.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

2 Organisaation ja käyttäjän tiedot

Miten Liityntäkatalogissa pääsee muokkaamaan organisaation tietoja?

Muuttaaksesi organisaatiosi tietoja, mene organisaatiosi tietoihin Liityntäkatalogissa ja klikkaa oikeasta yläkulmasta Hallinnoi-painiketta. Sinun täytyy olla kirjautuneena Liityntäkatalogiin ja sinulla täytyy olla oikeudet muokata organisaatiosi tietoja katalogissa.

Organisaatiosi Liityntäkatalogin ylläpitäjältä saat oikeudet muokata tietoja. Jos organisaatiossasi ei ole henkilöä, jolla olisi oikeudet muokata organisaatiosi tietoja, pyydä oikeuksia ja tunnuksia Liityntäkatalogin ylläpidolta: palveluvayla@palveluvayla.fi.

Mitä organisaation kuvauksessa tulee kertoa?

Kerro organisaation kuvauksessa lyhyesti yleistiedot organisaatiostasi: mikä organisaatio on kyseessä ja mitä se tekee. Voit myös mainita muutamalla virkkeellä, millaisia liityntöjä ja mitä tietoa organisaatiosi Palveluväylän kautta tarjoaa. Kuvaukseen voi tehdä linkin organisaation verkkosivuille.

Kuvaksen voi lisätä suomenkielisen tekstin perään myös ruotsiksi ja englanniksi.

Esimerkiksi Väestörekisterikeskuksen organisaatiokuvauksessa on kerrottu kolmella virkkeellä perustiedot organisaatiosta. Samat virkkeet ovat kuvauksessa myös ruotsiksi ja englanniksi. Kuvauksessa on myös verkkolinkit vrk.fi-sivustolle.

Logo/Kuva

Organisaatiolla on hyvä olla logo Liityntäkatalogissa. Voit ladata organisaatiosi logon kuvan työasemaltasi klikkaamalla sinistä Lataa-painiketta.

Käyttäjäjäsenet

VRK lisää ensimmäisen käyttäjän ja sen jälkeen organisaatio voi hallinnoida itse käyttäjiä ja heidän oikeuksiaan sekä kutsua uusia käyttäjiä. Pyydä tarvittaessa ylläpitäjän käyttäjätunnuksia Liityntäkatalogin ylläpidolta: palveluvayla@palveluvayla.fi.

Liityntäkatalogissa on erilaisia käyttäjärooleja, joilla on eri oikeudet. Esimerkiksi jäsenellä on oikeus vain liityntöjen tarkasteluun. Alla näet kaikki käyttäjäroolit ja oikeudet.

Liityntäkatalogin käyttäjäroolit

 

Ylläpitäjä

Muokkaaja

Jäsen

Liitynnän lisäys

x

x

 

Liitynnän muokkaus

x

x

 

Liitynnän poistaminen

x

 

 

Organisaation jäsenten hallinnointi

x

 

 


Käyttäjien pakollisia tietoja ovat käyttäjätunnus, salasana, tila ja rooli. Käyttäjälle voi antaa myös kuvauksen ja nimen, mutta nämä ovat vapaaehtoisia tietoja.

 

3 Liitynnän kuvaustiedot kertovat, mitä liityntä tarjoaa ja miten sen voi ottaa käyttöönsä

Miten liityntöjen tietoja pääsee muokkaamaan?

Muuttaaksesi liityntäsi tietoja, mene liitynnän tietoihin Liityntäkatalogissa ja klikkaa oikeasta yläkulmasta Hallinnoi-painiketta. Sinun täytyy olla kirjautuneena Liityntäkatalogiin ja sinulla täytyy olla oikeudet muokata organisaatiosi tietoja katalogissa.

Organisaatiosi ylläpitäjältä saat oikeudet muokata tietoja. Jos organisaatiossasi ei ole henkilöä, jolla olisi oikeudet muokata organisaatiosi tietoja, pyydä oikeuksia ja tunnuksia Liityntäkatalogin ylläpidolta: palveluvayla@palveluvayla.fi.

Huomioi, että liitynnän nimeä ei voi muokata Liityntäkatalogissa, sillä se tulee automaattisesti Palveluväylästä.

Mitä liitynnän kuvauksessa tulisi kertoa?

Liitynnän kuvaus on liitynnän rajapintoja ja sisältötietoja markkinoiva palvelulupaus. Älä siis kirjoita kuvausta liian teknisellä kielellä, vaan pyri yleistajuiseen ilmaisuun. Kirjoita kuvaus ytimekkäästi, mutta muista kertoa kaikki oleellinen. Katso esimerkiksi Väestörekisterikeskuksen kuvaus VTJ-rajapinta-palvelusta. Liitynnän teknisen kuvauksen tuottaminen on ohjeistettu kohdassa 4.

Kerro kuvauksessa:

  • Mitä tietoja liitynnän kautta voi saada käyttöönsä
    Kerro kuvauksessa, miten muut organisaatiot voivat hyötyä liitynnästä. Näin toiset organisaatiot voivat saada yleiskuvan liitynnästä ja arvioida, kannattaisiko heidän organisaationsa ottaa liityntä käyttöön.
  • Mitä rajoituksia liitynnän käytössä on
    Kerro kuvauksessa liitynnän käyttöön liittyvistä rajoituksista. Erittele esimerkiksi se, kuka liitynnän voi ottaa käyttöönsä. Kerro myös muista mahdollisista rajoituksista, jotka voivat liittyä esimerkiksi liitynnän käyttöaikoihin, tietolupakäytäntöihin, maksullisuuteen ja sisältötietojen julkisuuteen.
  • Miten liitynnän saa käyttöönsä
    Ohjeista kuvauksessa, miten toisten organisaatioiden tulee edetä, kun he haluavat saada liitynnästä lisätietoa tai ottaa sen käyttöön. Kuvaile käyttöönoton prosessi lyhyesti yleisellä tasolla ja ilmoita, mistä lisätietoja saa. Liitynnän ylläpitäjän yhteystiedot ilmoitetaan omassa kentässään, mutta jos yhteystietoja on useampia, voit ilmoittaa niitä myös kuvauskentässä.

 

Huomioi liityntäkuvausta tehdessä myös:

  • Käytä muotoiluja
    Muotoilujen käyttäminen parantaa tekstin ymmärrettävyyttä. Kuvausteksti kannattaa jakaa alaotsikoinnin avulla (esimerkiksi kolmeen yllä esitettyyn eri osioon: Mitä / Millä ehdoilla / Miten). Voit myös korostaa tekstin tärkeimpiä kohtia käyttämällä lihavointia.

    Huom. Muotoiluja tekstiin saa ns. Markdown-muotoiluna. Näet muotoilumahdollisuudet klikkaamalla kuvauskentän alapuolella olevaa Voit käyttää tässä Markdown-muotoiluja -kohtaa. Esimerkiksi otsikkomuotoilun saat, kun lisäät otsikon eteen #-merkin. Kirjoita kuvauskenttään esimerkiksi: ”# Tietojen käytön edellytykset ” ja saat viereisen esimerkin kaltaisen väliotsikon. Lisätietoja Markdown-muotoilusta saat täältä.
     
  • Kirjoita kuvaus myös ruotsiksi ja englanniksi
    Kuvauksen kieliversiot täydennetään omiin kenttiinsä (suomenkielisen kentän alla) ja ne näkyvät, jos käyttäjä käyttää liityntäkatalogia eri kielellä. Muista päivittää myös kuvauksen kieliversiot, kun päivität kuvausta.

 

 

 

Asiasanat

Anna liitynnälle liitynnän tarjoamia tietoja kuvaavia tai liityntään oleellisesti liittyviä asiasanoja. Esimerkiksi vtjrajapinta-liitynnälle on annettu asiasanoiksi ”väestötietojärjestelmä”, ”henkilötunnus”, ”henkilötiedot”, jne.

Liityntäkatalogin haku kohdistuu nimen ja tekstikenttien lisäksi asiasanoihin. Hyvin asiasanoitettu liityntä löytyy katalogista siis helpommin. Kun annat liitynnälle asiasanoja, kannattaa miettiä, millä hakusanoilla itse etsisit kyseistä rajapintapalvelua.

Voimassaoloaika

Voimassaolo alkaa -kohdassa ilmoitetaan, mistä alkaen liityntä on käytössä.

Jos liityntä on voimassa toistaiseksi, ei Voimassaolo päättyy -kohdassa tarvitse ilmoittaa mitään.

Jos kuitenkin tiedossa on päivämäärä, jolloin liityntä muuttuu tai poistuu Palveluväylästä, tulee se ilmoittaa Voimassaolo päättyy -kohdassa.

Ympäristö

Ympäristö-kohdalla viitataan Palveluväylän eri ympäristöihin. Sen avulla voitaisiin siis erotella testi- ja tuotantoympäristön liitynnät toisistaan. Testiympäristö ei kuitenkaan ole tällä hetkellä käytössä, joten kyseiseen kohtaan ei tarvitse merkitä mitään.

Näkyvyys

Voit julkaista liitynnän Palveluväylän Liityntäkatalogissa kaikkien katalogia selailevien nähtäväksi siirtämällä sen Julkinen-tilaan. Yksityinen-tilassa vain liityntää hallinnoiva organisaatio voi nähdä sen Liityntäkatalogissa.

Yksityinen-tilaa voi käyttää esimerkiksi silloin, jos liitynnän kuvaukset eivät ole vielä valmiita, eikä liityntää haluta siksi näyttää julkisesti katalogissa.

Liitynnän yhteiskäyttöisyys

Jos muut organisaatiot voivat hyödyntää liityntää, valitse aina kyllä.

Liitynnän yhteystiedot

Kerro liitynnän ylläpitäjän yhteystiedot, jotta liitynnästä kiinnostuneet organisaatiot voivat kysyä lisätietoja liitynnästä.

Anna organisaation toimialakohtainen sähköpostipostiosoite henkilökohtaisen osoitteen sijasta, jos se on mahdollista. Näin liityntää koskevat tiedustelut eivät jää käsittelemättä esimerkiksi henkilökohtaisten poissaolojen vuoksi.

 

4 Liitetiedostot ohjeistavat yksittäisen rajapinnan käyttöönotossa ja käytössä 

Liitynnän liitetiedostosivu tai -sivut koostuvat Liitynnän yhteenvedosta sekä automaattisesti luodusta esikatselusta varsinaisen liityntätiedoston sisältöön. Lisäksi liitetiedostolle voidaan syöttää muita tietoja, kuten esimerkiksi liitetiedoston kuvauksen. Luo oma liitesivu jokaiselle rajapinnalle erikseen. Voit katsoa esimerkkiä VTJ-rajapinta-liitynnästä, jolla on monta liitetiedostoa.

Liitynnän liitetiedoston kuvauksen on tarkoitus olla tekninen ohje yksittäisen rajapinnan käyttöönotolle ja käytölle. Kuvaile siinä siis, miten ko. rajapinta voidaan ottaa käyttöön ja mitä kaikkea tulee ottaa huomioon sitä käytettäessä.

Liitetiedostolle voidaan antaa seuraavia tietoja:

  • Kuvaus FI, SV, EN
  • Tyyppi FI, SV, EN
  • Maksullisuus Kyllä/Ei/Katso kuvaus
  • Tiedostomuoto
  • Voimassaoloaika alkaa
  • Voimassaoloaika päättyy
  • Liityntätiedot FI, SV, EN
  • Saatavuus FI, SV, EN
  • Service Level Agreement FI, SV, EN
  • Keskimääräinen vasteaika
  • Palvelun tila FI, SV, EN
  • Lisenssi

 

5 Liityntäkatalogin tietomalli ja käsitteitä

Liityntäkatalogi sisältää aina ajantasaisen tiedon Palveluväylään liittyneistä organisaatioista ja niiden liitynnöistä. Liityntäkatalogiin harvestoidaan joka yö viimeisimmät tiedot liitynnöistä. Palveluväylän keskuspalvelin harvestoi ne asiakaskohtaisilta liityntäpalvelimilta.

Automaattisesti Palveluväylästä harvestoituvien tietojen lisäksi organisaatiot kuvaavat itse katalogin käyttöliittymässä organisaatioon, käyttäjiin, liityntään ja liitetiedostoihin liittyviä liityntöjä kuvailevia tietoja (metatietoja).

Organisaatio on Palveluväylän käyttäjäorganisaatio.

Käyttäjä on käyttäjäorganisaation jäsen tai esimerkiksi tekninen operaattori, joka voi toimia käyttäjäorganisaation puolesta.

Liityntä: Rajapintapalvelu, johon voi liittyä yksi tai useampi rajapinta.

Esimerkki: VTJ-liitynnässä on liitynnän perustiedot kuvattu yhdellä sivulla ja lisäksi on listattu liitetiedostoja, joista vähintään yksi on Palveluväylän keskuspalvelimilta automaattisesti harvestoituva WSDL-tiedosto.

Rajapinta: Liittyy vain yhteen palveluun ja sisältää aina yhden teknisen kuvauksen, joka näytetään visuaalisesti Liityntäkatalogissa (esim. WSDL tai XML-kuvaus).

Esimerkki: VTJ-liityntään liittyy useita rajapintoja, joista osa on ohjeistavia, kuten esimerkkisanomia. Katso esimerkiksi VTJ-liitynnän rajapinta ”HenkilönTunnuskysely”.

Liitetiedosto: Liitynnällä on aina vähintään yksi liitetiedosto, harvestoituva WSDL-kuvaus. Tämän pakollisen lisäksi voi olla muita liitetiedostoja, esimerkiksi ohjeita tai esimerkkejä kysely- ja vastaussanomista.