Ydinpalvelurajapinnat (käyttäjä, käyttöoikeus, potilas): Tekninen liittymämäärittely http- ja XML-tekniikoilla Versio 2.

Transkriptio

1 Ydinpalvelurajapinnat (käyttäjä, käyttöoikeus, potilas): Tekninen liittymämäärittely http- ja XML-tekniikoilla Versio alustava PlugIT-projekti, Ydinpalvelurajapinnat Yhteyshenkilö: Marko.Sormunen@uku.fi Versio alustava

2 2 SISÄLLYS 1 JOHDANTO KESKEISET KÄSITTEET RAJAUS MIHIN VAATIMUKSIIN JA TOIMINNALLISIIN MÄÄRITTELYIHIN LIITTYY TEKNIIKOIHIN KOHDISTUVAT VAATIMUKSET TEKNISEN MÄÄRITTELYN PERUSRATKAISU ARKKITEHTUURI TEKNIIKKA TOIMINNALLISET JA TEKNISET STANDARDIT JA MÄÄRITYKSET SEKVENSSIKAAVIOT RAJAPINTOJEN KÄYTÖSTÄ OPERAATIOIDEN JA TIETOSISÄLLÖN TEKNISET MÄÄRITTELYT AUTHENTICATEUSER AUTHORIZATIONACCESS IDENTIFYPROFILE JA PROFILEACCESS PATIENT:IDENTIFYPROFILE JA PATIENT:PROFILEACCESS POTILAASEEN LIITTYVÄT PERUSTIEDOT KÄYTTÄJÄÄN LIITTYVÄT PERUSTIEDOT VIRHEKOODIT JA NIIDEN ARVOT TOTEUTUSKOHTAISEKSI JÄTETTÄVÄT ASIAT MÄÄRITTELYJEN MUKAISUUDEN TOTEAMINEN...20 LIITE 1: OPERAATIOIDEN JA TIETOSISÄLLÖN TEKNISET MÄÄRITTELYT...22 AUTHENTICATEUSER...22 AUTHORIZATIONACCESS...28 IDENTIFYPROFILE...30 PROFILEACCESS...34

3 3 Versio: Pvm: Laatijat: Muutokset: Luonnos_ Marko Jäntti Dokumentin pohja Luonnos_ Marko Jäntti Täydennyksiä koko dokumenttia koskien Luonnos_ Juha Rannanheimo Täydennyksiä koko dokumenttia koskien kommenttien pohjalta Luonnos_ Juha Rannanhei- Täydennyksiä koko dokumenttia koskien kom- mo Luonnos_ Juha Rannanheimo & Marko Sormunen menttien pohjalta Lisätty sekvenssikaaviot rajapintojen käytöstä ja pieniä korjauksia Luonnos_ Marko Sormunen Päivitetty PlugIT-puolivuotisseminaarin pohjalta Luonnos_ Marko Sormunen lisää päivityksiä jokaiseen kappaleeseen. Luonnos_ Marko Sormunen PlugIT-yhteys listalle tieto dokumentista ja kommentointipyyntö Luonnos_ Marko Sormunen Puolivuotisseminaarin jälkeisten PlugITosapuolten kommenttien muutokset dokumenttiin, lähinnä muutoksia potilaan perustietojoukkoon ja check_authorization metodiin. Lisäksi autentikaatiometodeihin lisättiin environment-attribuutti, jolla voidaan määrätä käyttäjän sisäänkirjautuiskohdeympäristö (esim. testi- tai tuotantoympäristö) V Johtoryhmä Hyväksyttiin muutoksitta. Luonnos_ Marko Sormunen * Metodien nimiä muutettu enemmän kontekstinhallinta-palvelun mukaisiksi, esim. find_candidates => FindCandidates * Virhekoodit uudelleen määritelty kontekstinhallinta-palvelun ja PIDS-palvelun mukaisiksi. * Päivityksiä AuthenticateUser-palvelun määrityksiin * getcoupon() metodin palauttaman kupongin on oltava aina ainutlaatuinen. Luonnos_1.x Marko Sormunen * Lisätty uusi virhekoodi: CouponNotAuthenticated * Muutettu max_records-attribuutti ei-pakolliseksi * Tarkennettu FindCandidates metodin toimintaa Luonnos_1.x Marko Sormunen * Lisätty uusi virhekoodi NotImplemented tulevaisuuden laajennuksia varten * Lisätty uusi metodi getsubject() AutenticateUser-rajapintaan * Muutettu ominaisuudet kotiosoite => koti, tyoosoite => tyo * HUOM! Rajapinnat on oikeastaan nimetty hieman virheellisesti, koska Y4-kohteen pitäisi olla pikemminkin perustiedot, eikä potilas, koska samaa rajapintaa käytetään myös käyttäjän perustietojen hakemiseen. Luonnos_1.x Marko Sormunen * Muutettu error-elementit exception-elementiksi ja elementin value-attribuutti exceptionmessageattribuutiksi (seuraamaan kontekstipalvelun minimimääritystä). Luonnos_1.x Marko Sormunen * poistettu application-elementti login() metodin parametridokumentista * kaikki metodit ottavat parametrina Requestdokumentin ja palauttavat Response-dokumentin * muutettu elementtien nimeämiskäytäntöä enemmän XML-standardimmiksi, esimerkiksi <request /> ja <maxrecords../>

4 4 Luonnos_1.x Marko Sormunen * login() ja getsubject() metodit palauttavat subject-elementin Luonnos_1.x Marko Sormunen * requestedtrait elementti muutettu trait elementiksi * GetProfile() ym. profiileja käsitteltvät metodit ottavat parameteinä profile-elementin (aikaisemin person-elementti). * trait elementit ovat nyt profile elementin sisällä. * queriedtrait elementit ovat nyt omassa query- Profile-elementissään ja myös nimetty traitelementeiksi. * sortedbytrait elementti muutettu sortbytrait elementiksi * updateandcleartraits metodi muutettu update- Profile metodiksi * getprofilelist metodi yhdistetty getprofile metodin kanssa (usea profile id (esim. hetu) voidaan antaa yhdellä kertaa). Luonnos_1.x Marko Sormunen * queryprofile-elementti sisältää kaiken haussa tarvittavan ominaisuustiedon. * UpdateProfile() metodi ottaa parametriksi updateprofile-elementin * subject-elementti sisältää profile-elementin (oli person-elementti) Luonnos_1.x Marko Sormunen * Kaikkiin kutsudokumentteihin lisätty interface ja method elementit joilla kutsuttu metodi tunnistetaan. Samalla kaikki kutsujen ylin elementti on nyt request. * Kaikki parametrit itse palvelumetodeille on param elementin sisällä. * Attribuutit muutettu elementeiksi kaikissa metodeissa, paitsi id-attribuutit.tällöin elementteihin voidaan lisätä helpommin namespace määritykset jatkossa. * limits elementti poistettu Luonnos_1.x Marko Sormunen * IdentifyPerson nimetty IdentifyProfile rajapinnaksi. Ajatuksena on, että palvelut voivat käsitellä profiileja, eikä potilaita tai henkilöitä. Profiili voi tarkoittaa mitä tahansa ominaisuusjoukkoa. * IdentifyProfile rajapinnan metodit käsittelevät candidate elementtejä eikä profiileja. Luonnos_1.x Marko Sormunen * Merkkikoodaukseksi suositellaan UTF-8:ia ISO :n sijasta. Luonnos_1.x Marko Sormunen * Lisätyt oletusnimialue xmlns= urn:plugit:commonservices erimerkkeihin. Luonnos_1.x Marko Sormunen * poistettu ClinicalAccess rajapinta, virheilmoituksia tarkennettu Luonnos_2.0 alustava Marko Sormunen * lisätty CheckCoupon metodi Authenticate- User-rajapintaan. Luonnos_2.0 alustava Marko Sormunen * tarkennettu Logout- ja CheckCoupon metodien toimintaa.

