PlugIT-projektin rajapintojen määrittely, dokumentointi ja hyväksyminen

PlugIT-projektin rajapintojen määrittely, dokumentointi ja hyväksyminen LUONNOS Johtoryhmälle 25.10.2002

2 Sisällys 1 Johdanto...3 2 Integrointiprosessi...3 3 Määrittelydokumentit...6 3.1 Integrointivaatimukset...7 3.2 Toiminnallinen liittymämäärittely...8 3.3 Tekninen liittymämäärittely...10 2.4 Liittymän toteutuksen kuvaus...11 4 Määrittelyjen hyväksyminen ja julkistaminen...11 Muutoshistoria: 7.10.2002 Ensimmäinen koottu ja kommentoitu luonnos, Juha Mykkänen, Juha Rannanheimo, Tomi Tikkanen / PlugIT 10.10.2002 Lisäkommenttien perusteella korjattu luonnos, Juha Mykkänen / PlugIT 22.10.2002 Työpajaseminaarin ja muiden kommenttien perusteella korjattu luonnos, Juha Mykkänen, Juha Rannanheimo, Tomi Tikkanen / PlugIT 25.10.2002 Ohjaajien kommenttien perusteella korjattu luonnos johtoryhmälle, Juha Mykkänen / PlugIT 2

3 1 Johdanto Tässä dokumentissa käsiteltäviä aiheita ovat integroinnin määrittelyprosessi sekä PlugIT-projektissa tuotettavien määrittelydokumenttien tuottaminen, julkaisu ja hyväksyminen. Tämä dokumentti kuvaa: 1. Mitä dokumentteja määrittelytyössä tuotetaan, 2. Miten dokumentit tuotetaan (ja miten projekti tukee niiden tuottamista), 3. Kuinka tehdyt määritykset hyväksytään ja levitetään. Tämän dokumentin lähteinä on käytetty soveltuvin osin integrointi- ja sovelluskehitysprosessia koskevaa kirjallisuutta sekä kehitetty uutta sovellusintegraation teoriaa, joita tässä pyritään soveltamaan käytäntöön ja keventämään käytännönläheisemmäksi projektin käyttöön soveltuvaksi menetelmäksi, joka ei vaadi erikoistuneiden välineiden käyttöä. Käytettyjä lähteitä ovat mm. Rational Unified Process RUP, OMG:n Model Driven Architecture MDA, ISO:n RM-ODP-malli, OMG:n standardointiprosessi, Integrating Healthcare Enterprise (IHE) -määritykset sekä projektin ja ulkopuolisten tutkijoiden tieteelliset artikkelit ja kirjat (dokumentin lopussa on viitteitä taustamateriaaliin). Tärkeä perusta dokumentille ovat myös eri yritysten ja terveydenhuollon organisaatioiden kanssa käydyt keskustelut. Myös projektissa jo tehdyn integroinnin toteutustyön dokumentaatiota sekä eri yritysten luovuttamia integraatiodokumentteja on käytetty pohjana. Dokumenttia ylläpidetään ja kehitetään edelleen ja siihen toivotaan kommentteja. Dokumentissa kuvattujen käytäntöjen arvioinnin tuloksia pyritään keräämään dokumentin käyttäjiltä. Uusin versio dokumentista on saatavilla projektin osapuolille sisäisten web-sivujen kautta. Kommentteja ja mielipiteitä voi lähettää esim. osoitteisiin Juha.Mykkanen@uku.fi, Tomi.Tikkanen@cs.uku.fi, Juha.Rannanheimo @kuh.fi. Myös projektin sähköpostilistoilla voi keskustella dokumenttia koskevista asioista. 2 Integrointiprosessi Integrointiprosessi kuvaa kuinka määrittelydokumentit tuotetaan sekä yleisesti (integrointimenetelmä) että erityisesti PlugIT-projektissa (projektikohtaiset käytännöt). Määrittelydokumenttien sisältöä käsitellään tarkemmin luvussa 3. PlugIT-projektin integrointiprosessin tavoitteita: Määrittelyissä pyritään "kolmikantayhteistyöhön": projektihenkilöt, th. organisaatiot ja yritys tai useita yrityksiä työstää määrittelyitä. Eri osapuolten näkökulmat yritetään aktiivisesti saada mukaan määrittelyihin. Määrittelyjen tuottamisen "keveys": on oltava helppoa saattaa prosessi alkuun ja tuottaa tuloksia. Eri vaiheissa voidaan "haarautua" tarkempaan määrittelyyn tai toteutukseen jollain osa-alueella. 3

