Ohje ylläpitäjälle

Liityntöjen ja organisaatioiden tietojen täydentäminen Liityntäkatalogiin

 

Sisältö

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

2 Organisaation tiedot ja käyttäjähallinta

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äkuvaukset ovat tärkeitä Palveluväylän käytettävyyden kannalta

Liityntöjen kuvaukset ovat oleellisia Liityntäkatalogin ja koko Palveluväylän käytettävyyden kannalta, sillä ne kertovat katalogia selaavalle, minkälaisia rajapintapalveluita Palveluväylän kautta on tarjolla. Tässä ohjeessa neuvotaan, kuinka kuvaat organisaatiosi liitynnät katalogiin.

• Liityntöjä kuvaavat tiedot (ns. metatiedot) organisaatiot täydentävät itse Liityntäkatalogin käyttöliittymässä. Esimerkiksi liityntöjen yleistajuiset kuvaukset ja ylläpitäjän yhteystiedot ovat tällaisia metatietoja. 
• Liityntöjen rajapintatiedot, kuten esimerkiksi nimi ja rajapintakuvaukset, puolestaan päivittyvät päivittäin automaattisesti Palveluväylästä Liityntäkatalogiin.

 

2 Organisaation tiedot ja käyttäjähallinta

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

Muuttaaksesi organisaatiosi tietoja, mene organisaatiosi tietoihin Liityntäkatalogissa ja klikkaa 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.

Kuvaus on  hyvä lisätä myös ruotsiksi ja englanniksi.

Esimerkiksi Digi- ja väestötietoviraston organisaatiokuvauksessa on kerrottu tiiviisti perustiedot organisaatiosta. Kuvauksessa on myös verkkolinkit dvv.fi-sivustolle.

Logo/kuva

Organisaatiolla on hyvä olla logo/kuva Liityntäkatalogissa. Voit ladata kuvan työasemaltasi klikkaamalla Lataa-painiketta.

Käyttäjäjäsenet

DVV 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 kolme eri käyttäjäroolia, joilla on erilaisia oikeuksia:

• Ylläpitäjän oikeudet: liityntöjen tarkastelu, lisääminen, muokkaaminen ja poistaminen sekä organisaation jäsenten hallinointi
• Muokkaajan oikeudet: liityntöjen tarkastelu, lisääminen ja muokkaaminen
• Jäsenen oikeudet: liityntöjen tarkastelu

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 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 Digi- ja väestötietoviraston kuvaus VTJ-rajapinta-palvelusta (ks. kuva alla). 

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 väliotsikkomuotoilun saat, kun lisäät otsikon eteen "###". Kirjoita kuvauskenttään esimerkiksi: ”### Palvelun maksullisuus” ja saat kyseisestä tekstistä väliotsikon. Lisätietoja Markdown-muotoilusta saat Markdown Guide -verkkosivulta (sivu englanniksi).
• 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 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ä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.

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.
  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.