Kalenderelement iCalendar
iCalendar (se http://tools.ietf.org/html/rfc5545) benyttes for å overføre informasjon om timeavtaler. Dette gjelder alle de bruksområdene for timeavtaler, som for eksempel:
Timevisning
Timebestilling
Avbestilling av avtale
Timedialog
Timeendring
Timeendringsønske
Informasjon om timer vil kommuniseres ved bruk av xCal standarden som er XML representasjon av iCalendar kalenderinformasjon, for generell beskrivelse av standarden se http://tools.ietf.org/html/rfc6321 .
iCal-standarden er utvidet med noen spesifikke attributter for Helsenorge. Det skal sendes gyldig innhold i henhold til skjema iCalendar.xsd.
xCal versjon 2.0 skal benyttes
Skjemaet definerer ikke makslengder eller innhold i felter. Men for Digital dialog med innbygger er det innført begrensninger i brukergrensesnitt for feltlengder og ved lagring av data. Begrensninger er vist i tabellen under, dersom det sendes innhold lenger enn dette vil Helsenorge sende negativ AppRec (kode X99) på meldingen med informasjon om hvilket felt er for langt.
Element | Obligatorisk eller valgfri | Beskrivelse | Begrensning på innhold |
|---|
Element | Obligatorisk eller valgfri | Beskrivelse | Begrensning på innhold |
|---|---|---|---|
xcal:vcalendar.properties.version | Obligatorisk | Versjon av iCalendar standarden som benyttes |
|
xcal:vcalendar.properties.prodid | Obligatorisk | Produktidentifikasjon av det produktet som genererte iCalendar objektet |
|
xcal:components | Obligatorisk | Angis på selve vcalendar objektet som inneholder alle vevent. På hver vevent må det også angis for å validere ihht XSD. <xcal:components/> |
|
xcal:dtstart | Obligatorisk | Starttidspunkt for time | Tidssone skal være norsk tidssone:
Format: yyyy-MM-ddTHH:mm:ss |
xcal:dtend | Obligatorisk | Sluttidspunkt for time. | Tidssone skal være norsk tidssone:
Format: yyyy-MM-ddTHH:mm:ss |
xcal:uid | Obligatorisk | Id for time på formatet UUID | Id for time på formatet UUID |
xcal:contact | Obligatorisk | HER-id for kommunikasjonspart som timen tilhører (xcal:contact). Denne er nødvendig for å vite mottager for operasjoner som er tilgjengelig på en timeavtale, slik som avbestilling for en mottatt avtale. Det støttes mottak av denne av historiske grunner, men den blir ikke brukt og trenger ikke å være med. |
|
xcal:related-to | Valgfri | Id for relatert timeavtale, skal oppgis dersom denne id-en eksisterer. Denne benyttes i to tilfeller:
|
|
xcal:categories | Valgfri | Benyttes for å angi timetype, se eget avsnitt kategorisering av avtaler. | Kodeverk "Timetype Innbyggerportal" med id 7617: https://finnkode.helsedirektoratet.no/adm/collections/7617?q=7617 Ved angivelse av flere kategorier så er eneste tillatte kombinasjon “Hastetime” og “Video“ |
xcal:summary | Valgfri | Benyttes for å angi oppsummering av avtale. For hjemmebaserte tjenester navn på tjenesten som utføres, f.eks. «Praktisk Bistand» eller «Hjemmesykepleie». Vises på Helsenorge som “Timen Gjelder” | Maks 192 tegn |
xcal:description | Valgfri | Angir fritekstinformasjon om avtalen. | Maks 1000 tegn |
xcal:rrule | Valgfri | Regelmessighet. Gjentagelse brukt ved planlagte besøk og eventuelle unntak fra gjentagelse, bruk av Rrule element. Støttes kun for hjemmebesøk
| Les mer under seksjonen “Angivelse av regelmessige avtaler i iCalendar”. |
xcal:xdate | Valgfri | Angit datoer som skal eksluderes fra regelmessighet. Støttes kun for hjemmebesøk | Les mer under seksjonen “Angivelse av regelmessige avtaler i iCalendar”. |
xcal:location | Valgfri | Angivelse av hvor avtalen finner sted. | Maks 255 tegn |
xcal:status | Valgfri | Angivelse av status for avtalen. Støttes kun for hjemmebesøk | Følgende koder støttes:
|
xcal:x-cancellation-reason | Valgfri | Angir hvorfor en avtale har status avlyst. Ved angivelse av verdi som ikke er støttet settes default Avlyst av tjeneste. Brukes for hjemmebesøk. | Følgende verdier er støttet:
|
xcal:x-referral-id | Valgfri | Referanse til henvisningsid Støttes kun for spesialisthelsetjenesten. | Skal være en henvisnings-id |
xcal:attendee | Valgfri | Angivelse av deltagere i avtalen, benyttes blant annet for ansatte som utfører besøk. Mulig å angi flere. Støttes kun for hjemmebesøk | Se informasjon her: |
xcal:organizer | Valgfri | Angivelse av organisasjonen som utfører avtalen. | Se informasjon her: iCalendar - organizer |
xcal:x-available-at | Valgfri | Angivelse av tidspunkt avtalen tilgjengeliggjøres eller gjøres valgbar for innbygger. Benyttes ved visning av ledige tidspunkt for timebestilling, ikke relevant for annen bruk. | Tidssone skal være norsk tidssone:
Format: yyyy-MM-ddTHH:mm:ss |
xcal:x-servicetype | Valgfri | Angir alderstrinn for helsestasjoner og skolehelsetjenesten. Brukes for å vise standardisert informasjon om en timeavtale. | Maks 20 tegn Kodeverk "Alderstrinn" med id 9505: |
xcal:x-contact-type | Valgfri | Angir møteform. Telefon/Video Støttes kun for timeønskeungdom | Maks 255 tegn |
XML eksempel på iCalendar med svar fra fastlegen vedørende bekreftelse av reservasjon av en time:
<xcal:vcalendar>
<xcal:properties>
<xcal:prodid>
<xcal:text>System NN</xcal:text>
</xcal:prodid>
<xcal:version>
<xcal:text>2.0</xcal:text>
</xcal:version>
</xcal:properties>
<xcal:components>
<xcal:vevent>
<xcal:properties>
<xcal:dtstart>
<xcal:date-time>2012-02-13T09:15:00</xcal:date-time>
</xcal:dtstart>
<xcal:dtend>
<xcal:date-time>2012-02-13T09:30:00</xcal:date-time>
</xcal:dtend>
<xcal:summary>
<xcal:text>Konsultasjon med lege NN</xcal:text>
</xcal:summary>
<xcal:description>
<xcal:text>Din time er bekreftet. Du får SMS påminnelse før konsultasjonen. Mvh. Legekontor NN.</xcal:text>
</xcal:description>
<xcal:uid>
<xcal:text>012d1e50-760e-11e2-bcfd-0800200c9a66</xcal:text>
</xcal:uid>
<xcal:contact>
<xcal:text>91095 </xcal:text>
</xcal:contact>
<xcal:related-to>
<xcal:uri>651b1341-26ca-11e4-8c21-0800200c9a66</xcal:uri>
</xcal:related-to>
</xcal:properties>
<xcal:components/>
</xcal:vevent>
</xcal:components>
</xcal:vcalendar>En endring kan være hvilke som helst informasjon som er synlig for innbygger:
Start-/slutt tidspunkt
Oppmøtested
Avtaletype (endret til/fra video/telefon time / fysisk oppmøte)
Hva timen gjelder
Beskrivelse
Behandler
...
Endring som trigger varsel om endret timeavtale
Hvis en time blir endret, sendes det varsel med informasjon om at timen er endret. For å regnes som endret må oppmøtested, starttid eller timetype. Andre endringer vil vises, men ikke varsles.
Identitethåndtering ved endringer
Følgende identiteter brukes for å identifisere hvilke timeavtale på Helsenorge endringen gjelder. For å finne treff på timeavtale som skal oppdateres så sjekkes verdiene i skrivende rekkefølge. Ved ingen treff vil timeavtale tolkes som ny.
Verdi | Er påvkrevd | Kommentar |
|---|
Verdi | Er påvkrevd | Kommentar |
|---|---|---|
Related-to fra iCalendar | Valgfri | Forventes være statisk verdi på tvers av endringer. Verdien skal peke på opprinnelige timeavtale. Dersom related-to er lik en eksisterende avtales related-to, eller peker på en eksisterende avtales uid så vil den eksisterende avtalen oppdateres. |
Uid fra iCalendar | Påkrevd | Id for time på formatet UUID (xcal:uid) Dersom uid er lik en eksisterende avtales uid så vil den eksisterende avtalen oppdateres. Dersom uid endrer seg (når uid representerer et konkret tidspunkt), så skal related-to brukes for å identifisere eksitserende avtale. |
RefToConversation / RefToParent fra Hodemeldingen | Valgfri | Dersom ingen treff på related-to/uid så gjøres en sjekk på RefToConversation/RefToParent. Det gjør det mulig å finne eksisterende timeavtale når innbygger har sendt forespørsel. Ikke ment som primær identitet for å finne eksisterende timeavtale. |
Oppførsel ved endrete felter
For noen felter beholder vi forrige verdi dersom en endret timeavtale ikke har med dette feltet og for noen fjerner vi informasjonen dersom de ikke er med. Her er en liste over de ulike feltene og hvordan de oppfører seg ved timeendring:
Element | Kategori | Forklaring av logikk ved manglende |
xcal:version | Obligatorisk | Dette er et påkrevd felt, og må alltid være med |
xcal:prodid | Obligatorisk | Må alltid være med for å identifisere systemet som genererte avtalen |
xcal:uid | Obligatorisk | Dette er et påkrevd felt, og må alltid være med |
xcal:dtstart | Obligatorisk | Dette er et påkrevd felt, og må alltid være med |
xcal:dtend | Oppdateres kun hvis verdi er satt | Beholder gammel verdi hvis feltet mangler eller er blankt og den har vært satt tidligere |
xcal:contact | Obligatorisk. Informasjonen fra denne brukes ikke på Helsenorge, da det er teknisk avsender i hodemeldingen som brukes for adressering | Dette er et påkrevd felt, og må alltid være med |
xcal:summary | Oppdateres kun hvis verdi er satt | Beholder gammel verdi hvis feltet mangler eller er blankt og den har vært satt tidligere |
xcal:description | Oppdateres alltid | Oppdateres uansett, blank tolkes som sletting |
xcal:categories | Gruppetime: Oppdateres alltid | Her er det noe ulik oppførsel avhengig av hva slags kategori man snakker om |
xcal:x-servicetype | Oppdateres kun hvis verdi er satt | Beholder gammel verdi hvis feltet mangler eller er blankt og den har vært satt tidligere |
xcal:status | Oppdateres kun hvis verdi er satt | Beholder gammel verdi hvis feltet mangler eller er blankt og den har vært satt tidligere |
xcal:x-cancellation-reason | Oppdateres kun hvis verdi er satt | Beholder gammel verdi hvis feltet mangler eller er blankt og den har vært satt tidligere |
xcal:rrule | Ikke relevant med endring | Dersom denne sendes med, så ignoreres den da vi bare bruker den ved å gjøre oppslag på timer fra hjemmetjenesten. |
xcal:related-to | Brukes for å indentifisere original timeavtale dersom uid er endret på den originale avtalen | Brukes for å identifisere hvilke timeavtale som skal oppdateres. |
xcal:location | Oppdateres og fjernes hvis blank | Oppdateres uansett, blank tolkes som sletting |
xcal:attendee | Oppdateres og fjernes hvis blank. | Oppdateres uansett, blank tolkes som sletting
Brukes kun for hjemmetjeneste |
xcal:organizer | Oppdateres og fjernes hvis blank | Oppdateres uansett, blank tolkes som sletting |
xcal:x-available-at | Ikke relevant med endring | Tidspunkt avtalen blir tilgjengelig. Dette feltet gir ikke mening ved oppdatering av en timeavtale, da det brukes før en avtale bookes. |
xcal:x-servicetype | Oppdateres og fjernes hvis blank | Oppdateres uansett, blank tolkes som sletting |
xcal:x-contact-type | Oppdateres og fjernes hvis blank | Oppdateres uansett, blank tolkes som sletting |
For å kunne angi referanse til intern henvisningsid i meldingen mellom http://helsenorge.no og spesialisthelsetjenesten er det lagt til et egendefinert element «x-referral-id» i xCal for dette.
Element «x-referral-id» er definert i en egen xsd (iCalendar-DigitalDialogSpesialist-extensions.xsd) som må inkluderes fra iCalendar.xsd. Denne metoden for å legge til egendefinerte elementer er i henhold til slik det er beskrevet i selve xCal/iCalendar standarden.
For å kunne bruke element «x-referral-id» i XML-meldinger må exstensions-skjemaet iCalendar-DigitalDialogSpesialist-extensions.xsd være inkludert fra iCalendar.xsd, og iCalendar-DigitalDialogSpesialist-extensions.xsd må være tilgjengelig.
XML eksempel på iCalendar med informasjon om en time som har henvisning:
<xcal:vcalendar>
<xcal:properties>
<xcal:prodid>
<xcal:text>System NN</xcal:text>
</xcal:prodid>
<xcal:version>
<xcal:text>2.0</xcal:text>
</xcal:version>
</xcal:properties>
<xcal:components>
<xcal:vevent>
<xcal:properties>
<xcal:dtstart>
<xcal:date-time>2015-08-13T09:00:00</xcal:date-time>
</xcal:dtstart>
<xcal:dtend>
<xcal:date-time>2015-08-13T10:30:00</xcal:date-time>
</xcal:dtend>
<xcal:summary>
<xcal:text>Kontrolltime</xcal:text>
</xcal:summary>
<xcal:uid>
<xcal:text>abc123</xcal:text>
</xcal:uid>
<xcal:x-referral-id>
<xcal:text>xyz789</xcal:text>
</xcal:x-referral-id >
</xcal:properties>
<xcal:components/>
</xcal:vevent>
</xcal:components>
</xcal:vcalendar>EPJ-systemet kan kategorisere avtaler for å angi mer detaljert type avtale. For dette er det etablert et kodeverk "Timetype Innbyggerportal" med id 7617: https://finnkode.helsedirektoratet.no/adm/collections/7617?q=7617 .
Elementet «categories» i iCalendar skal brukes til å angi timetype, dersom det ikke behøves eller er angitt noen spesifikk timetype skal elementet «categories» ikke brukes. Kodeverket som benyttes angis ikke i Categories.
Det er støtte for flere timetyper samtidig, men bare noen kombinasjoner er tillatt. Per i dag er den eneste tillatte kombinasjonen ved avtaleutsending “Hastetime” og “Video“. Dersom flere kategories sendes, er det kun den første angitte som benyttes.
Følgende verdier av timetype er tatt i bruk:
"Ordinær". Ordinær time, ved fravær av timetype benyttes denne som default - (brukes ved bestilling, timevisning og varsling).
"Hastetime". Benyttes for hastetimer - (brukes kun ved timebestilling)
"Video". Avtalen er en videotime - (brukes ved bestilling, timevisning og varsling)
“Telefon”: Avtalen gjennomføres på telefon - (brukes ved bestilling, timevisning og varsling)
"Tidsvindu". Benyttes for hjemmebesøk - (brukes kun ved timevisning)
"Gruppetime". Avtaler som inneholder flere pasienter
Alle under, - brukes ved bestilling, timevisning og varsling:
"Vaksine". Time for vaksinering, Kan gi eget varsel og visning til innbygger
"Lab". Time på lab, Kan gi eget varsel og visning til innbygger
"Koronatest". Kan gi eget varsel for time for koronatest, innført for pandemien
"Koronavaksine". Kan gi eget varsel for time for koronavaksine, innført for pandemien
Et eksempel på angivelse av en hastetime på video er vist under.
<xcal:categories>
<xcal:text>Hastetime</xcal:text>
<xcal:text>Video</xcal:text>
</xcal:categories> EPJ-systemet kan angi om en planlagt avtale er et tidsvindu når informasjon om planlagte avtaler sendes til http://helsenorge.no . Med tidsvindu menes en avtale der start og stopp indikerer en forventet periode der avtalen inntreffer, uten at avtalen forventes å vare hele perioden. Et eksempel på et tidsvindu er en avtale som inntreffer en gang mellom 10:00 og 12:00 og forventes å vare i 30 minutter.
Timene vil vises ulikt for innbygger på http://helsenorge.no for å tydeliggjøre dette.
Dersom timen er et tidsvindu kan også forventet varighet på avtalen angis. For standard avtaler kan start og stopp eller start og duration angis, det er ikke mulig å oppgi start, stopp og duration. Det er derfor lagt til en custom extension for å støtte dette, x-expected duration.
Merk: Inntil 31.10.2023 var eksempelet for duration feil i henhold til Iso spesifikasjonen. Tidligere var det angitt “P30M” for å angi 30 minutter, riktig er “PT30M”
Angivelse av et tidsvindu med en avtale med antatt varighet på 30 min er vist under:
<xcal:categories>
<xcal:text>Tidsvindu</xcal:text>
</xcal:categories>
<xcal:x-expected-duration>
<xcal:duration>PT30M</xcal:duration>
</xcal:x-expected-duration> Timeboken kan angi tidspunktet for når avtalen blir tilgjengelig for bestilling. Timen gjøres først valgbar for innbygger når dagens tidspunkt er likt eller overstiger tidspunktet angitt. Før dette tidspunktet vises avtalen som ikke bestillbar.
Elementet er en utvidelse av iCalandar standarden, XML eksempel er vist under.
<xcal:x-available-at>
<xcal:date-time>2018-07-25T08:00:00</xcal:date-time>
</xcal:x-available-at>Elementet skal ikke benyttes sammen med timer som ikke kan bestilles på nett. Det vil si timer som har kategori="Must-call" skal ikke ha dette feltet angitt, og http://helsenorge.no vil overse elementet i dette tilfellet.
Ved henting av ledige timer kan timeboken angi at en time ikke kan bestilles elektronisk. Elementet «categories» i iCalendar skal brukes til å angi ikke bestillbar time. Følgende verdi skal benyttes for dette.
"MustCall". Benyttes for å vise at en time ikke er tilgjengelig for elektronisk bestilling og innbygger må kontakte behandler på annen måte.
Denne verdien er bare relevant ved henting av ledige timer, ved overføring av bekreftede timer skal denne ikke benyttes.
Kategorien "MustCall" som angir en time som ikke kan bookes på nett kan kombineres med andre timetyper. I tillegg kan noen timetype kombineres med tidspunkt for tilgjengeliggjøring. Tabellen under viser lovlige kombinasjoner og funksjonell betydning.
Kombinasjonene benyttes kun ved henting av ledige timer, dersom en time allerede er bekreftet skal MustCall og available-at ikke benyttes.
Timetype | Bestillbar | available-at | Betydning |
(Ingen) |
| (ingen) | Vanlig konsultasjon, timetype ikke angitt |
(Ingen) |
| Tidspunkt | Vanlig konsultasjon, tilgjengelig for booking etter angitt tidspunkt |
(Ingen) | MustCall | N/A | Vanlig konsultasjon som ikke kan bookes på nett |
Hastetime |
| (ingen) | Hastetime |
Hastetime |
| Tidspunkt | Hastetime, tilgjengelig for booking etter angitt tidspunkt |
Hastetime | MustCall | N/A | Hastetime som ikke kan bookes på nett |
Video |
| (ingen) | Videotime |
Video |
| Tidspunkt | Videotime, tilgjengelig for booking etter angitt tidspunkt. |
Video | MustCall | N/A | Videotime som ikke kan bookes på nett |