4 Prosessiin on voitava tuoda "valmiiksi" yrityksissä tai terveydenhuollon organisaatioissa tehtyjä yhteentoimivuuden määrittelyitä (bottom-up) tai tuottaa toimintaprosessilähtöisen mallintamisen kautta uusia määrityksiä (topdown) tunnistettuihin integraatiotarpeisiin. Molemmissa määrittelyjen tuottamistavoissa pyritään yleistämään tuotettavia määrityksiä siten, että tuotokset ovat yleiskäyttöisiä, eivät tuotekohtaisia tai vain yhden yksikön toimintaprosessiin sidottuja. Tuotettavat määritykset ovat yleisten ja tilanteeseen soveltuvien standardien mukaisia sekä projektin sisällä eri integrointitarpeissa toisiaan tukevia. Sairaala tai muu th. organisaatio -substanssiosaaminen -pilotointikohde -käytetyt tekniikat -laatuvaatimukset PlugIT Prosessin kehittäminen -luettelo integraatiotarpeista -ohjeet määrittelyjen tekemiseen -sisältömäärittelyt määrittelydokumenteille -esimerkkejä määrittelyistä eri tyyppisiin integrointitilanteisiin -malliratkaisuja -toteutusvälineitä Projektisuunnitelma Ohjelmistoyritys Integraatiotarve Vaatimusmäärittely määrittelytyö -valmiita määrittelyitä -pilotointi -olemassa olevat tekniikat -oma laatu- ja tuotantoprosessi 1. INTEGRAATIO- VAATIMUKSET -tehdyn työn dokumentointi -arviointi -prosessin kehittäminen -yleistäminen -menetelmän validointi Liittymän määrittely Pilotointi määrittelytyö määrittely- ja toteutustyö 2. TOIMINNALLINEN LIITTYMÄ- MÄÄRITTELY 3. TEKNINEN LIITTYMÄ- MÄÄRITTELY 4. LIITTYMÄN TOTEUTUKSEN KUVAUS -tulokset Hyväksyntä -soveltaminen Kuva 1. Integraatiomäärittelyjen tuottaminen ja pilotointi PlugIT-projektissa. Tavoitteena on, että tämä osa (tai pikemminkin erillinen integrointiopas) kehittyy, kasvaa ja elää projektin edetessä. Projektissa tuotetaan eri vaiheisiin tarkalla tasolla ohjeita ja menettelytapoja, kuinka eri dokumentit sekä toteutukset valituilla tekniikoilla saadaan aikaan yhteistyössä eri osapuolten kanssa. Määrittelyjen tekemisen tarkka prosessi riippuu aina mukana olevien yritysten toiminta- ja laatukäytännöistä ja yksittäisten henkilöiden osaamisesta ja henkilökohtaisista preferensseistä, joten tämän dokumentin tässä osassa pyritään kuvaamaan vain yleiset pelisäännöt, joilla PlugIT-projektissa pyritään avointen liittymien määrittelyihin ja toteutuksiin. 4