5 5 1 Johdanto Tämä dokumentti on tekninen liittymämäärittely PlugIT:n ydinpalvelurajapinnoille http- ja XML-pohjaisena ratkaisuna. Teknisessä liittymämäärittelyssä kuvataan, mitä tekniikoita järjestelmien välisen liittymän toteutuksessa käytetään, järjestelmien toisilleen tarjoamat toiminnot ja yhteistoimivuuteen liittyvä tietosisältö näillä tekniikoilla. Ydinpalvelut- ja Työpöytäintegraatio-kohteissa on siirrytty http-pohjaiseen viestintään ja Web services tyyppiseen palveluarkkitehtuuriin. Toteutusta on tarkoitus pilotoida, jolloin rakennetaan http-viestien avulla käytettävät palvelukomponentit. Pilotointiympäristössä pyritään aluksi toteuttamaan alla mainituista kohteista käyttäjä-rajapinta, käyttöoikeusrajapinta ja potilaan perustietojen hakurajapinta (alla merkitty vahvennettuna). Tässä liittymämäärittelyssä ovat mukana seuraavat PlugIT-kohteet, joiden on suunniteltu hyödyntävän HTTP/Web Services-arkkitehtuuria: - Käyttäjä (AuthenticateUser, User:ProfileAccess) Organisaatio - Käyttöoikeus (AuthorizationAccess) - Potilas (Patient:IdentifyProfile, Patient:ProfileAccess) - Henkilö (Person:IdentifyProfile, Person:ProfileAccess) - Kliiniset tiedot - Koodisto 2 Keskeiset käsitteet Ydinjärjestelmä Sovellus Sairaalan potilashallinnon järjestelmä, jossa ylläpidetään yleensä keskitetysti kaikkia tärkeimpiä tietoja, potilastietoja, ajanvaraustietoja, yms. Mikä tahansa terveydenhuolto-organisaation tietojärjestelmäkokonaisuuden osa, joka on tarkoitettu tietyn erityisen osatoiminnan tukemiseen. Voi olla erillinen kliininen tai potilashallinnollinen sovellus tai osa laajempaa kokonaisjärjestelmää, kertomusjärjestelmä, portaali, aluetietojärjes-

6 6 Sisäänkirjaus Autentikaatio, todentaminen Potilaan perustiedot Http-keskustelija Http-yhteyskomponentti Palvelutoteutus Palvelurajapinta WWW-palvelin telmä, yms. Toimenpide, jota tarvitaan päästäkseen käyttämään jonkun tietokonejärjestelmän palveluja. Menettely, jolla varmennetaan käyttäjän tai laitteen tunnistaminen tai tiedonsiirtona lähetetyn sanoman alkuperäisyys. Esimerkiksi käyttäjän tunnistaminen voidaan todentaa salasanan avulla. Potilaskohtaiset henkilötiedot ja yhteystiedot Esimerkiksi WWW-palvelin tai muu yksinkertaisempi komponentti joka osaa vastaanottaa http(s)-viestejä ja palauttaa vastauksen kutsujaosapuolelle. Komponentti tai muu vastaava ohjelmakirjasto (liitin), joka osaa lähettää http(s)-sanoman ja vastaanottaa palautetun viestin. Ohjelmakomponentti, luokka tai muu kokonaisuus, joka sisältää itse palvelun toteutuksen eli toteuttaa palvelurajapinnan. PlugIT:in kannalta työpöytäintegraatio-kohteessa palvelutoteutus olisi kontekstin hallintapalvelu ja potilaskohteessa potilaan perustietojen hakupalvelu. Ohjelmistorajapinta, jonka kautta sovellus tarjoaa ohjelmistopalveluita (operaatioita, suorittaa tehtäviä) toiselle sovellukselle WWW-palvelin, joka jakelee ja ylläpitää Websovelluksien sivuja. 3 Rajaus mihin vaatimuksiin ja toiminnallisiin määrittelyihin liittyy Tekniset liittymämäärittelyt perustuvat seuraaviin dokumentteihin: integraatiovaatimukset.doc teknriippumaton_maarittely_v10.doc

7 7 4 Tekniikoihin kohdistuvat vaatimukset Tekniikan tulee mahdollistaa hajautettu rajapinta eli palvelua (esim. potilaan perustietoja) tarjoava sovellus sisältää palvelinosan (Server), johon asiakas (Client) ottaa yhteyden verkon yli. Palvelinosa voi sijaita esimerkiksi webpalvelimella. Tekninen ratkaisu on asiakkaan kannalta synkronoitua toiminnallisuutta, jossa palvelun pyytäjä jää odottamaan vastausta palvelinosalta, joka palauttaa vastauksen välittömästi. Palvelun toteuttajan (palvelinosan) on kuitenkin kyettävä ottamaan vastaan useita yhtäaikaisia tai peräkkäisiä kutsuja eri asiakkailta. Palvelujen (URL-muotoisen) kutsuosoitteen pitää olla parametrisoituna sovelluksessa. Ratkaisujen on oltava liitettävissä ainakin sekä Windows-työasema- että webpohjaisiin sovelluksiin, joissa voi olla toteutuskielenä myös Java. Pilotoinnissa käytettävissä sovelluksissa on käytetty client/server pohjaisia tekniikoita ja Windows-työasematekniikoita. Varsinkin siirtyminen Web-ympäristöön aiheuttaa lisävaatimuksia turvallisuuden suhteen, esimerkiksi ydinpalveluja käyttävien työasemien erottaminen toisistaan vaikeutuu huomattavasti ja vaatii lisätoiminnallisuutta. Tässä dokumentissa esitetyt rajapinnat määrittävät turvallisuuden suhteen ns. minimitason, jossa oletetaan palveluja käyttävien työasemien sijaitsevan samassa suojatussa sisäverkossa (intranet), jolloin ne voidaan erottaa toiststaan IPosoitteen perusteella. Jatkossa on tarkoitus määritellä turvallisuuteen lisätasoja ja rajapinta, jolla autentikaatio tapahtuu turvallisisesti esimerkiksi Internet-ympäristössä. 5 Teknisen määrittelyn perusratkaisu 5.1 Arkkitehtuuri Potilashallinnon ydinjärjestelmä tarjoaa palvelun, jolla sovellukset voivat hakea tarvittavan tietosisällön dokumenttipohjaisesti verkkoyhteyden yli. Tällöin palvelua käyttävä sovellus voi sijaita joko käyttäjän työasemalla tai palvelimella (Kuva 1).

