18.2.2016 <tässä rajapinnan hallintasuunnitelman pohjassa on koottu ohjeita suunnitelman täyttämiseksi. Pohjaa tulee soveltaa kunkin palvelun osalta. Poistakaa hakasulkeissa olevat ohjetekstit suunnitelmasta.> xxx avoimen rajapinnan hallintasuunnitelma (VALMIS 1.4) Versionhallinta: Versio Pvm Tila (Luonnos / Ehdotus / Tekijä(t) Huomautukset (kommentit, johtoryhmän hyväksyntä, muutosehdotuksen syy ja muutoskohteet) Hyväksytty) 0.1 21.8.2015 Dokumenttipohja Dokumenttipohja 0.2 26.8.2015 Luonnos 0.3 30.8.2015 0.4 0.5 20.9.2015 0.9 29.9.2015 Ehdotus 1.Ehdotus 1.0 1.10.2015 Valmis 1.2 3.2.2016 Valmis 1.2 Selkeytetty kappalejakoa ja tekstien kuvauksia Merkitty kohdat jotka on tärkeä suunnitelma ennen rajapinnan kehittämistä 1.3 10.2.2016 Valmis 1.3 Lisätty uusia kohtia kommenttien perusteella 1.4 17.2.2016 Valmis 1.4 Julkaistava versio
18.2.2016 2/9 Sisällysluettelo: 1 Johdanto... 3 2 xxx rajapinnan ja sen hallinnan perustiedot... 3 3 xxx rajapinnan hallinnan roolit ja organisaatiot... 5 4 xxx rajapinnan elinkaarenhallinta... 6 5 xxx rajapinnan hallinnan rahoituksen käytännöt... 7 6 xxx rajapinnan dokumentaatio... 8 7 xxx rajapintamäärityksiä noudattavat ohjelmistot... 8 Liite 1: hallinnan roolikuvaukset... 9
18.2.2016 3/9 1 Johdanto Tämä dokumentti kuvaa <xxx> rajapinnan tai rajapinta kokonaisuuden hallintasuunnitelman. Tässä rajapinnan hallintasuunnitelman pohjassa on koottu ohjeita suunnitelman täyttämiseksi. Pohjaa tulee soveltaa kunkin palvelun osalta. <Poistakaa hakasulkeissa olevat ohjetekstit suunnitelmasta.> 2 xxx rajapinnan ja sen hallinnan perustiedot Taulukko 1. /rajapintakokonaisuuden perustiedot. Tähän taulukkoon kuvataan rajapinnanperustiedot. Kaikki tietietoja ei tarvitse rajapinnan hallintasuunnitelman alkuvaiheessa täyttää vaan ne täydentyvät rajapintatoteutuksen aikana. Kohdat, jotka on hyvä miettiä mahdollisimman alussa tai ennen kehittämiseen ryhtymistä on merkitty alleviivauksella. /rajapintakokonaisuuden perustiedot /rajapintakokonaisuuden nimi uusin versionumero ja sen hyväksymispäivämäärä käyttämiseen liittyvät oikeudet tai lisenssit Rajanpinnan toiminnallisen määrittelyyn osallistuneet sidosryhmät kehittämisen koordinoinnin suorittanut organisaatio tekniset määritykset laatinut organisaatio <rajapintakokonaisuuden nimi> <Rajapintakokonaisuus voi koostua, joka yhdestä tai useammasta rajapinnasta. Rajapintakokonaisuuden muodostavat rajapinnat, jotka palvelevat saman toimialueen järjestelmien yhteentoimivuuden tarpeita> <mitä rajapintaversiota tällä dokumentilla hallitaan> <jos rajapinnalla on versionumero niin se laitetaan tähän sekä version hyväksymispäivämäärä> <tähän kuvataan tai viitataan dokumentaatioon jossa kuvataan rajapinnan käyttöönottoon liittyvät mahdolliset lisenssit, oikeudet tai rajoitukset> <tähän kuvataan rajapinnan toiminnalliseen määrittelyyn osallistuneet sidosryhmät> <tähän kuvataan organisaatio, joka on koordinoinut rajapintakokonaisuuden kehittämisen> <rajapinnan tekniset määritykset toteuttanut organisaatio>
18.2.2016 4/9 Ensimmäisen rajapintaversion toteutuksen rahoittaja dokumentaation jakelupaikka Hakusana/yksilöivä tunniste jakelupaikassa Sosiaalisen median välineet ja toimintatavat <ensimmäisen rajapintatoteutuksen rahoittanut taho> <mistä rajapintaan liittyen saa lisätietoja ja siihen liittyvän dokumentaation saa itselleen? tarvittava dokumentaatio kuvattu taulukossa 6> <millä nimellä rajapintakuvaus on jakelupaikassa> <millaisia sosiaalisen median välineitä ja toimintatapoja palvelua kehittävä yhteisö käyttää (esim. facebook)?>
18.2.2016 5/9 3 xxx rajapinnan hallinnan roolit ja organisaatiot Tässä kappaleessa kiinnitetään rajapinnan hallintaan liittyvät roolit organisaatioihin ja henkilöihin <Tutustu rajapinnanhallinnan roolikuvauksiin jotka ovat liitteenä 1. Ne kertovat esimerkkejä eri roolien tehtävistä ja tarkoituksesta> Taulukko 3. Roolit ja organisaatiot Rooli omistaja Rajapintaa hallinnoivan organisaation/yhteisön nimi ja rakenne Nimi / organisaatio <tähän kuvataan rajapinnan omistajan organisaatio> <Omistajaorganisaatio/yhteisö, jos eri kuin rajapinnan omistaja> Johtoryhmä/ohjausryhmä <mikä on johtoryhmän ja/tai ohjausryhmän rakenne?> tuotepäällikkö / kehittämisen koordinaattori teknisen laadun/ avoimuuden valvoja <tähän nimetään henkilö, joka vastaa rajapinnan elinkaaresta ja kehittämisestä rajapinnan hallintasuunnitelman kuvausten mukaisesti> <Huolehtii, että rajapinnan tekninen määrittely on laadukas ja jokaisen järjestelmän rajapintatoteutus vastaa määrityksiä. Voi olla myös rajapinnan tuotepäällikkö, jos osaaminen on riittävää tekniseen laadunvalvontaan>
18.2.2016 6/9 4 xxx rajapinnan elinkaarenhallinta Taulukko 4. Toimintatavat rajapinnan elinkaarenhallinnassa Asia hallinnan ohjausryhmän/johtoryhmän kokoontuminen julkaisusuunnitelma muutospyyntöjen esittäminen muutospyynnön analysointi ja muutosehdotuksen tekeminen muutospäätöksen tekeminen muutoksen toteutus (muutostyön projektointi) versionhallinta Uuden rajapinnan version hyväksyntä ja käyttöönotto Kiireellinen korjaus rajapintaan käytönpäättäminen Kuvaus <kuinka ohjausryhmä kokoontuu? Kuka kutsuu kokouksen koolle? Kuka toimii tapaamisten koordinaattorina ja puheenjohtajana? Onko tapaamisille aikataulua?> <mitä asioita käsitellään ohjausryhmän tapaamisessa? Mitkä asiat ovat johtoryhmän päätäntävallassa? Mitä asioita käsitellään mahdollisessa kehitysryhmässä/ohjausryhmässä?> <millaisia rajapintaversioita tehdään ja millaisella aikataulutuksella? Onko esimerkiksi pienempiä julkaisuja (virheenkorjaukset, parannukset) ja suurempia julkaisuja (uusia ominaisuuksia, teknologiamuutoksia)?> <kuinka muutospyynnöt/uudet ideat tehdään ja mihin/miten ne talletetaan/dokumentoidaan?> <kuinka pyynnöt analysoidaan ja kenen toimesta? Käyttääkö rajapinnan tuotepäällikkö yhteisön asiantuntijoita? Kuka kokoaa muutosehdotuksen?> <mitkä ovat päätöksentekovaltuudet johtoryhmällä, kehitysryhmällä/ohjausryhmällä ja tuotepäälliköllä?> <kuinka uuden rajapintaversion toteutus projektoidaan? Kuka vastaa projektinhallinnasta?> <kuinka versionhallinta toteutetaan rajapinnan elinkaaren aikana? esimerkiksi ylläpidetäänkö useita rajapintaversioita ja miten ne versioidaan > <kuinka yhteisö/johtoryhmä/tuotepäällikkö hyväksyy uuden version ohjelmistosta käyttöön? Käytetäänkö yhteisön asiantuntijoita hyväksymistestaukseen? Miten uudesta versiosta tiedotetaan?> <kuka hyväksyy ja koordinoi mahdollisen kiireellisen korjauksen (esim. tietoturva ongelma)?> <onko tunnistettavissa tilanteita tai olosuhteita, joissa rajapinta poistetaan> <jos sellaisia on niin miten niihin varaudutaan ja miten niissä toimitaan> <kuka vastaa ja
18.2.2016 7/9 organisoi alasajon> 5 xxx rajapinnan hallinnan rahoituksen käytännöt Taulukko 5. Rahoituskäytännöt ensimmäisen perusversion tuottamisen jälkeen Rooli / toiminta ylläpidon ja sen kehittämisen rahoittaminen Rahoituksen jakaminen käyttöönoton rahoittaminen Osallistuminen ohjausryhmän toimintaan Uuden toimijan mukaantulo ohjausryhmään tekninen laadunvalvoja dokumenttien jakelupaikka ja sen ylläpito Rahoitus <miten rajapinnan vaatimat ylläpitotehtävät rahoitetaan esimerkiksi muuttuvien tarpeiden vaatimien rajapintamäärittelyiden toteutukset sekä rajapintojen muutokset järjestelmiin> <mikäli pelkästään yksi taho ei rahoita rajapinnan ylläpitoa niin on tehtävä päätös miten rahoitus jaetaan eri toimijoiden kesken?> <kuvataan miten rajapinnan käyttöönotto rahoitetaan organisaatioissa vai rahoittaako, jokainen organisaatio käyttöönoton omassa organisaatiossa> <osallistuminen yhteisön toimintaan vaatii osallistumista esim. yhteisöpalavereihin. Kustantavatko kukin taho oman osallistumisensa yhteisön toimintaan? Miten hoidetaan kokouksien järjestelykustannukset?> <tuleeko uuden toimijan maksaa liittymismaksu tai muu vastaava osallistuessaan yhteisön toimintaan tai ottaessaan rajapinnan käyttöönsä?> <kuinka laadunvalvojan toiminta rahoitetaan?> <liittyykö jakelupaikan ylläpitoon/administraatioon jotakin kustannuksia? Kuinka ne rahoitetaan?>
18.2.2016 8/9 6 xxx rajapinnan dokumentaatio <kuvataan mitä rajapinnan käyttämiseen liittyvää dokumentaatiota rajapinnasta on saatavilla ja missä tämä dokumentaatio sijaitsee. Dokumentit eivät välttämättä ole alla esitetyillä nimillä olemassa ja saattavat löytyä useista ohjelmiston dokumenteista. Riippuen rajapinnasta välttämättä kaikkia dokumentteja ei tarvita.> Taulukko 6. dokumentaatio Dokumentti Dokumentin nimi Dokumentin sijainti toiminnallinen kuvaus tekninen kuvaus tietosisällön kuvaus käyttöönotto tai käyttämisen ohje kehittämiseen liittyvä projektidokumentaatio käyttämisen tietoturvaan ja tietosuojaan liittyvä dokumentaatio koneluettava dokumentaatio (Rajapinnat on dokumentoitu koneluettavalla rajapintakuvauksella (esim. Swagger, OpenAPI definition, RAML, JSON Schema)) Taulukko7. Dokumentaation ylläpito Ylläpitotehtävä Dokumentaation tallennus ja ylläpito jakelupaikkaan Dokumentaation laadunvarmistus Vastuuosapuoli 7 xxx rajapintamäärityksiä noudattavat ohjelmistot Taulukko 2. Rajapinta määrityksiä noudattavat ohjelmistot eli alla olevaan taulukkoon on kuvattu ohjelmistot, joihin on toteutettu rajapintamääritysten mukaiset rajapinnat.
18.2.2016 9/9 Ohjelmiston nimi ja versio <tähän annetaan ohjelmiston nimi ja versionumero, johon rajapinta on toteutettu> Yhteyshenkilö ohjelmistoa koskevissa asioissa <tähän annetaan ohjelmiston omistajan ja yhteyshenkilön nimi> Huomautuksia <mahdollisia huomautuksia> Liite 1: hallinnan roolikuvaukset Rooli Tehtävät Omistaja hallinnan järjestäminen joko itse tai valtuuttaa toiset tehtävään. Sovitun rajapinnan rahouituksen noudattamisen valvonta tuotepäällikkö/ Koordinaattori teknisen laadun ja avoimuuden valvoja Käynnistää ja koordinoi rajapinna yhteisön toimintaa Kommunikaatio Kaupunkien ja Ohjelmistotalojen kanssa, joiden ohjelmistoihin on määritelty rajapinta toteutettu Kutsuu yhteisöpalaverin ja Johtoryhmän koolle. Toimii palaverien koordinaattorina ja sihteerinä. Huolehtii että toimitetussa rajapinnassa on ne ominaisuudet, jotka Johtoryhmä on sopinut siihen toteutettavaksi ja että muutokset on toteutettu, testattu ja dokumentoitu hyväksyttävällä tavalla. Huolehtii että rajapinnat noudattavat annettuja määrityksiä Järjestää toimitetulle rajapinnalle testauksen Tehtävää voi myös suorittaa Tuotepäällikkö. Ohjausryhmä/ Johtoryhmä Rajapinta dokumentaatio jakelupaikan ylläpitäjä Päättää rajapinnan kehityksen tiekartasta ja seuraavan julkaisuversion sisällöstä sekä rajapinnan hallinnasta ja sen roolitukseen liittyvissä muista asioista. Johtoryhmä voi kutsua mukaan tarvittaessa ulkopuolisia asiantuntijoita. Ylin päätäntävalta rajapinnan kehittymisestä. Jakelupaikan muodostaminen rajapinnanhallinnan suunnitelman mukaan Jakelupaikan administraatio. Käyttöoikeudet, kehittäminen, opastus, ym.