5 Liittymän määrittely on yksi osa koko integrointiprosessia. Projektin osapuolet tuovat esiin integrointitarpeita, joiden perusteella päätetään mille tarpeille projektissa lähdetään määrittelyjä ja toteutuksia tekemään. Valituista integraatiotarpeista tuotetaan luvussa 3 kuvattavia dokumentteja, ja määrittelytyön jälkeen voidaan siirtyä liittymien toteutukseen. Vaiheet: Määrittelytyön aihe tulee joltakin projektin osapuolelta (sairaala/yritys), ja tiettyyn integrointitarpeeseen liittyvien osapuolten tunnistaminen ja mukanaolo on tavoitteena prosessin alusta lähtien. PlugIT-projektissa on tuotettu tärkeimpien tunnistettujen integrointitarpeiden luettelo. Valitaan koollekutsuja / vetäjä (projektista) ja alustavat osallistujat kirjataan. Kultakin osallistuvalta osapuolelta on yksi vastuuhenkilö mukana ("oikeat henkilöt mukaan"). Aihe ja alustava rajaus sekä mukana olevat osapuolet ilmoitetaan PlugITyhteys -listalla ja web-sivuilla. Muut osapuolet voivat ilmoittaa vetäjälle kiinnostuksensa tai osallistumishalunsa tehtävään määrittelyyn. Määrittely- (ja toteutus-, käyttöönotto-, testaus-) työstä tehdään projektisuunnitelma, joka on saatavilla projektin osapuolille o Projektisuunnitelman muoto määritellään tapauskohtaisesti, mutta sen tulisi sisältää suunnitelma rajauksesta, resursoinnista ja aikataulusta sekä tarvittaessa kuvaus muiden hankkeiden hyödynnettävistä tai niille tarjottavista tuotoksista. Määrittelyssä tuotetaan dokumentteja (luonnos), jotka sisältävät "Määrittelydokumentit" -luvun mukaiset asiat. Ensin voidaan tuottaa Integrointivaatimukset ja sitten muita dokumentteja, tai useita määrittelydokumentteja voidaan tuottaa kerralla. Jos osapuolia on useita, ne voivat tuottaa omia tai yhteisiä luonnoksia. Osapuolten yhteiset luonnokset ovat etusijalla. Projektin osapuolen aikaisemmin tekemä määrittely voidaan tuoda prosessiin luonnoksena. Määrittelyjen tuottamisessa voidaan seurata määriteltyä integrointiprosessia (Mykkänen, Porrasmaa ja Korpela, 2002): o Toiminnan ja sen kehittämisen vaatimukset otetaan huomioon. o Olemassa olevat järjestelmät otetaan huomioon toiminnallisuuden, arkkitehtuurin ja jo käytettyjen tekniikoiden osalta. o Toiminnalliset ja tekniset standardit otetaan huomioon. o Uusien tekniikoiden ja välineiden mahdollisuudet otetaan huomioon 5

6 -integrointivaatimukset -sovellusarkkitehtuuri -olemassaolevien sovellusten toiminnallisuus -sovellusten alusta 1. Kohdealueen analysointi 2.Sovellusarkkitehtuurin tunnistaminen 3. Olemassaolevien sovellusten tekniikoiden tunnistaminen 1. INTEGRAATIO- VAATIMUKSET standardit -toiminnalliset integrointipisteet -integrointipisteet kohdearkkitehtuurissa -semanttiset vaatimukset 4. Toiminnallisten liittymien tunnistaminen -teknologiariippumattomat liittymät 5. Liittymätekniikoiden valinta -olemassaoleva tekninen infrastruktuuri -tekniset standardit -uudet metodit, työkalut and teknologiat -uusi sovellusinfrastruktuuri -integrointiteknologiat 2. TOIMINNALLINEN LIITTYMÄ- MÄÄRITTELY 6. Liittymien määrittely 3. TEKNINEN LIITTYMÄ- MÄÄRITTELY -tekniset liittymät 7. Käytettävien teknologioiden valinta Kuva 2. Integrointimäärittelyjen tekeminen (liittymän määrittely). Määrittelyjen tuottamista tukemaan tarvitaan PlugIT-projektista: Selville saatujen integrointitarpeiden alustava luettelo Integration guidelines: ohjeet määrittelyjen tekemiseen Sisältömäärittelyn ohjeet eri määrittelydokumenteille (tavoitteena saada samoista dokumenteista tehtyjen toteutusten variaatiot määriteltyjen asioiden suhteen mahdollisimman pieniksi tai vähintäänkin dokumentoiduiksi) Määrittelydokumenttien tarkistuslista, näin dokumenttini on sellainen kuin pitääkin Esimerkkejä eri määrittelydokumenteista eri tyyppisiin integrointitilanteisiin, eri tekniikoille jne. Kartoitusta eri standardien kattamista alueista Jo tehtyjen ja käytettyjen määritysten varasto (ei samoja osia useilla tavoilla) Tietoa käytettävissä olevista kansallisista tai kv. luokituksista Koulutusta esim. puolivuotisseminaarien yhteydessä Vähitellen malliratkaisuja ja toteutusvälineitä ohjeineen (mahdollisimman paljon jo valmiiksi saatavilla olevia). Tukea tehtyjen määrittelyjen arviointiin ja tarkastukseen. Tukea eri osapuolten valmiiden määrittelyjen yleistämiseen prosessia varten. Tukea määrittelydokumenttien katselmointiin Tukea sovellusten määrittelyjen mukaisuuden testaamiseen 3 Määrittelydokumentit Tavoitteet: Määrittelyissä pyritään konkreettiselle tasolle: määrittelyn mukainen järjestelmien välinen liittymä pyritään toteuttamaan saatavilla olevien ohjelmistotuotteiden liittymäksi. 6

