1 HL7 Finland koulutus FHIR profilointi perusteet 13.6.-14.6.2018, Helsinki Tietohiisi, Mika Tuomainen
2 Kiitokset Materiaalissa hyödynnetty seuraavien tekijöiden esityksiä (CC by author): Rene Spronk Mirjam Baltus Ewout Kramer Lloyd McKenzie Michel Rutten Grahame Grieve David Hay
3 Koulutuksen sisältö Päivä 1 FHIR perusteet FHIR profilointi perusteet FHIR profilointi 1/2 Päivä 2 FHIR profilointi 2/2 Simplifier profiilirekisteri
4 Sisältö Yleistä taustaa profiloinnille FHIR Conformance resurssit Profiilit Profilointi
Taustaa profiloinnille 5
6 Miksi profilointia tarvitaan? Ydin FHIR standardi kuvaa alustan, joukon resursseja ja APIn, joista voidaan käyttää useissa eri terveydenhuollon konteksteissa. Monta eri terveydenhuollon kontekstia mutta vain yksi setti resursseja On kuitenkin olemassa paljon eroavaisuuksia eri käyttökontekstien välillä Lainsäädännösssä, eri terveydenhuollon ekosysteemien käytännöissä, vaatimuksissa, säännöissä Jokainen resurssipalvelin voi toteuttaa tietyn alijoukon FHIR määrittelystä (kyvykkyydet, tietosisältö, formaatti, tiedonsiirtomalit) Näin joudutaan tekemään valintoja, mitkä näistä johtuvat toimet ovat mahdollisia ja/tai hyödyllisiä. Tästä syystä FHIR määritelty alustamäärittelyksi Se luo yleisen alustan / perustan, jolle useat erilaiset ratkaisut voidaan toteuttaa. 80 / 20 malli Yleisyyden vuoksi FHIR vaatii soveltamista/mukauttamista = profilointia tietyn kontekstin käyttötarpeisiin
Periytetyt profiilit (derived profiles, layered profiles) 7 Resurssit Ydin (Core) resrussit Suomi profiilit US profiilit Kansalliset profiilit PHR profiilit Organisaatiokohtaiset profiilit
8 Mitä profilointi on? Kuvaa resurssien soveltamisen eri käyttökohteisiin ja eri käyttökonteksteihin: Mitä resurssin elementtejä käytetään ja miten Mitä resurssin elementtejä ei käytetä Mitä lisäelementtejä, joita ei löydy pohjamäärittelystä, resurssiin on lisätty Mitä koodistoja käytetään tietyissä koodatun tiedon elementeissä Mitä FHIRin RESTful APIn, sanomien (messaging) ja dokumenttien (documents) ominaisuuksia käytetään ja miten Hakuparametrit Kuvaukset miten resurssin elementtejä ja APIn ominaisuuksia käytetään paikallisiin vaatimuksiin ja / tai toteutuksiin
9 Esim. Kanta PHR tarpeet Itse tehdyt fysiologiset mittaukset, itsehoitolääkitys, kyselyt ja vastaukset, suostumus, omahoitosuunnitelmat Resurssi-instanssien tiedon oikeellisuuden varmentaminen mahdollisimman pitkälle serveripään validoinnilla esim. mittayksiköt, valuesetit, koodistot jne.. validointi tehdään profiileja vasten (ei tarvetta erillisille validointisäännöille!!!) samaa tietoa lukee ja kirjoittaa eri sovellukset (kansallinen konteksti vs. oma sovellus ja oma resurssipalvelin) Omakanta näyttää Omatietovarannon tiedot kansalaiselle Lokiraporttien tuottamiseen vaadittavat tiedot APIn ominaisuudet Mitä resurssityyppejä tuetaan, mitä profiileja tuetaan Mitä CRUD operaatioita tuetaan per resurssi Mitä hakuparametreja tuetaan per resurssi Syntaksituki (Kanta PHR vain JSON)
10 FHIR profiloinnin tuomia etuja FHIR:ssa profilointi on sisäänrakennettu (FHIR Conformance resurssit) Aiemmin HL7:ssa profiilit tehtiin eri syntaksilla kuin itse standardit (Schematron, Word, Skeemat, HTML..) FHIR:ssa profiilit ja implementointoppaat ovat itsekin FHIR resursseja Ohjelmallisesti käsiteltävässä muodossa Profiilien hallinta ja ylläpito rakenteisessa muodossa -> profiilit määritelty samalla standardilla kuin resurssitkin Validointi -> FHIR palvelimet voivat validoida suoraan resurssi-instansseja profiileja vasten (ks. https://www.hl7.org/fhir/validation.html) Koodin generointi profiilien pohjalta Kommunikointiväline eri osapuolten välillä
FHIR Conformance resurssit 11
Conformance resurssit ja niiden suhteet https://www.hl7.org/fhir/conformance-module.html 12
13 FHIR Conformance resurssit FHIR tarjoaa joukon resursseja, joita voidaan käyttää edellisten kalvojen soveltamistarpeiden esittämiseen ja hyödyntämiseen ohjelmallisesti. Näitä resursseja kutsutaan Conformance resursseiksi. Näitä resursseja käytetään Implementation Guide- (Implementointioppaissa) ja Capability Statement- (järjestelmän kyvykkyydet) kuvauksissa mutta voidaan käyttää myös omina erillisinä yksittäisinä resursseinaan Implementointioppaat (Implementation Guides) ovat tietyn sovellusalueen, organisaation / instituution tai toimittajan julkaisemia dokumentteja, jotka kuvaavat miten FHIR standardia on sovellettu tukemaa tiettyä käyttötarkoitusta / käyttötapausta (käyttötapauksia). Implementointiopas yhdistää joukon Conformance resursseja ja näihin liittyvän tekstimuotoisen ohjeistuksen toteuttajien hyödynnettäväksi dokumentiksi. Capability Statement käyttää Conformance resursseja dokumentoimaan, miten asiakaspää (client) tai palvelin (server) toteuttavat FHIRiä, esim. mitkä standardin tukemat paradigmat ja API ominaisuudet ovat toteutettu ja miten
14 FHIR Conformance resurssit Implementointioppaan (soveltamisoppaan) sisältö kuvataan käyttämällä resurssia ImplementationGuide Capability Statementin sisältö kuvataan käyttämällä resurssia CapabilityStatement Huom. CapabilityStatement on itse asiassa yksi Conformance resursseista, se kuvaa järjestelmän ominaisuudet (kyvykkyydet) ImplementationGuide on joukko Conformance resursseja: StructureDefinition CapabilityStatement MessageDefinition OperationDefinition SearchParameter CompartmentDefinition DataElement Conformance resursseja voidaan käyttää myös itsenäisesti, ei välttämättä vain implementointioppaassa tai Capability statementin määrityksessä.
Conformance resurssit ja niiden suhteet https://www.hl7.org/fhir/conformance-module.html 15
16 FHIR Conformance resurssit StructureDefinition Resurssi, joka kuvaa miten tiettyä rakennetta (resurssi, laajennus, tietotyyppi) käytetään Miten resurssin/tietotyypin olemassa olevia elementtejä käytetään Mitä olemassa olevia elementtäjä ei käytetä Mitä laajennuksia voidaan käyttää resurssissa/tietotyypissä Viittaukset Value Setteihin, jotka määrittävät käytettävien kooditettujen elementtien tietojen sisällöt Capability Statement Resurssi, joka käyttää muita Conformance resursseja dokumentoimaan, miten asiakaspää (client) tai palvelin (server) toteuttavat FHIRiä Esim. mitkä standardin tukemat paradigmat ja API ominaisuudet ovat toteutettu ja miten MessageDefinition Resurssi, joka kuvaa sanomat, joita voidaan lähettää ja vastaanottaa Ml. tapahtumat jotka liittyvät sanomaviestintään, välitettävä sanoman tietosisältö, sanoman vastaanottajan vastuut OperationDefinition Resurssi, jolla voidaan kuvata lisäoperaatiot, jotka eivät löydy pohjastandardista SearchParameter Resurssi, jolla voidaan kuvata lisähakuominaisuukisa, joita ei löydy pohjastandardista CompartmentDefinition Resurssi, joka kuvataan resurssien loogista ryhmittely (käytetään pääsynhallinnassa ja hakujen kuvauksissa) DataElement Resurssi, jolla voidaan kuvata yhden yksittäisen erillisen tiedon rakenne (esim. raportointia varten)
17 FHIR ydinmäärittelyt tehty conformance resursseilla FHIR Core tietotyyppien määrittelyt FHIR Core resurssien määrittelyt REST operaatiot Standardissa määritellyt hakuparametrit Standardissa kiinnitetyt koodistot Profiilien määrittelyt Laajennusten määrittelyt Loogisten mallien (Logical Models) määrittelyt
18 StructureDefinition Julkaistaan rekisterissä Hyödynnettävissä ohjelmallisesti! Voidaan tehdä vertailua Voidaan tehdä muunnoksia Voidaan validoida resursseja Voidaan genoroida koodia Voidaan generoida käyttöliittymää
19 CapabilityStatement Määrittelee FHIR palvelimen kyvykkyydet Miten asiakaspää (client) tai palvelin (server) toteuttavat FHIRiä Mitkä standardin paradigmat tuettuna Mitkä REST ominaisuudet ovat toteutettu ja miten Mitkä hakuparametrit per resurssi käytössä Tuetut formaatit XML, JSON, RDF Tuetut resurssityypit Operaatiot Tuetut profiilit Tietoturvapalvelut Sitoo Conformance resursseja yhteen Hyödynnettävissä ohjelmallisesti
20 OperationDefinition Määrittelee REST interaktiot Operaation nimi Input/output parametrit Toiminnan kuvaus Mille resursseille määritelty Voidaan laajentaa ja rajoittaa perus REST APIa Hyödynnettävissä ohjelmallisesti
21 SearchParameter Määrittelee nimetyt REST APIssa käytettävät hakuparametrit Nimi Miten hakuparametriin viitataan client-päässä Miten hakuparametria käsitellään palvelinpäässä Mitä resurssin elementtiä hakuparametri vastaa Voidaan laajentaa ja rajoittaa perus REST APIa Hyödynnettävissä ohjelmallisesti Lisähakukriteerien määrittely Hakukriteerit voidaan jakaa eri kategorioihin: Haut, jotka kohdistuvat ydinelementteihin mutta näille ydinelementeille ei ole standardissa hakukriteerejä (esim. Haetaan havaintoja, jotka kuuluvat normaaliin viitearvoon) Haut, jotka kohdistuvat tiettyyn laajennukseen Haut, jotka eivät kohdistu yhteen tiettyyn elementtiin vaan näiden elementtien yhdistelmiin tai elementteiin kohdistuvaan laskentaan (esim. Haetaan tietyn ikäisiä potilaita) Nämä lisähaut määritellään SearchParameter resurssilla.
22 ImplementationGuide Kuvaa käytön kohdeympäristön/kontekstin Kuvaa vaatimukset FHIR toteutukselle Määrittelee linkit Oleellisiin FHIR artifakteihin (profiilit, muut soveltamisohjeet) Oppaan toimittamiseen liittyvät tiedot Käyttö Mahdollistaa implementointioppaan julkaisun Mahdollistaa työkalupohjaiset määrittelyjen mukaisuuden validoinnin Hyödynnettävissä ohjelmallisesti
23 Resurssien tunnisteet (Canonical Url) Conformance resurssin yksilöivä tunniste Käytetään viittauksissa conformance resurssiin Resurssin määrittelijän määrittelmä HUOM. Ero resurssin loogiseen id:hen, joka on serverin muodostama Esim. http://hl7.org/fhir/structuredefinition/observation http://hl7.org/fhir/structuredefinition/vitalsigns http://hl7.org/fhir/structuredefinition/11179-de-administrative-status http://hl7.org/fhir/structuredefinition/humanname http://phr.kanta.fi/structuredefinition/fiphr-bloodglucose-stu3
Profiilit / profilointi 24
25 FHIR:n profilointi Profiloinnin kaksi kohdetta CapabilityStatement resurssi StructureDefinition resurssi
CapabilityStatement 26
27 CapabilityStatement Määrittelee FHIR palvelimen kyvykkyydet Miten asiakaspää (client) tai palvelin (server) toteuttavat FHIRiä Tuetut formaatit Tuetut resurssityypit Operaatiot Tuetut profiilit Tietoturvapalvelut
28 FHIR:n profilointi - CapabilityStatement APIn kuvaaminen ja rajoittaminen Listaa REST interaktiot (read, update, search, jne.), jotka resurssipalvelin tarjoaa + jokaiseen inteaktioon liittyvät lisätiedot Voidaan käyttää listaamaan myös joukko tuettuja toiminnallisuuksia (esim. välttämättä kaikki REST interaktiot ei käytettävissä). Ainoa pakollinen interaktio ja toiminnallisuus on itse CapabilityStatement resurssin noutaminen palvelimelta. APIn laajentaminen FHIRin tarjoamien operaatioiden lisäksi palvelimet voivat tarjota myös erikseen määriteltyjä lisäoperaatioita (jotka eivät ole osa FHIR standardia) Nämä määritellään Operation frameworkilla ja OperationDefinition resurssilla (tunnistaa etuliitteestä $)
29 Esim. Kanta PHR CapabilityStatement http://fhirsandbox.kanta.fi/phr-resourceserver/basestu3/metadata
30
StructureDefinition 31
32 FHIR:n profilointi - StructureDefinition (FHIR Core tietotyyppien ja resurssien määrittelyt ovat StructureDefinition resursseja) Resurssin laajentaminen ja rajoittaminen Edellisistä johdettujen profiilien määrittelyt Laajennusten määrittelyt Yleensä kun puhutaan resurssin profiloinnista, tarkoitetaan StructureDefinition resurssin profilointia Jatkossa koulutuksessa keskitytään nimenomaan StructureDefinition resurssin profilointiin
33 StructureDefinition resurssi Resurssin rakennekuvauksen sisällön yleistiedot / ominaisuudet Canonical Url Nimi (Name), Otsikko (Title) Status (draft, active) Päivämäärä (Date), Versio (Version, author assigned) Tekijä (Author), Julkaisija (publisher), Yhteystiedot (contact), Profiili johon rakenne pohjautuu (Base profile)
34 StructureDefinition resurssi Mapping: Ulkoiset määrittely, johon sisältö voidaan mapata Differential vs Snapshot Element ElementDefinition Resurssin tietolementtien määrittelyt (ElementDefinitions) Nimi (Name), kardinaliteetit (cardinality), tietotyyppi (data type) Määritelmät (Definitions), käytön huomiot (usage notes), vaatimukset (requirements) Oletus (Default) tai vakioarvot (fixed values) Rajoitukset (constraints), pituusrajat (length limits) Koodistojen kiinnittämiset (Terminology bindings) Mappaukset toisiin määrittelyihin (Mappings to other specifications)
35 Differential vs. Snapshot Differential Component Lista elementtien rajoituksista, joita profiilissa on määritelty Määrittelee vain elementtien rajoitukset Mallintajan ylläpitämä Suhteellisen pieni tiedostokoko (KBs) Voidaan hyödyntää tehokkaaseen tietojen vaihtamaiseen ja tallentamiseen (riippuen hyödyntävän järjestelmän kyvyistä) Snapshot Component Täydellinen lista kaikista resurssien ja tietotyyppien elementtien määrittelyistä Määrittelee kaikki rajoitukset + määrittelyt jotka periytyvät pohjamäärittelystä (resurssi, tietotyyppi) Ohjelmallisesti muodostettava (FHIR Operation) Suhteellisen suuri tiedostokoko (MBs) Prosessointia varten (validointi, koodin generointi jne.)
36 FHIR rakenteen määrittely (StructureDefinition) Resource BackboneElement Backbone: Rakenne-elementti useammasta elementistä koostuvalle rakenteelle (ei ole tietotyyppi) DomainResource Primitive Data Type StructureDefinition Resurssi Tietotyyppi Laajennus Profiili Element ElementDefinition Complex Data Type Metadata Data Type Spec.purp. Data Type
37 StructureDefinition resurssin käyttäminen StructureDefinition resurssilla (profiililla) voidaan määritellä rajoituksia FHIR resurssin elementteihin tai tietotyyppeihin, tai lisärajoituksia jo olemassa oleviin profiileihin. StructureDefinition:ssa otetaan käyttöön koko rakenteelle tai tietylle elementille määrittellyt laajennukset StructeDefinition tunnistetaan yksiöllisellä URL:lla ja tämän URL:in pitäisi olla sama jota käytetään StructureDefinition:in julkaisussa. StructeDefinition on käytännössä lineaarinen lista elementtien määrittelyjä (ElementDefinitions)
38 StructureDefinition resurssin käyttäminen Elementin kardinaliteetin muuttaminen, esim. pohjaresurssi sallii 0..*, tämä voidaan rajoitaa tukemaan vain 1..2 Elementti voidaan poistaa käytöstä määrittelemällä max. kardinaliteetti 0 Elementin sisältö voidaan rajoittaa tiettyyn fiksattuun arvoon (fixed value) Tehdä lisärajoituksia syvemmällä hierarkiassa oleviin elementteihin (ei vain päätasolle)
39 StructureDefinition resurssin käyttäminen Rajoittaa vain tietyt sallitut elementin tyypit, jos elementissä sallittu useita eri tyyppejä (choice) Vaatia elementin tietotyypille käytettäväksi tietotyypille määritelty profiili (tietotyyppiä voidaan rajoittaa myös suoraan profiilissa mutta rajoitus on tällöin profiilikohtainen) Tehdä toistuville elementeille elementtikohtaisia rajoituksia (slicing, slaissaus ) Määrittää koodatulle tiedolle sidonta tiettyyn ValueSet:iin
40 StructureDefinition resurssin käyttäminen Tarkentaa / muuttaa elementtien määritelmiä, kommentteja, käyttöohjeita vastaamaan profiilin käyttökontekstia Määrittää tarkempia tai lisämappauksia (esim. verrattuna HL7 v2 tai HL7 v3) Määrätä, että yhtä tai useampaa rakenteen elementtiä on pakko tukea (must support)
Resurssin profilointi esimerkkejä Vaaditaan, että identierissa on käyttävä kansallista tunnistetta Rajoitetaan nimen toistuminen 0..1 (instead of 0..*) Sidotaan maritalstatus tietoon uusi valueset, joka laajentaa HL7 kansainvälistä valuesettiä Lisätään laajennus RaceCode Huom. Pohjassa ei juuri mitään pakollista. 41
Määritelmien, kommenttien, vaatimusten jne määrittely vastaamaan profiilin käyttökontekstia Käytännössä ylikirjoitetaan pohjamäärittelyn elementtien kenttiä short : string 1..1 formal : string 1..1 comments : string 0..1 requirements : string 0..1 synonym : string 0..* example[x] : 0..1 (example value!) mappings : 0..* (more specific mappings) 42
Rakenteinen ja julkaistavissa Profiili on normaali resurssi -> Minkä tahansa FHIR palvelimen pitäisi pystyä tukemaan profiilia (kuten se tukee Patient, Observation jne resursseja) -> Mikä tahansa FHIR palvelin on tavallaan profiilirekisteri -> Resurssi ja profiili periaatteessa lähetettävissä yhdessä samassa bundle rakenteessa (jos palvelin tukee Bundle resurssia, ja tietyn profiilin mukaista resurssia, yleensä profiilit ladataan erikseen palvelimelle) Jokaiseen profiiliin voi viitata sen URI:lla e.g. https://hl7.org/fhir/structuredefinition/iso-21090 43
Profiilien käyttäminen Kun resurssi-instansseja välitetään, niissä viitataan profiiliin jota instanssi noudattaa Palvelimelle voidaan määritellä, että se hyväksyy vain resurssiinstanseja, joissa viitataan tiettyyn profiiliin ja resurssi-instanssin on oltava tämän profiilin mukainen Palvelin validoi resurssi-instanssin profiilia vasten 44
45 Viittaaminen profiiliin resurssi-instanssissa Observation pituusmittauksen resurssiinstanssi - Observation.code: 8302-2 - Observation.valueQuantity: 178 cm - Observation.meta.profile: http://phr.kanta.fi/structuredefinitio n/fiphr-bodyheight-stu3 Validoi Obsrvation pituusmittauksen profiili (Kanta PHR Body height) - Loinc code: 8302-2 - UCUM unit: cm - url: http://phr.kanta.fi/structuredefinitio n/fiphr-bodyheight-stu3
Profilointikäytänteitä / -ohjeita 46
47 Suunnittelu Tarkasta löytyykö jo jotain valmista Uudelleenkäytä (kansalliset) profiileita Valitse käytätkö avointa mallinnusta (Open modeling) vai suljettua mallinnusta (closed modeling) Noudata sovittua nimeämistapaa
48 Mitä löytyy valmiina FHIR standardista Profiilirekistereistä Simplifier FHIR registry
49 Uudelleenkäytä (kansalliset) profiileita Resurssit Ydin (Core) resrussit Suomi profiilit US profiilit Kansalliset profiilit PHR profiilit Organisaatiokohtaiset profiilit
50 Avoin vs suljettu mallinnustapa Riippuen projektin scopesta, voi miettiä käytetäänkö avointa vai suljettua mallinustapaa Avoin mallinnustapa on geneerisempi, siinä käytetään vähemmän rajoituksia ja se on näin joustavampi Suljettu mallinnustapa on tarkempi ja siinä on käytössä enemmän rajoituksia. Suljetussa mallissa voidaan sopia tarkemmin millaista data otetaan vastaan, joka puolestaan voi nopeuttaa järjestelmien rakentamista (vähemmän välitettävää tietoa, yksinkertaisemmat tietokannat jne.)
51 Avoin vs suljettu mallinnus Plussat Miinukset Avoin mallinnus Eteenpäin yhteensopivuus Fokus siinä, mitä kaikkea pitää tukea Geneerisempi tietojen soveltuvuus Toteuttajat voivat joutua tukemaan kaikkien elementtejä. Isommat ja epätarkemmat mallit Vähemmän palautetta toteuttajilta Suljettu mallinnus Ei tarvitse tukea kaikkia elementtejä Tarkemmat mallit Pienemmät ja suoraviivaisemmat mallit Enemmän toteuttajien palautetta Enemmän tietokohtaisia malleja. Vain taaksepäin yhteensopivuus Uudet elementit vaativat uudet versiot
52 Nimeämistavat Example Nictiz: http://[domain]/fhir/[conformanceresource]/[project]-[name]- [semver.major] http://fhir.nl/fhir/structuredefinition/nl-core-patient http://nictiz.nl/fhir/structuredefinition/zib-dispense-1.0 Example Germany: http://fhir.de/structuredefinition/condition-de-basis http://fhir.de/structuredefinition/condition-de-icd10gm Kanta PHR Finnish PHR profiling guidelines http://www.kanta.fi/documents/12105/4106842/finnish+phr+profiling+guidelines/abf8 af44-ba9c-460c-bee5-407d10928a49
53 Versiointi non breaking change(s) Muutokset eri versioiden välillä yhteensopivia Vanha data Voidaan validoisa uutta profiilia vasten Tulkita oikein uutta profiilia vasten Tällöin voidaan käyttää profiilin tunnisteena samaa URLia (canonical url) FHIR Version management policy https://www.hl7.org/fhir/versions.html
54 Versiointi - breaking changes Epäyhteensopivaa aiempien profiilien kanssa Tällöin profiileille täytyy määritellä uusi tunnisteena käytettävä URL canonical url) Julkaistujen profiilien ja datojen kanssa sovittava erikseen miten toimitaan