8 8 Kuva 1: Palveluarkkitehtuuri Palvelua käyttävä sovellus kutsuu palvelun toteutuksen tarjoamia operaatioita http-protokollan ja XML:llä määritellyn tietosisällön avulla. Palvelun toteutus muodostuu http-palvelimesta (esim. web-palvelin) sekä palvelun sisällöstä vastaavasta sovelluksesta. Palvelua käyttävissä sovelluksissa on tieto siitä, missä osoitteessa palvelun toteutus on, ja niihin on toteutettu http-yhteyttä hyödyntävä osa tai sovitin, joka ottaa yhteyttä palvelun toteutukseen. Palvelun osoite voidaan myös parametrisoida sovellukseen tarvittaessa. Sovellus voi tehdä palvelukutsun itse tai sen voi hoitaa erillinen palvelun tarjoajan rakentama http-yhteyskomponentti (liitin), joka kapseloi palvelurajapinnan

9 9 käytön. Palvelua käyttävässä sovelluksessa tai liittimessä huolehditaan tarvittavien parametrien asettamisesta palvelupyyntöihin sekä tulleiden vastausten käsittelystä. Palvelutoteutuksen rajapinta toimii kokonaisuudessaan synkronisella kyselyvastaus periaatteella. Se tarkoittaa sitä, että palvelu vastaa yhteen kyselyyn (ts. palvelun jonkun operaation kutsumiseen) kerrallaan välittömästi yhdellä vastauksella. Itse palvelut suunnitellaan toimivaksi siten, että ne voivat ottaa tilattomuudestaan johtuen palvelukutsuja vastaan ilman jonoa. 5.2 Tekniikka Viestinvälityksessä käytetään teknisenä standardina HTTP-protokollaa ja palvelukutsut suositellaan lähetettävän sen POST-metodilla. HTTP -protokolla on yksinkertainen hajautettujen palvelujen kutsuun soveltuva tekniikka. Se on laajassa käytössä oleva www-tekniikka. XML on samoin yleinen ja avoin www-tekniikka, jolla voidaan paketoida ja kuvata käsiteltävä tietosisältö palvelupyynnöissä ja vastauksissa. Viestien koodauksessa suositellaan käyttämään UTF-8 koodausta, joka on määritelty oletuskoodaukseksi useissa W3C:n XML:än liittyvissä standardeissa. Kutsujen parametrien ja paluuarvojen kapseloiminen on toteutettu XMLmuotoisina parametri- ja paluuarvodokumentteina. Toisin sanoen kaikki kutsut ottavat vastaan parametrina XML-dokumentin, jossa on elementteinä ja attribuuteilla kuvattu kutsun muuttujat ja kaikki kutsujen paluuarvot on myös esitetty niin ikään XML-dokumentteina. XML tarjoaa myös mahdollisuuden laajentaa määriteltyä tietosisältöä esim. siirrettävien tietojen suhteen. Virhetilanteet esitetään myös XML-dokumentteina. Käytännössä yksittäiset virhetilanteet esitetään exception-elementteinä, joissa on id-attribuutti tunnistamassa virheen tyyppiä ja exceptionmessage-attribuutti kuvaamassa virheen tekstimuotoista selitystä. Nämä elementit ovat osana kutsujen paluu-xmldokumenttia.

10 10 PlugIT-projektissa on tarkoitus määrittää erillinen virhelista, joita PlugITrajapintoja toteuttavat palvelut voivat palauttaa. 6 Toiminnalliset ja tekniset standardit ja määritykset PlugIT pyrkii hyödyntämään tietosisällön määrittelyissä ulkoisia, valmiita määrittelyitä tai kuvaamaan laajennettavia minimitietojoukkoja, ja tässä dokumentissa keskitytään toimintojen ja teknisten ratkaisujen määrittelyyn. OMG:n Person Identification Service (PIDS)-standardia käytetään toiminnallisena standardina, mutta sen tekniikoita (CORBA, IDL) ei käytetä. CDAstandardia käytetään sekä toiminnallisena (elementtien nimet) että teknisenä standardina (XML-merkkaukset kliinisissä tietojoukoissa). Autentikaatiorajapinta pohjautuu toiminnallisesti JAAS-standardiin (Java Authentication and Authorization Service) ja myös siinä käytetään XML-merkkausta tietosisällön esittämiseen. Viestinvälityksessä käytetään teknisenä standardina HTTP-protokollaa ja tarvittaessa tiedon salaamiseen HTTP Secure protokollaa (HTTPS). 7 Sekvenssikaaviot rajapintojen käytöstä Tässä kappaleessa on esitetty kaksi sekvenssikaaviota PlugIT-rajapintojen käytöstä sovelluksen näkökulmasta. Kaavioissa on kuvattuna seuraavat kutsut: - käyttäjän tunnistaminen (AuthenticateUser-palvelu) - käyttäjän tietojen hakeminen (User:ProfileAccess-palvelu) - potilaan tunnistaminen (Patient:IdentifyProfile-palvelu) - tietyn potilaan tietojen hakeminen (Patient:ProfileAccess-palvelu) Toisessa kaaviossa on kuvattu lisäksi käyttäjän tarkistaminen yhteisestä kontekstinhallinnasta (ContextManager-palvelu) ennen autentikaatiota eli kertakirjautuminen. ContextManager-palvelu on esitetty erillisessä Minimitason kontekstinhallinnan määrittely dokumentissa.

11 11 Tarkemmat kuvaukset sovelluksen kutsumista metodeista on kappaleessa 8. Kuva 2: Sovelluksen PlugIT-palvelujen käyttö (ilman kertakirjausta)

12 12 Kuva 3: Sovelluksen PlugIT-palvelujen käyttö (kertakirjauksen kanssa) 8 Operaatioiden ja tietosisällön tekniset määrittelyt Seuraavassa esiteltävät rajapintamääritykset on kuvattu tarkemmin liitteessä 1.

13 AuthenticateUser Käyttäjä-rajapinnan metodit - GetCoupon (metodi, jolla haetaan käyttäjälle kuponki, tunnistetaan käyttäjän fyysinen laite) - CheckCoupon (metodi, jolla voidaan tarkistaa, onko kuponki enää voimassa) - CheckAuthentication (metodi, jolla voidaan tarkistaa, onko käyttäjä jo autentikoitunut) - Login (metodi, jolla käyttäjä autentikoidaan) - Logout (metodi, jolla käyttäjän autentikaatiotiedot poistetaan) - GetSubject (metodi, jolla voidaan hakea autentikoidun käyttäjän tunnistetiedot) Autentikaatio liittyy myös tiiviisti Työpöytäintegraatio -kohteeseen. Yksi mahdollisuus olisi, että autentikaatiopalvelu käyttäisi itse suoraan kontekstinhallintaa ja sitä kautta lisäisi autentikoidun käyttäjän yhteiseen kontekstiin joka mahdollistaisi myös kertakirjautumisen, ts. työpöytäintegraation: Ennen autentikaatiota voitaisiin tarkistaa, onko käyttäjä jo kirjautunut yhteiseen kontekstiin. Tämä toiminnallisuus on esitetty kappaleessa 7 kuvassa 3. Tässä dokumentissa AuthenticateUser-rajapinnassa on määritelty ns. minimi-toiminnallisuus turvallisuuden suhteen ja palvelua käyttävien työasemien oletetaan sijaitsevan samassa sisäverkossa (intranet), jolloin ne voidaan erottaa toisistaan IPosoitteen perusteella. Jatkossa on tarkoitus määritellä turvallisuuteen lisätasoja ja rajapinta, jolla autentikaatio tapahtuu turvallisisesti esimerkiksi Internet-ympäristössä. AuthenticateUser-palvelun on ylläpidettävä listaa kaikista autentikoiduista kupongeista ja pystyttävä yhdistämään kuponki tunnistuksessa käytettyyn tunnisteeseen (manifest). Tämä sen takia, että samasta fyysisestä työasemasta voi olla usea sovellus yhtä aikaa sisäänkirjautunut autentikaatiopalveluun, jolloin kaikilla sovelluksilla on eri (GetCoupon metodin palauttama) yhteyskuponki, mutta sama manifest-arvo. Tämä mahdollistaa single-signon