7 Yhteentoimivuuden toteuttamiseksi riittävän kattavien asioiden dokumentointi, mutta vain tarpeellinen määrä, jotta määritykset ovat suhteellisen kevyesti toteutettavissa. (tarkoituksenmukaisuus) Helppo liikkeellelähtö, asteittainen tarkennus teknistä toteutusta kohti Selkeiden mallien tarjoaminen määrittelydokumenteille Toteutuskohtaisten asioiden erottaminen liittymään liittyvistä asioista, vain tarpeellisten toteutuskohtaisten yksityiskohtien paljastaminen. Osapuolten omien laatuvaatimusten ja -järjestelmien huomiointi Tuotettavat määrittelydokumentit: 1. Integrointivaatimukset 2. Toiminnallinen liittymämäärittely 3. Tekninen liittymämäärittely 4. Liittymän toteutuksen kuvaus Tässä luvussa kuvataan määrittelydokumentteja, jotka ovat projektin pysyväluonteisia tuotoksia. Seuraavassa käsitellään kunkin määrittelydokumentin sisältöä tarkemmin. Näiden dokumenttien lisäksi voidaan tuottaa muita dokumentteja, esim. projektisuunnitelmia määrittelyjen toteutusta varten. Yleisiä dokumentointitapoja määrittelydokumenteissa: Järjestelmistä puhutaan yleisnimillä, ei erisnimillä, mutta esimerkkeinä käytetään nimeltä mainittuja järjestelmiä. Esimerkki: Patologian järjestelmä (esim. Qpati), potilashallinnon ydinjärjestelmä (esim. Musti). Dokumenteissa esitetään perustelut tehdyille valinnoille. Dokumenteissa kuvataan minimitaso ja kuvataan mitä ominaisuuksia minimitason (ja tarvittaessa muiden edistyneempien tai laajempien tasojen) mukainen järjestelmä toteuttaa. Määrittelydokumenttien uusissa versioissa on mahdollista tuottaa edistyneempiä tasoja olemassa oleviin määrityksiin. Dokumenteissa näkyvät dokumentin tuottamiseen osallistuneet tahot. Dokumentissa on versionumero. Viittaukset ylemmän tason dokumentteihin tehdään dokumentin nimen ja versionumeron (luonnoksissa voidaan käyttää päivämäärää versionumeron lisäksi) avulla. Integraatioprosessin eri vaiheissa syntyvät määrittelydokumentit voidaan PlugIT-projektissa hyväksyä (ks. luku 4). Ne voidaan myös tuoda julkisesti (muidenkin kuin projektin osapuolten) saataville johtoryhmän päätöksellä projektin aikana. Dokumentit ja kommentoitavaksi tuodut luonnokset ovat kaikkien projektin osapuolten saatavilla projektin web-sivujen kautta. 3.1 Integrointivaatimukset Integrointivaatimukset on pohjadokumentti, johon perustuvat myöhemmin tuotettavat dokumentit. Vaatimusdokumentti voi kattaa laajankin alueen vaatimuksia, josta valitaan tarvittaessa pienempi osa-alue kerrallaan jatkomäärittelyjä ja toteutusta varten. Integrointivaatimukset-dokumentti tehdään loppukäyttäjien ja integroinnin suunnittelijoiden ja toteuttajien yhteiseksi tavoitemäärittelyksi, joka on huomioitava 7

8 kirjoitettaessa (esim. välttämällä teknisiä yksityiskohtia ja määrittelemällä mahdollisesti sekaannusta aiheuttavat terveydenhuollon käsitteet). Tietyssä integrointitilanteessa voidaan pysähtyä jo vaatimusten kartoituksen jälkeen, jos toteutukseen tai jatkosuunnitteluun ei löydy toteuttajaa tai priorisoidaan toisten vaatimusten toteutus ensisijaiseksi (ks. Integrointiprosessi). Dokumentissa määritellään keskeisten määrittelyssä käytettyjen käsitteiden merkitys, ja mukana olevista järjestelmistä tai niiden osista käytettävät yleisnimet. Mihin toiminnan tarpeeseen pyritään vastaamaan o Toiminnan tai prosessien kehittäminen o Järjestelmissä jo oleva toiminnallisuus Mitkä järjestelmät osallistuvat / voivat osallistua Mitä standardeja halutaan ottaa huomioon / hyödyntää Esim. käyttötapaus- tai aktiviteettikaavioita käyttötilanteesta, eri järjestelmien toiminnallisuudesta ja toimintaprosesseista Avoimuus-, siirrettävyys- ja ylläpidettävyysvaatimukset Suorituskyky-, turvallisuus-, ja muut laatuvaatimukset o nämä vaatimukset tulisi esittää siten, että toteutuksessa ja sen kuvauksessa voidaan niihin realistisesti vastata Tarvittaessa aikatauluvaatimukset Tarvittaessa riippuvuudet muista hankkeista, varautuminen muiden hankkeiden tuotosten hyödyntämiseen ja tuotosten tarjoaminen muille hankkeille 3.2 Toiminnallinen liittymämäärittely Toiminnallinen liittymämäärittely -dokumentteja voi olla useita yhtä integrointivaatimukset-dokumenttia kohti, jos vaatimusdokumentissa on laaja kokonaisuus. Toiminnallinen liittymämäärittely viittaa yhteen integrointivaatimukset-dokumenttiin. Toiminnallisessa määrittelydokumentissa keskitytään toiminnalliseen (käyttäjän tai kokonaisoptimoinnin) näkökulmaan, mutta myös olemassa olevien sovellusten toiminnallisuus ja niissä käytetyt arkkitehtuuriratkaisut saavat näkyä jonkin verran toiminnallisessa määrittelyssä. Pyrkimys on kuitenkin siihen, että eri tekniikoilla ja arkkitehtuureilla toteutetut sovellukset voivat noudattaa samaa toiminnallista liittymämäärittelyä. Toiminnallinen liittymämäärittely on integrointivaatimusten tavoin integroinnin tilaajien (myös loppukäyttäjien) sekä suunnittelijoiden ja toteuttajien yhteinen kommunikointiväline. Vaikka siinä kuvataan integroinnissa käytettävää tietosisältöä ja operaatioita, tulee kuvauksen olla ymmärrettävää myös ei-teknisille osallistujille. Toiminnallinen liittymämäärittely pyrkii vastaamaan yhteen selkeästi rajattuun integrointitarpeeseen Kuinka integraatio näkyy järjestelmän loppukäyttäjälle 8

9 o Esim. pitääkö/voivatko ratkaisut sisältää ohjelmointirajapinnan lisäksi käyttöliittymän Millainen yhteistoiminnallisuus on kyseessä o sovellusten välinen koordinointi o tiedonsiirto tai ohjelmistopalvelun kutsu työasemalla o tiedonsiirto tai ohjelmistopalvelun kutsu verkon yli o käyttöliittymän kutsuminen työasemalla o web-käyttöliittymän kutsuminen Onko ratkaisujen oltava verkon kautta käytettävissä Voiko ratkaisussa sallia/vaatia esim. että eri järjestelmät on asennettu samalle työasemalle Katettujen tieto- tai toimintokokonaisuuksien nimet Sovellusten vastuut eri tieto- ja toimintokokonaisuuksista o Sisältääkö toteutus esim. myös kaiken sisäisen datansa vai tarjoaako vain rajapinnan muualla olevaan dataan Voidaan käyttää Esim. UML:n aktiviteetti- ja sekvenssikaavioita integrointitilanteen vuorovaikutuksesta Viittauksia toiminnallisiin standardeihin ja valmiisiin määrityksiin o HL7-viestisisältö, EPR-sisältömääritykset, OMG-standardit/vastaavat, jne. Koodistojen käyttö, mitä asiaan liittyviä koodistoja ja niiden versioita on saatavilla / käytetty o esim. Laboratoriotutkimusnimikkeistö, ICD-luokitukset, ISO, JHS (esim. Kuntalistaus), toimittajakohtaiset koodistot, SNOMED, LOINC, kans. th. projektin luokitukset Nojautuminen aikaisempaan työhon (PlugITin jo tehdyt määritykset, muiden projektiosapuolten tarjoamat valmiit määritykset) o Tarvittavat ja saatavilla olevat lisäpalvelut (turvallisuus ym.) palvelut Vaihtoehtoisia integrointitapoja: o koordinaattorin käyttö - esim. CCOW o API-rajapinnan kautta tiedonsiirto paluuarvo sisältää käytettävää tietoa joko siten, että nojaudutaan siihen että palvelu on aina saatavilla (esim. kutsuva järjestelmä ei itse sisällä tietoa), tai voidaan sallia samojen tietojen kopiointi osallistuviin järjestelmiin o API-rajapinnan kautta käyttöliittymän kutsuminen suoritetaan toisen järjestelmän "ulokkeella" jokin toimenpide, paluuarvo sisältää tietoa suoritetun toimenpiteen onnistumisesta o yhteisen tietovaraston käyttö - tiedot ovat vain yhdessä paikassa, esim. kertomusarkiston liittymä o (luotetun sovelluksen käyttö turvallisuusintegroinnissa) o (sanomapohjainen HL7/XML-liittymä) - ei PlugIT-projektin kohteena Halutut suorituskyky- ja muut laatuominaisuudet voidaan dokumentoida jo tässä vaiheessa. 9