14 14 toiminnallisuuden. Palvelu voi delegoida tämän tehtävän myös erilliselle ContextManager-palvelulle (kuva 3 kappaleessa 7). 8.2 AuthorizationAccess Valtuutustietojen haku ydinjärjestelmältä. - CheckAuthorization (luvan kysyminen ydinjärjestelmältä) 8.3 IdentifyProfile ja ProfileAccess Nämä rajapinnat on suunniteltu siten, että niiden avulla voidaan käsitellä mitä tahansa profiili-tietoja. Profiiliksi käsitetään yksilöityä ominaisuusjoukkoa, esimerkiksi potilaan perustiedot jotka tunnistetaan profiiliksi potilaan henkilötunnuksen avulla. PlugIT-ydinpalvelumäärityksissä kuitenkin profiili rajataan käsittämään joko käyttäjää tai potilasta. Käsiteltävät ominaisuudet voivat myös olla yksittäisiä (esim. nimi) tai sisäkkäisiä, esimerkiksi osoite-ominaisuus sisältää ominaisuudet katuosoite, postitoimipaikka ja postinumero. Sama ominaisuus voi toistua myös useaan kertaan, kuten osoite-ominaisuus. Profiilien hakeminen käyttäjän antamien ehtojen perusteella IdentifyProfilerajapinnan kautta: - FindCandidates (Haetaan lista ehdokkaista, jotka sovellus näyttää loppukäyttäjälle) - GetMoreCandidates (Haetaan lisää tuloksia edellisestä hausta) - DropRemainingCandidates (Palvelun ei tarvitse enää muistaa edellisen kyselyn tuloksia, ei vastausta) Profiilitietojen haku ProfileAccess-rajapinnan kautta - GetProfile (Metodi, jolla haetaan profiilin tiedot) - UpdateProfile (Metodi, jolla profiilin tietoja voidaan päivittää. Ei kuulu minimitoteutukseen) - CreateProfile (Metodi, jolla voidaan luoda uusi profiili. Ei kuulu minimitoteutukseen)

15 15 - DeleteProfile (Metodi, jolla voidaan poistaa profiileja. Ei kuulu minimitoteutukseen) 8.4 Patient:IdentifyProfile - potilaiden haku Rajapintojen toiminnallisuus on kuvattu edellisessä 8.3 kappaleessa. Patient:IdentifyProfile rajapinnan kautta voidaan tunnistaa ydinjärjestelmän potilaita. Rajapinta on Hakuominaisuuksina minimitoteutuksessa pitää voida käyttää seuraavien ominaisuuksien yhdistelmiä: - hetu potilaan henkilötunnus (täsmällinen vastaavuus) - syntymaaika potilaan syntymäaika (osittainen vastaavuus) - sukunimi potilaan sukunimi. (osittainen vastaavuus) - etunimet kaikki potilaan etunimet eroteltuna välilyönneillä (osittainen vastaavuus). Pelkillä etunimillä ei voi kuitenkaan hakea, vaan lisänä on annettava esimerkiksi sukunimen alkua. Vastaavuus tarkoittaa löydettyjen potilaiden hakuominaisuuksien vastaavuutta verrattuna hakuarvoon. Täsmällinen vastaavuus tarkoittaa että hakuarvon on oltava täsmälleen sama kuin potilaan vastaavan ominaisuuden. Esimerkiksi sukunimi-ominaisuuden avulla voidaan hakea potilaita käyttäen sukunimen kolmea ensimmäistä kirjainta, mutta henkilötunnusta hakuarvona käytettäessä hakuarvon on oltava oikeamuotoinen henkilötunnus. 8.5 Patient:ProfileAccess - potilaaseen liittyvät perustiedot Tässä kappaleessa on kuvattu potilaaseen liittyviä perustietoja eli ominaisuuksia joita voidaan käsitellä Patient:ProfileAccess rajapinnan kautta. Määriteltynä on niin sanottu minimi-tietojoukko, jota potilas-tietoja käsittelevän Patient:ProfileAccess-rajapinnan on tuettava. Näitä perustietoja on tarkoitus laajentaa liittymämäärittelyiden seuraavassa versiossa. Perustietojoukko on otettu potilasasiakirjojen laatimisesta sekä niiden ja muun hoitoon liittyvän materiaalin säilyttämisen määrittävästä sosiaali- ja terveysministeriön asetuksesta 10. Ominaisuuksien tyyppimääritykset on otettu HL7 V3 tietotyyppi- ja koodistomäärityksistä. Ominaisuuksista on esimerkki kuvauksen oheessa ja koodattujen ominaisuuksien yhteydessä on myös käytetty

16 16 koodisto tai standardi ilmoitettu, ts. koodiston OID-tunnus tai ISO-standardin nimi. Kuvattuja perusominaisuuksia käytetään lisäämällä niiden eteen pisteellä eroteltuna ominaisuuteen liittyvä suurempi kokonaisuus. Esimerkiksi potilaan kotikatuosoitetta kuvattaisiin ominaisuudella koti.katuosoite ja työpaikan katuosoitetta ominaisuudella tyo.katuosoite. Potilaan kotiosoite ilmoitettaisiin ominaisuuksilla: koti.katuosoite, koti.postinumero, koti.postitoimipaikka, koti.maa.koodi, koti.maa.nimi, koti.puhelinnumero ja koti.tyyppi. Jos esimerkiksi osoitteita on useita, ne voidaan kuvata lisäämällä ko. ominaisuuden perään järjestysnumero pisteellä eroteltuna, esimerkiksi koti.katuosoite.2. Lisäksi osoitteiden tyyppiä voidaan kuvata tyyppiominaisuudella. Palvelun toteuttajan on kuvattava kaikki tuetut ominaisuudet palvelun dokumentaatiossa. Perusominaisuus hetu syntymaaika sukunimi etunimet sukupuoli.koodi sukupuoli.nimi Kuvaus Potilaan pysyvä henkilötunnus XXXX Potilaan syntymäaika: DATE (muoto on YYYYMMDD) Potilaan sukunimi: ST (Character String) SORMUNEN Potilaan etunimet eroteltuna välilöynneillä: ST (Character String) Marko Juhana Potilaan sukupuolen koodi: CWE, koodiston OID: HL7 V2.3 tyyppikoodit ja selitykset ovat: 1 Mies 2 nainen 3 ei tiedossa/määriteltävissä Potilaan sukupuolen nimi:

17 17 Mies, Nainen tai Ei tiedossa/määriteltävissä kunta.nimi JHS 110-suosituksen mukainen kunnan nimi Kuopio kunta.koodi JHS 110- suosituksen mukainen kunnan koodi 279 Osoitetietoihin Kuvaus jne. liittyviä ominaisuuksia koti Potilaan kotiin liittyviä tietoja. Esimerkiksi kotiosoitteen katuosoite ilmoitettaisiin: koti.katuosoite tyo Potilaan työhön liittyviä tietoja. Esimerkiksi työosoitteen katuosoite ilmoitettaisiin: tyo.katuosoite tyyppi Osoitteen tyyppi: CS, koodiston OID: HL7 V2.3 tyyppikoodit ja selitykset ovat: C Tilapäinen kotiosoite (Current or Temporary) O Työosoite (Office) H Pysyvä kotiosoite (Home) N Syntymäpaikka katuosoite katuosoite: ST (Character String) Petosenmutka 10 A4 postinumero postinumero: ST (Character String) postitoimipaikka postitoimipaikka: ST (Character String) Kuopio maa.koodi SFS-ISO 3166-standardin mukainen maa-koodi FI maa.nimi SFS-ISO 3166-standardin mukainen maan nimi Suomi puhelinnumero puhelinnumero: ST (Character String) Tarvittaessa perustietojoukkoa voidaan laajentaa seuraavilla STM:n määrittämillä lisäominaisuuksilla. aidinkieli.koodi SFS-ISO 639 standardin mukainen kaksi-kirjaiminen kielen koodi

18 18 aidinkieli.nimi asiointikieli.koodi asiointikieli.nimi ammatti lahiomainen yhteyshenkilo huoltaja tyonantajan_vakuutusyhtio fi SFS-ISO 639 standardin mukainen kielen nimi Suomi SFS-ISO 639 standardin mukainen kaksi-kirjaiminen kielen koodi fi SFS-ISO 639 standardin mukainen kielen nimi Suomi Potilaan ammatti: ST (Character String) Potilaan lähiomainen. Esimerkiksi potilaan lähiomaisen sukunimi ilmoitettaisiin ominaisuudella lahiomainen.sukunimi ja katuosoite ilmoitettaisiin ominaisuudella lahiomainen.katuosoite. Kaikki tässä kuvatut potilaan perusominaisuudet voidaan liittää lahäomaiseen tällä tavalla. Potilaan yhteyshenkilö. Esimerkiksi potilaan yhteyshenkilön sukunimi ilmoitettaisiin ominaisuudella yhteyshenkilo.sukunimi ja katuosoite ilmoitettaisiin ominaisuudella yhteyshenkilo.katuosoite. Kaikki tässä kuvatut potilaan perusominaisuudet voidaan liittää yhteyshenkilöön tällä tavalla. Potilaan huoltaja. Esimerkiksi potilaan huoltajan sukunimi ilmoitettaisiin ominaisuudella huoltaja.sukunimi ja katuosoite ilmoitettaisiin ominaisuudella huoltaja.katuosoite. Kaikki tässä kuvatut potilaan perusominaisuudet voidaan liittää huoltajaan tällä tavalla. Työnantajan vakuutusyhtiö: ST (Character String) 8.6 Käyttäjään liittyvät perustiedot Käyttäjään liittyviä perustietoja voidaan käsitellä User:ProfileAccessrajapinnan kautta. Käyttäjään liittyviä perustietoja voivat olla mitkä tahansa kappaleessa 8.6 kuvatuista perusominaisuuksista ja osoitetiedoista. Pakollisia näistä ominaisuuksista ovat hetu, etunimet ja sukunimi.

19 Virhekoodit ja niiden arvot Tässä kappalleessa on kuvattu virhetilanteiden minimitaso. Virhetilanteet ilmoitetaan aina exception-elementeillä, jossa on kuvattuna virheen koodi idattribuutin ja virheen selkokielinen kuvaus exception-elementin sisällä. Oheessa on taulukko minimitason virhekoodeista ja kuvauksista. id GeneralFailure CouponNotCreated CouponNotAuthenticated Selkokielinen kuvaus Virhe tietokannan käsittelyssä: <tarkempi virhe> (kaikki rajapinnat ja metodit) Kupongin laatiminen epäonnistui: <tarkempi virhe> (Rajapinta AuthenticateUser, metodi GetCoupon) Kuponkia ei ole varmennettu. (Rajapinta AuthenticateUser, metodit GetSubject ja Logout. Rajapinnat AuthorizationAccess, ProfileAccess, ProfileAccess, IdentifyProfile, kaikki metodit) AuthenticationCheckFailed Autentikaation tarkistus epäonnistui: <tarkempi virhe> AuthenticationFailed AuthorizationCheckFailed UnknownProfile UnknownTrait NoMoreResults NotImplemented (Rajapinta AuthenticateUser, metodit CheckAuthentication) Autentikaatio epäonnistui: <tarkempi virhe> (Rajapinta AuthenticateUser, metodi Login) Valtuuksien tarkistaminen epäonnistui: <tarkempi virhe> (Rajapinta AuthorizationAccess, metodi CheckAuthorization) Tuntematon profiili: <tunniste> (Rajapinta ProfileAccess, kaikki metodit) Tuntematon ominaisuus <ominaisuuden nimi> (Rajapinta ProfileAccess, metodit GetProfile, CreateProfile, UpdateProfile Rajapinta IdentifyProfile, metodit FindCandidates) Ei enempää hakutuloksia. (Rajapinta IdentifyProfile, metodi GetMoreCandidates) Varattu tulevaisuuden laajennuksia varten, jos palvelu ei tue jotain rajapinan nmetodia, se voi palauttaa tämän virheen.

20 20 9 Toteutuskohtaiseksi jätettävät asiat Http(s)-keskustelija on helpoin olla myös tavallinen WWW-palvelin, joka vastaanottaa normaaleja URL:ien avulla lähetettäviä http-viestejä. Tällöin palvelutoteutus voi olla toteutettu esimerkiksi: CGI-ohjelmana. JavaServer Pages (JSP) tekniikalla Java-ympäristössä. Active Server Pages (ASP) tai ASP.NET tekniikalla Microsoft ympäristössä. Caché Server Pages (CSP) tekniikalla Caché-ympäristössä. Viestinvälityksen turvallisuus voidaan toteuttaa käyttämällä HTTPS (HTTP Secure) yhteyksiä HTTP-yhteyksien sijaan. avulla turvallisuusnäkökohtia ei tarvitse ottaa huomioon viestien sisältöä suunniteltaessa, koska sen tarjoama viestien salaus toimii alemmalla protokolla-tasolla. Tämän ansiosta HTTPS toimii yhteen myös esimerkiksi SOAP-viestien kanssa myöhemmin ( SOAP-over-HTTPS ) jos niihin on tarvetta. Lisäksi HTTPS voidaan jättää helposti pois tarvittaessa jos turvallisuus on muuten varmennettu, esim VPN-tekniikalla. Muita tapoja toteuttaa turvallinen HTTP-pohjainen viestinvälitys on mm: SOAP-pohjaiset turvallisuusmääritykset W3C:n määritykset (XML Encryption ja XML Signature) Yleisten salausalgoritmien hyödyntäminen Nämä turvallisuusratkaisut toimivat lähetettävien viestien, eivät koko liikenteen salauksen tasolla. Niitä on käsitelty mm. PlugIT-projektin Web Servicesselvityksessä (Component and Service Technology Families, Web Services) 10 Määrittelyjen mukaisuuden toteaminen Eri määritysten kohdalla on kerrottu, mitkä operaatiot ja tietoelementit palvelun toteutuksen on vähintään toteutettu ja mainittu, mitkä seikat ovat palvelun tarjoajan ja palvelun käyttäjän vastuulla. Toteutukset, jotka noudattavat kuvattuja vähimmäisvaatimuksia ja määriteltyjä sovellusten vastuita, ovat määritysten mukaisia. Palvelun toteutuksen määritysten mukaisuus voidaan todeta

21 21 testausraportilla, joka sisältää palvelun toteutuksen palauttamat arvot yllä kuvatuilla ehdoilla ja virheellisillä syötteillä. Palvelua käyttävän sovelluksen määritysten mukaisuus voidaan todeta testausraportilla, jossa palvelun onnistuneiden kutsujen (yllä olevilla edellytyksillä) lisäksi selviää palvelua käyttävän sovelluksen toiminta palvelun palauttaessa virhetilanteita.

22 22 LIITE 1: Operaatioiden ja tietosisällön tekniset määrittelyt Joitakin kutsumetodeja on merkitty tässä dokumentissa määriteltyyn minimitoiminnallisuuden ulkopuolelle. Niitä ei siis tarvitse toteuttaa, ellei halua ottaa käyttöön niissä erikseen kuvattua lisätoiminnallisuutta. Virhekoodit on selitetty tarkemmin kappaleessa 8.8. Esimerkeissä käytetty oletusnimiavaruus urn:plugit:commonservices suositellaan lisättäväksi viestien request- ja response elementteihin, vaikka ne eivät ole pakollisia. AuthenticateUser Metodi GetCoupon Tällä metodilla käyttäjälle haetaan kuponki, jolla tunnistetaan käyttäjän fyysinen laite. Huom! Tässä vaiheessa ei autentikoida käyttäjän henkilöllisyyttä. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>authenticateuser</interface> <method>getcoupon</method> <param> <manifest> </manifest> </param> </request> Vastaus <coupon>fj2uc8a9</coupon> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys

23 23 manifest coupon Käyttäjän koneen IP-osoite (ja/tai nimi eroteltuna / merkillä). Manifest on merkkimuotoista tietoa, jolla ei maksimipituutta. Manifest voi myös koostua lisätiedoista, kuten tarvittaessa käyttäjän nimestä ja organisaatiotiedosta. Esimerkiksi manifest-tiedon ja kasvatettavan laskuriarvon pohjalta laadittu tiiviste ( hash-tiiviste ), joka on salattu (allekirjoitettu) turvallisuusavaimella esimerkiksi käyttäen HMAC-MD5 algoritmiä ja base64-koodattu. Hash-tiivisteellä ei ole maksimipituutta, mutta sen pituus riippuu käytetystä HMAC-MD5 algoritmistä. Kupongin pitää aina olla ainutlaatuinen, vaikka GetCoupon metodia kutsuttaisiin samalta työasemalta useaan kertaan. Palvelun tehtävä on muistaa, mitkä kupongit liittyvät mihinkin manifest-tunnukseen. HUOM! Kuponki voitaisiin hakea myös ContextManager-palvelusta eli olla suoraan participantcoupon. Tällöin GetCouponmetodin pitäisi myös liittyä Context- Managerin yhteiseen kontekstiin. exception Kuponki tunnistaa käyttäjän istunnon. PlugIT-palveluja käyttävien sovellusten vastuulla on lisätä kuponki tunnisteeksi niihin palvelukutsuihin, joissa sitä tarvitaan. Kuponki talletaan autentikaatiopalvelun muistiin, jotta se tunnistetaan jatkossa. Kuponki ei vaarannu jatkossa, koska käytössä oleva HTTPS-protokolla suojaa sen. Virheen sisältävä elementti.

24 24 Metodi CheckCoupon Metodi, jolla voidaan tarkistaa, onko kuponki vielä voimassa. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>authenticateuser</interface> <method>checkcoupon</method> <param> <coupon>fj2uc8a9</coupon> </param> </request> Vastaus <coupon>fj2uc8a9</coupon> tai jos kuponki ei ole voimassa: <response xmlns= urn:plugit:commonservices /> tai jos tapahtuu virhe: Metodi CheckAuthentication Tällä metodilla voidaan tarkistaa, onko käyttäjä jo autentikoitunut, ts. onko kuponki voimassa ja onko se varmennettu. <exception id= virhekoodi >virhe</exception> XML:n selitys coupon exception Kuponki, joka tunnistaa käyttäjän. Jos kuponki on saatu erilliseltä Context- Manager-palvelulta, CheckCoupon-metodin pitäisi tarkistaa kupongin voimassaolo myös ContextManager-palvelusta. Virheen sisältävä elementti. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>authenticateuser</interface> <method>checkauthentication</method> <param> <coupon>fj2uc8a9</coupon> </param> </request> Vastaus

25 25 Metodi Login Metodi, jolla käyttäjä autentikoidaan. Jos varmentaminen onnistuu, käyttäjän tunnistetiedot palautetaan ja käyttään profiilitietoja voidaan hakea User:ProfileAccess rajapinnan kautta tunnistetiedon avulla. <coupon>fj2uc8a9</coupon> tai jos käyttäjä ei ole autentikoitunut, palautetaan: <response xmlns= urn:plugit:commonservices /> tai jos tapahtuu virhe: <exception id= virhekoodi >virhe</exception> XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. Jos kuponki on saatu erilliseltä Context- Manager-palvelulta GetCoupon-metodin avulla, CheckAuthentication-metodin pitäisi tarkistaa ContextManager-palvelun yhteisestä kontekstista, onko käyttäjä jo sisäänkirjautunut. exception Virheen sisältävä elementti. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>authenticateuser</interface> <method>login</method> <param> <coupon>fj2uc8a9</coupon> <account> <username>msormune</username> <password>plugit.42</password> </account> <environment>uku_test_server</environment> </param> </request> Vastaus <subject> <account> <username>msormune</username> <profile id= 1 /> </account> </subject tai: <exception id= virhekoodi >virhe</exception> XML:n selitys