10 3.3 Tekninen liittymämäärittely Tekninen liittymämäärittely -dokumentteja voi olla useita yhtä toiminnallista liittymämäärittelyä kohti, jos samoja toiminnallisia liittymiä halutaan toteuttaa eri tekniikoilla. Jokainen tekninen liittymämäärittely viittaa yhteen toiminnallinen liittymämäärittely -dokumenttiin. Valmis tekninen liittymämäärittely toimii suunnitteludokumenttina ja teknisenä sopimuksena integroinnin toteuttajille (sekä palvelun toteuttaja että hyödyntäjä) toteutettavan liittymän suhteen. Se kuvaa myös tilaajan teknisille asiantuntijoille käytettävät integrointitekniikat ja tekniset ratkaisut. Eri teknisissä liittymämäärittelyissä pyritään käyttämään pohjana ja toteutuksessa mahdollisimman paljon samoja teknisiä osia ja esim. samoja XML-merkkauksia ja HL7-määrittelyjä Sovellusten tekniset vastuut Valitut liittymätekniikat, tekniset standardit PlugIT-projektissa syntyy mallitapauksia sekä ohjeita tyypillisistä teknisistä toteutuksista (voi avustaa liittymien määrittelyssä ja toteutuksessa). Kolme perusliittymätapaa tullut ilmi tähän mennessä (ks. myös PlugITprojektin selvitys tekniikkaperheistä, jossa asiaa käsitellään tarkemmin): o työasematason komponenttirajapinta sisältää aina API-liittymän (tai vastaavan web-mekanismin) voi sisältää käyttöliittymän, ei sisällä välttämättä on kuvattava myös mekanismi, jolla palvelun käyttäjä saa selville onko tietty palvelu ja sen versio saatavilla Käytettävissä olevia teknisiä vaihtoehtoja: Windows dll (Dynamic Link Library) JavaBeans websivu-tekniikat (JSP, ASP, cgi jne.) COM/ActiveX-komponentti o työpöytäintegraation rajapinta standardiin perustuva rajapinta, jonka mukaiset sovellukset voivat noudattaa koordinaattorikomponentin ohjaamaa yhteistoimintaa Windows- tai web-pohjaisissa järjestelmissä. CCOW Context Manager muu työpöytäintegraation määritys o palvelinintegraation rajapinta verkon yli hajautetusti kutsuttava palvelu, joka toteutetaan hajautetulla tekniikalla web services EJB CORBA COM websivu-tekniikat (JSP, ASP, cgi, esim. xml-sivu) sisältää aina API-liittymän ei sisällä käyttöliittymää loppukäyttäjälle Valittujen liittymätekniikoiden vaatima LIITTYMÄN tekninen infrastruktuuri Valittua tekniikka käyttäen API-dokumentaatio 10

11 Jokaisen operaation, tietoelementin, merkkauksen ja paluuarvon merkitys ja muoto (esim. Etunimi Sukunimi), tarvittaessa myös maksimipituus tai toiminta jos arvo on tyhjä Virheilmoitukset ja virhetilanteiden hallinta, esim. jos palvelu ei olekaan käytettävissä, toteutetun version selville saanti Mahdollinen eri operaatioiden kutsujärjestys 2.4 Liittymän toteutuksen kuvaus Toteutuksen kuvauksia voi olla useita yhtä teknistä määrittelyä kohti, esim. jokaiselle tuotteelle joka toteuttaa palvelun. Toteutuksen kuvaus viittaa yhteen tekninen liittymämäärittely -dokumenttiin ja on toteutus- tai tuotekohtainen. Toteutuksen kuvaus on tarkoitettu helpottamaan tietyn teknisen liittymän toteuttavien tuotteiden arviointia, käyttöönottoa, asennusta ja ylläpitoa. PlugIT-projektissa voidaan todeta toteutuksen kuvaus-dokumentin olevan toteutuksen dokumentoinnin vaatimusten mukainen, muuten muoto ja sisältö ovat vapaasti toteuttajan päätettävissä. Toteutuksista tulee kuitenkin dokumentoida tässä luetellut asiat. Ei sisällä tarkkaa toteutuksen kuvausta, vaan yhteentoimivuuteen ja asentamiseen liittyvät asiat tarkalla tasolla toteutetussa ratkaisussa TOTEUTUKSEN vaatima tekninen infrastruktuuri (esim. RPC Brokerpalvelin, sovellus X asennettuna työasemalle, käyttöjärjestelmäriippuvuudet, asennetut päivityspaketit eri ympäristöissä) Tuote- tai komponenttikohtainen konfigurointi o esim. palvelun kutsuosoitteen välittäminen toteutukselle, käytettävän dll-tiedoston nimen välittäminen, käyttöliittymän mukauttaminen ulkoisten parametrien avulla, tarjottavat lisäpalvelut Toteutuksen siirrettävyys eri ympäristöihin, jakelumekanismit Toteutuksen rajoitteet (esim. maksimipituudet tietokentille tai elementeille, jollei niitä ole määritelty ylemmän tason dokumenteissa) Suositeltavaa on, että toteutuksen kuvaus sisältää esimerkkitapauksia tarjotun ratkaisun käytöstä, ohjeita ratkaisun käytön (esim. tarjottua palvelua käyttävän osan) toteuttamiseen jne. Dokumentti kuvaa suorituskyky- ja muiden laatuvaatimusten toteutuminen, jos ne on dokumentoitu edellisissä vaiheissa. Dokumentti kuvaa lisäykset muissa määrittelydokumenteissa tehtyihin määrittelyihin, esim. toteutuksen verkkoliikenteen salauksessa käytetyn ratkaisun, jota ei ole määritelty liittymän teknisessä kuvauksessa. Toteuttajan tukipalvelut, yhteystiedot. 4 Määrittelyjen hyväksyminen ja julkistaminen Tavoitteita: määrittelyjen ja liittymien avoimuus, mutta tuotteiden sisäisten yksityiskohtien ja kilpailuetujen suojelu 11

12 riittävä keveys yksittäiseen projektiin riittävä formaalius, jotta työtä voidaan jatkaa projektin jälkeen esim. sopivassa standardointiorganisaatiossa julkistusleima" - takuu avoimuudesta hyväksyntäleima" - takuu projektin osapuolten sitoutumisesta Projektissa tehdään toteutuksia ja tarkennetaan määrityksiä etupäässä tehtyjen luonnosten perusteella, eli esim. avoimia rajapintoja tuotteisiin voi syntyä ilman yllä olevien leimojen käyttöä. Hyväksymis- ja julkistamisprosesseja käynnistetään suhteellisen harvoin (esim. puolivuosittain), tai kun on tarpeen tehdä virallisempaa hyväksyntää. Määrittelydokumentit voivat käydä läpi seuraavat vaiheet, tai vain jotkin niistä: LUONNOS laitetaan projektin jäsenten saataville kommentointia varten, ja kommentointia varten asetetaan takaraja o kommentoida voi esim. sähköpostin avulla, ja kuka tahansa projektin osapuoli voi kommentoida Saatujen kommenttien perusteella voidaan tehdä korjauksia luonnokseen, ja luonnosten perusteella tuotetaan tarkempia jatkodokumentteja ja toteutuksia, ilman että odotetaan luonnosten projektin laajuista hyväksyntää (ks. seur.). Integrointivaatimukset sekä Toiminnallinen ja Tekninen liittymämäärittely -dokumenteista hyväksymistä varten tehty luonnos tuodaan projektin osapuolten saataville (www-sivuille) ja hyväksymistä ja kommentointia varten asetetaan takaraja. Projekti ilmoittaa kaikille osapuolille hyväksymisäänestyksestä. Takarajaan mennessä osapuolten edustajat voivat ilmoittaa kannattavansa luonnoksen hyväksymistä, äänestää tyhjää tai ilmoittaa etteivät kannata luonnoksen hyväksymistä. Luonnoksesta tulee HYVÄKSYTTY määrittely, jos takarajaan mennessä ei ole tullut kielteisiä ilmoituksia ja on tullut hyväksyttyjä ilmoituksia. Jos jokin osapuoli ei ilmoita takarajaan mennessä myönteistä tai kielteistä kantaa hyväksymiseen, on osapuoli äänestänyt tyhjää. Jos samasta aiheesta on useita luonnoksia, pyritään luonnokset sulauttamaan yhteen ennen hyväksyntää (tai tuottamaan esim. samasta toiminnallisesta liittymämäärittelystä eri tekniikoille teknisiä liittymämäärittelyitä). Eri luonnosten priorisoinnissa pyritään vastaamaan ensisijaisesti käyttäjätarpeisiin. Jos hyväksymisäänestyksessä oleva dokumentti ei ole relevantti projektin osapuolen kannalta (esim. tekninen määrittely tekniikalla, jota osapuoli ei käytä tai aio käyttää), on suositeltavaa äänestää tyhjää (esim. jättämällä äänestämättä ko. dokumentin suhteen). Toteutuksen kuvaus-dokumentteja ei hyväksytä erikseen, vaan riittää että ne ovat saatavilla projektin kautta ja asetettujen dokumenttikriteerien mukaisia. Hyväksymisäänestystä ei käynnistetä jokaisen hyväksyttäväksi tarkoitetun luonnoksen valmistuessa, vaan esim. määräajoin (1-2 kertaa vuodessa tai jos on erityinen syy käynnistää äänestys), ja samassa äänestyksessä pyritään hyväksymään useita tehtyjä luonnoksia. Hyväksytyssä määrittelyssä on lukkoon lyöty versionumero. Siitä poistetaan sana "Luonnos". Määrittelystä tulee JULKINEN, kun projektin johtoryhmä on hyväksynyt määrityksen julkaisemisen vapaasti saataville. o Projektisopimuksen mukaan johtoryhmä hyväksyy yksimielisesti 12