26 26 Metodi GetSubject Tämän metodin avulla voidaan jälkeen päin hakea varmennetun käyttäjän tunnistetieto. Käyttään profiilitietoja voidaan hakea User:ProfileAccess rajapinnan kautta tunnistetiedon avulla. account Käyttäjän autentikointitiedot. Tällä hetkellä mukana on vasta tunnus/salasana-pohjainen tunnistus. authentication Autentikoitavan käyttäjän tiedot, joiden avulla käyttäjän varmentaminen pitäisi onnistua. subject Elementti, joka sisältää kupongin autentikoineen käyttäjän yksiselitteisen tunnisteen (profile-elementti). Tunniste voi olla esim. juokseva numero (esimerkissä idattribuutti), jota kasvatetaan aina kun uusi käyttäjä lisätään järjestelmään. Lisäksi elementti voi sisältää varmenteita joilla käyttäjän autentikointi onnistui (esim. käyttäjätunnus). Tunnisteen avulla voidaan hakea käyttäjän tietoja User:ProfileAccess rajapinnan kautta. Subject-elementti sisältää myös kaikki onnistuneet varmenteet. environment Ympäristö, johon käyttäjä sisäänkirjautuu. Ei ole pakollinen, jos autentikaatiopalvelun kautta voidaan sisäänkirjautua vain yhteen ympäristöön (esim. testi- tai tuotantoympäristö). coupon Kuponki, joka tunnistaa käyttäjän. Jos kuponki on saatu erilliseltä Context- Manager-palvelulta GetCoupon-metodin avulla, Login-metodin pitäisi merkitä käyttäjä sisäänkirjautuneeksi ContextManagerin yhteiseen kontekstiin. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>authenticateuser</interface> <method>getsubject</method> <param> <coupon>fj2uc8a9</coupon> </param> </request> Vastaus <subject> <account> <username>msormune</username> <profile id= 1 /> </account> </subject tai: <exception id= virhekoodi >virhe</exception>

27 27 Metodi Logout Käyttäjä uloskirjautuu tämän metodin avulla. Kaikki varmennetut kupongit poistetaan. XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. subject Elementti, joka sisältää kupongin autentikoineen käyttäjän yksiselitteisen tunnisteen (profile-elementti). Tunniste voi olla esim. juokseva numero (esimerkissä idattribuutti), jota kasvatetaan aina kun uusi käyttäjä lisätään järjestelmään. Lisäksi elementti voi sisältää varmenteita joilla käyttäjän autentikointi onnistui (esim. käyttäjätunnus). Tunnisteen avulla voidaan hakea käyttäjän tietoja User:ProfileAccess rajapinnan kautta. Subject-elementti sisältää myös kaikki onnistuneet varmenteet. account Varmenteet, joiden avulla käyttäjä autentikoitiin onnistunesti. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>authenticateuser</interface> <method>logout</method> <param> <coupon>fj2uc8a9</coupon> </param> </request> Vastaus <response xmlns= urn:plugit:commonservices /> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. Jos käyttäjälle myönnetyt kupongit on haettu erillisestä ContextManagerpalvelusta, tässä yhteydessä ne pitäisi myös merkitä uloskirjautuneeksi Context- Managerin yhteisestä kontekstista.

28 28 AuthorizationAccess Metodi CheckAuthorization Abstrakti luvan kysyminen ydinjärjestelmältä. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>authorizationaccess</interface> <method>checkauthorization</method> <param> <coupon>fj2uc8a9</coupon> <permission id= joku_lupa > <unit>th-yksikkö</unit> <role>joku_käyttäjän_rooli</role> <dataid>kohde</dataid> <application>sovellus</application> <person>pid</person> <mode>jokin_toimintotyyppi</mode> </permission> </param> </request> Vastaus <permission id= joku_lupa /> tai jos lupaa ei ole: <response xmlns= urn:plugit:commonservices /> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys

29 29 coupon permission id application person unit role dataid mode exception Kuponki, joka tunnistaa käyttäjän. lupaa esittävä elementti. Jos käyttäjällä ei ole lupaa, paluuarvo sisältää vain response-elementin. Yhdessä kutsussa voidaan kysyä useampaa lupaa yhdellä kertaa lähettämällä useampi permission-elementti. Jos käyttäjällä on lupa, palvelu palauttaa vastaavan permission-elementti, jossa id-koodi tunnistaa myönnetyn luvan. Sovelluksen itse määrittämä tunniste tms. yksikäsitteinen arvo jolla se pystyy erottelemaan toisistaan lupaelementit CheckAuthorization-kutsun jälkeen. Esimerkiksi 1, 2, jne. Jos vain yhtä lupaa kysytään kerrallaan, tätä attribuuttia ei tarvita. Sovelluksen tieto, ts. minkä sovelluksen piirissä lupaa kysytään. Luvan kohteen tunnistava tieto (virallinen henkilötunnus tai väliaikainen, jos virallista ei vielä ole), kysyttäessä esimerkiksi potilaan suostumusta tai hoitosuhdetta. Terveydenhuollon yksikön koodi, jonka piirissä lupaa kysytään. Voidaan jättää pois, jolloin oletetaan että lupaa kysytään käyttäjän yksikön piirissä. Käyttäjän roolitieto, joka voidaan jättää pois tai määritellä sovelluskohtaisesti. Esimerkiksi käyttäjällä voi olla määritelty erilaisia rooleja liittyen sovelluksen eri toimintokokonaisuuksiin (katselu, ylläpito) ja tällä elementillä voidaan ilmaista, mikä rooli käyttäjällä pitää olla luvan saamiseksi. Elementti, joka koskee nimettyä tietojoukkoa tai muuta kohdetta. Tietojoukkojen nimeäminen tapahtuu siten, että kunkin sovelluksen tekijä määrittelee oman sovelluksensa sisältämien tietojoukkojen tunnisteet. Esimerkkeinä: potilaslista, CDA-dokumenttimäärityksen OID, muu dokumentin tunniste. Vapaaehtoinen mode-elementti tarkoittaa merkkijonoa, joka sisältää jonkin tai useamman seuraavista merkeistä: C create, lisäysoikeus (tiedon) R read, luku- tai käynnistysoikeus (tiedon, toiminnon tai sovelluksen) U update, muutosoikeus (tiedon), ylläpito-oikeus (sovelluksen) D delete, poisto-oikeus (tiedon). Kunkin palvelussa mukana olevan tietojoukon (kts. dataidelementti) tai tietokokonaisuuden osalta määritellään tarkemmin, mitä kukin lupa tarkoittaa. Exception-elementti sisältää mahdollisen luvan tarkistamisen aikana tapahtuneen virheen.

30 30 IdentifyProfile Metodi FindCandidates Haetaan lista profiiliehdokkaista jotka sovellus näyttää loppukäyttäjälle. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>patientidentifyprofile</interface> <method>findcandidates</method> <param> <coupon>fj2uc8a9</coupon> <findcandidate> <trait id= hetu /> <trait id= sukunimi partial= 1 >SORM</trait> <trait id= etunimet /> </findcandidate> <sortbytrait id= sukunimi >ASC</sortByTrait> <maxreturned>1</maxreturned> <maxstored>5</maxstored> </param> </request> Vastaus <candidate id= xxxx > <trait id= hetu > xxxx</trait> <trait id= sukunimi >SORMUNEN </trait> <trait id= etunimet >MARKO JUHANA</trait> </candidate> <candidate id= xxxx > <trait id= hetu > xxxx</trait> <trait id= sukunimi >SORMUNEN </trait> <trait id= etunimet >SAARA</trait> </candidate> jos tietueita on löydetty enemmän kuin mitä palautetaan: <candidate id= xxxx > <trait id= hetu > xxxx</trait> <trait id= sukunimi >SORMUNEN </trait> <trait id= etunimet >MARKO JUHANA</trait> </candidate> <candidate id= xxxx > <trait id= hetu > xxxx</trait> <trait id= sukunimi >SORMUNEN </trait> <trait id= etunimet >SAARA</trait> </candidate> <storedcandidates>2</storedcandidates> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys

31 31 coupon Kuponki, joka tunnistaa käyttäjän. findcandidate Haun määrittävä elementti. Haussa käytetyn ominaisuuden (Trait-elementit) täytyy sisältää jokin hakuarvo value-elementissä. Kaikki tässä elementissä luetellut ominaisuudet palautetaan löydetyistä ehdokkaista. candidate Löydetty ehdokas, joka vastaa hakuarvoa. trait Haku- tai vastausprofiilin ominaisuus. Partial-attribuutti hakuominaisuuden yhteydessä tarkoittaa hakutuloksen vastaavuutta. Sallitut arvot ovat 0 (täsmällinen löytö), 1 (osittainen löytö ominaisuuden alusta), 2 (osittainen löytö ominaisuuden alusta tai keskeltä, esimerkiksi hakuominaisuus JUHA vastaisi ominaisuutta MARKO JUHANA ). Oletuksena on 0. sortbytrait Ominaisuus, jonka mukaan järjestettynä vastaukset halutaan palautettavan. Lajittelusuunnat ovat ASC (oletus) tai DESC. maxreturned montako löydettyä ehdokasta enintään palautetaan saman tien. Oletuksena palvelun pitäisi palauttaa kaikki löydetyt ehdokkaat kerralla, jos maxreturned-arvoa ei ole annettu. maxstored montako löydettyä ehdokasta palvelu säilyttää enintään haettavaksi GetMoreCandidates metodilla. Tämä elementti on hyödyllinen vain, jos palvelun toteutus hakee kaikki ehdokkaat yhdellä kertaa tietokannasta. Jos kaikkia ehdokkaita ei haeta yhdellä kertaa (esim. JDBC/ODBCrajapinnan kautta haettaessa), elementti voidaan jättää huomioimatta. Oletuksena palvelun pitäisi löytää kaikki hakuarvoja vastaavat ehdokkaat, jos maxstoredarvoa ei ole annettu. id Ehdokkaan tunniste (esim. hetu tai muu geneerinen id) tai potilaan ominaisuuden tunnistava tieto. storedcandidates Lisävastauksia kuvaava elementti.

32 32 Metodi GetMoreCandidates Haetaan lisää tuloksia edellisestä hausta. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>patientidentifyprofile</interface> <method>getmorecandidates</method> <param> <coupon>fj2uc8a9</coupon> <maxreturned>1</maxreturned> </param> </request> Vastaus <candidate id= xxxx > <trait id= hetu > xxxx</trait> <trait id= sukunimi >SORMUNEN </trait> <trait id= etunimet >RAUNA MARIA</trait> </candidate> <storedcandidates>1</storedcandidates> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. candidate Edellisestä hausta palauttamassa jäänyt ehdokas. trait Ehdokkaan ominaisuus. maxreturned montako ehdokasta enintään palautetaan. id Ehdokkaan tunniste (esim. hetu tai muu geneerinen id) tai potilaan ominaisuuden tunnistava tieto. storedcandidates Lisävastauksia kuvaava elementti, jos niitä on.

33 33 Metodi DropRemainingCandidates Palvelun ei tarvitse enää muistaa käyttäjän kyselyiden tuloksia. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>patientidentifyprofile</interface> <method>dropremainingcandidates</method> <param> <coupon>fj2uc8a9</coupon> </param> </request> Vastaus <response xmlns= urn:plugit:commonservices /> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys Coupon Kuponki, joka tunnistaa käyttäjän.

34 34 Metodi GetProfile ProfileAccess Metodi, jolla haetaan profiilin itiedot. Tämä metodi voi tukea myös useamman profiilin hakemista yhdellä kertaa, ts. parametrina voidaan antaa useampi RequestProfile-elementti. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>patientprofileaccess</interface> <method>getprofile</method> <param> <coupon>fj2uc8a9</coupon> <accessprofile id= xxxx > <trait id= sukunimi /> <trait id= etunimet /> </accessprofile> </param> </request> Vastaus <profile id= xxxx > <trait id= sukunimi >SORMUNEN</trait> <trait id= etunimet>marko JUHANA</trait> </profile> <response> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. accessprofile Profilli, jonka ominaisuuksia haetaan. profile Profiilin määrittävä elementti. trait Profiiliin liittyvä ominaisuus id Profiilin tunniste (esim. hetu tai muu geneerinen id) tai ominaisuuden tunnistava tieto. value Ominaisuuden arvo.

35 35 Metodi UpdateProfile * Tämä metodi ei kuulu Ydin-rajapintojen minimi-toteutukseen* Profiilin tietojen muuttaminen. Tämä metodi voi tukea tarvittaessa myös useamman profiilin tietojen päivittämistä yhdellä kertaa. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>patientprofileaccess</interface> <method>updateprofile</method> <param> <coupon>fj2uc8a9</coupon> <updateprofile id= xxxx > <trait id= koti.katuosoite.1 >Petosenmutka</trait> <trait id= koti.postitoimipaikka.1 /> </updateprofile> </param> </request> Vastaus <response xmlns= urn:plugit:commonservices /> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. updateprofile Päivitysprofiilin määrittävä elementti. trait Päivitettävä ominaisuus. Jos ominaisuudella ei ole teksti-elementtiä, ko. ominaisuus poistetaan. id Profiilin tunniste (esim. hetu tai muu geneerinen id) tai profiilin ominaisuuden tunnistava tieto. Metodi CreateProfile * Tämä metodi ei kuulu Ydin-rajapintojen minimi-toteutukseen* Uuden profiilin lisääminen ydinjärjestelmään. Tämä metodi voi tukea tarvittaessa myös useamman profiilin lisäämistä yhdellä kertaa. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>patientprofileaccess</interface> <method>createprofile</method> <param> <coupon>fj2uc8a9</coupon> <createprofile id= xxxx > <trait id= sukunimi >JAAKKOLA</trait> <trait id= etunimet>jaakko POIKA</trait> </createprofile> </param> </request> Vastaus <response xmlns= urn:plugit:commonservices /> tai:

36 36 <exception id= virhekoodi >virhe</exception> XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. createprofile Uuden profiilin määrittävä elementti. trait Uuteen profiiliin liitettävä ominaisuus. id Profiilin tunniste (esim. hetu tai muu geneerinen id) tai profiilin ominaisuuden tunnistava tieto. Metodi DeleteProfile * Tämä metodi ei kuulu Ydin-rajapintojen minimi-toteutukseen* Profiilin poistaminen ydinjärjestelmästä. Tämä metodi voi tukea tarvittaessa myös useamman profiilin poistoa yhdellä kertaa. Kysymysesimerkki <request xmlns= urn:plugit:commonservices > <interface>patientprofileaccess</interface> <method>deleteprofile</method> <param> <coupon>fj2uc8a9</coupon> <deleteprofile id= xxxx /> </param> </request> Vastaus <response xmlns= urn:plugit:commonservices /> tai: <exception id= virhekoodi >virhe</exception> XML:n selitys coupon Kuponki, joka tunnistaa käyttäjän. deleteprofile Poistettavan profiilin määrittävä elementti. id Poistettavan profiilin tunniste (esim. hetu tai muu geneerinen id).

37 37