13 Tuotteet: Määrittelystä tulee TOTEUTETTU, kun määrityksen mukainen liittymä löytyy ainakin yhdestä käyttöympäristöön asennetusta tuotteesta, tuotteen toimittaja on ilmoittanut käyttöönotosta ja toteutuksen kuvaus on saatavilla. Tuotteesta tulee MÄÄRITTELYÄ NOUDATTAVA, jos voidaan varmistua siitä, että se toimii määrittelydokumenttien mukaisesti ja yhdessä muiden määritystä noudattavien tuotteiden kanssa o määrittelyjen mukaisuuden testausta voidaan kehittää PlugITprojektissa Luonnoksista, hyväksytyistä, julkisista tai toteutetuista määrityksistä voidaan tehdä uusien versioiden luonnoksia. Uusien versioiden dokumentoinnissa on kuvattava onko versio taaksepäin yhteensopiva, muutokset ja laajennukset edellisiin versioihin jne. PlugIT-projektin sisäisillä web-sivuilla ovat kaikki projektissa tehdyt määrittelydokumentit, projektisuunnitelmat ja niiden kommentoitavaksi tarkoitetut luonnokset. Eri dokumenteista näkyy selvästi onko se luonnos, hyväksytty tai julkistettu. Määritysten yhteydessä näkyy, mitkä tuotteet ovat toteutettu tai määrittelyä noudattava-tilassa. Julkiset määrittelydokumentit laitetaan projektin julkisille web-sivuille saataville Projektin johtoryhmä voi päättää kenelle tehty (sekä kesken oleva) työ siirretään projektin jälkeen. Taustamateriaalia: OMG Model Driven Architecture MDA: ftp://ftp.omg.org/pub/docs/ab/01-03-02.pdf ISO RM-ODP: ftp://ftp.dstc.edu.au/pub/dstc/arch/rm-odp/pdfdocs/part1.pdf Rational Unified Process: http://www.rational.com/media/whitepapers/rup_bestpractices.pdf OMG Standardization process: http://www.omg.org/gettingstarted/processintro.htm Mykkänen J, Porrasmaa J, Korpela M: A process for specifying integration for multi-tier applications in healthcare. In: Surján G, Engelbrecht R, McNair P, eds. MIE 2002. Proceedings of the 17th International Congress of the European Federation of Medical Informatics. [Budapest], [25-29 August 2002], p. 691-696. Amsterdam: IOS, 2002. Saatavilla projektin sisäiseen käyttöön PlugIT-projektin yhteyshenkilöiden web-sivuilta: http://www.uku.fi/atkk/plugit/ Component and Service Technology families. PlugIT-projektin selvitys. Luku 8.3: Selecting technologies for integration. Luonnos saatavilla projektin sisäiseen käyttöön PlugIT-projektin yhteyshenkilöiden web-sivuilta: http://www.uku.fi/atkk/plugit/ 13