RIV Tekniska Anvisningar

Binära bilagor

Version 1.1

ARK_0038

2019-11-06

Inledning

Denna anvisning beskriver regler för överföring av binära bilagor till tjänstekontrakt inom ramen för RIV Tekniska Anvisningar. Anvisningen ger möjlighet till två metoder att överföra bilagor: inbäddat i ett tjänstekontrakt, eller via en extern URL, refererad från ett tjänstekontrakt.

1.1 Revisionshistorik

Version	Författare	Kommentar
0.1	Johan Eltes	Utkast till anvisning
1.0_RC1	Mattias Nordvall	Skrivit bakgrundstexter, skapat exempelmeddelanden och strukturerat regler.
1.0_RC2	Johan Eltes	Redigerat formuleringar.
1.0_RC3	Mattias Nordvall	Tagit bort kravet att ”value” och ”reference” inte får användas samtidigt. Ändrat krav på vilka MIME-typer som får användas i ”mediaType”.
1.0_RC4	Johan Eltes	Lagt till ny regel om asynkronitet, samt numrerat om efterföljande regler.
1.0	Mattias Nordvall	Första publicerade versionen.
1.1	Björn Hedman	Rättat fel i exempel i 3.2.1 och 3.2.2 förtydligat regel 1 i kapitel 4 förtydligat att listan i Kapitel 5 bara är ett exempel

1.2 Definitioner

Följande termer förekommer i anvisningen:

Definition	Beskrivning
Informationsproducent	En organisation som tillgängliggör information till en annan part. Kan vara antingen tjänstekonsument eller tjänsteproducent i en tjänsteinteraktion.
Informationskonsument	En organisation som tar emot information från en annan part. Kan vara antingen tjänstekonsument eller tjänsteproducent i en tjänsteinteraktion.
MultimediaType	Den XML-typ som används för att förmedla information om en bilaga. Se kapitel 3.

1.3 Referenser

Följande referenser förekommer i anvisningen:

Nummer	Namn	URL
	RFC 2045	https://tools.ietf.org/html/rfc4648
	RIV TA Kryptografi	http://rivta.se/documents/ARK_0036/

Översikt

Bilageutväxling sker alltid inom ramen för ett tjänstekontrakt och det aktuella tjänstekontraktet bär referensen till bilagan som ska överföras. Det finns inget generellt bilage-tjänstekontrakt.

Binära bilagor kan överföras i såväl begäran som svaret i en tjänsteinteraktion. Format-definitionen för bilageinformationen är densamma i båda fallen, men har olika fältregler.

Denna anvisning beskriver två överföringsmetoder för bilagor:

- Inbäddad bilaga

- Refererad bilaga

2.1 Inbäddad bilaga

Metoden ”inbäddad bilaga” innebär att bilagan kodas om till textformat (base64) och inkluderas direkt i meddelandet. Denna metod kräver ingen ytterligare infrastruktur utöver vad som redan används för meddelandeutbyte inom RIV TA, men medför begränsningar, framför allt beträffande bilagans storlek.

Detaljerade regler för inbäddade bilagor finns i kapitel 4.1.

2.2 Refererad bilaga

Metoden ”refererad bilaga” innebär att informationsproducenten förmedlar en URL till en nedladdningsbar bilaga. Det ställer krav på att informationsproducenten behöver ha tillgång till infrastruktur för att publicera ”kortlivade länkar” och att informationssambandet mellan refererande journalinformation och refererad bilaga behöver finnas i vårdsystemet hos informationsproducenten.

Denna anvisning anger ingen begränsning beträffande storleken på refererade bilagor. Storleken kan dock begränsas för tillämpande tjänstekontrakt, och dokumenteras då i aktuell tjänstekontraktsbeskrivning.

2.2.1 Kortlivade länkar

Metoden ”refererad bilaga” använder konceptet ”kortlivade länkar”. En kortlivad länk är en URL som är giltig under en begränsad tidsperiod. Sådana länkar är vanligt förekommande för att t.ex. återställa sitt lösenord till en webbtjänst. I detta fall är den URL som informationsproducenten förmedlar en sådan kortlivad länk. Anledningar till att kortlivade länkar används i detta sammanhang är:

Bilagor betraktas på logisk nivå som en del av den information som förmedlas via ett tjänstekontrakt. Bilagan skall därför överföras till informationskonsumenten för lagring eller direktåtkomst tillsammans med refererande information. En beständig länk skulle kunna leda till tvetydigheter om vilken part som ansvarar för att upprätthålla bilagan över tid.
En bilaga kan under länkens livslängd genom oaktsamhet bli åtkomlig för andra än den avsedda mottagaren. Därför behöver ett tidsfönster för länkens giltighet finnas, för att minska effekterna av oaktsamhet.

Tjänsteproducenten tillgängliggör därför URL:en enbart under ett begränsat tidsfönster. Tidsfönstret skall vara stort nog för att mottagaren skall hinna hämta bilagan, även om tillfälliga driftstörningar inträffar, men litet nog för att inte under oskälig tid exponera bilagan.

Detaljer regler för refererade bilagor och kortlivade länkar finns i kapitel 4.2.

3. Meddelandeformat

Följande XML Schema-typ används för bilagor, såväl inbäddade som refererade:

<xs:complexType name="MultimediaType">
        <xs:sequence>
            <xs:element name="id" type="xs:string" minOccurs="0"/>
            <xs:element name="mediaType" type="codes:MediaTypeEnum"/>
            <xs:element name="value" type="xs:base64Binary" minOccurs="0"/>
            <xs:element name="reference" type="xs:anyURI" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

Schematypen distribueras inte i form av någon gemensam schemafil, utan infogas i lämplig schemafil i den aktuella tjänstedomänen.

3.1 Fältregler

Här följer anvisningar om fältinnehåll i MultimediaType.

Namn	Datatyp	Beskrivning	Kardinalitet
id	string	Identitet på bilagan. Används vid referenser inom en tjänsteinteraktion. Ev. formatregler på denna identitet uttrycks i aktuell TKB.	0..1
mediaType	MediaTypeEnum	Mediatyper i MIME-format. Listan med tillgängliga alternativ definieras per tjänstedomän och bör begränsas, då ett stort antal alternativ ökar införandekostnaden för mottagaren. Se bilaga för exempel.	1..1
value	base64Binary	Används vid inbäddad bilaga och innehåller då bilagans binärdata, kodat enligt base64. Om bilagan innehåller avkodad text ska denna vara avkodad från UTF-8-format.	0..1
reference	anyURI	Används vid refererad bilaga, och innehåller då den URL där bilagan kan hämtas.	0..1

3.2 Exempelmeddelanden

Här följer några exempel på meddelanden som använder de båda metoderna.

3.2.1 Exempel på inbäddad bilaga

Exemplet visar hur en inbäddad bilaga förmedlas via ett frågemeddelande. Samma metod kan även användas för att förmedla bilagor i svarsmeddelanden.

I det här fallet används MultimediaType i ett element kallat ”images”, som innehåller en base64-kodad representation av en 1 KB stor png-bild. Dessutom används det valfria elementet ”id”.

<ProcessImage>
    <patientId>121212-1212</patientId>
    <imageDate>20151105</imageDate>
    <images>
        <id>12983798123</id>
        <mediaType>image/png</mediaType>
        <value> iVBORw0KGgoAAAANSUhEUgAAACgAAAAYCAMAAAC/Wk/yAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyxpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NjcyOSwgMjAxMi8wNS8wMy0xMzo0MDowMyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIEVsZW1lbnRzIDEyLjAgTWFjaW50b3NoIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOjExMDhGMkVGN0ZEQzExRTU5Q0U3QjM1N0YyMUZERDI4IiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOjExMDhGMkYwN0ZEQzExRTU5Q0U3QjM1N0YyMUZERDI4Ij4gPHhtcE1NOkRlcml2ZWRGcm9tIHN0UmVmOmluc3RhbmNlSUQ9InhtcC5paWQ6MTEwOEYyRUQ3RkRDMTFFNTlDRTdCMzU3RjIxRkREMjgiIHN0UmVmOmRvY3VtZW50SUQ9InhtcC5kaWQ6MTEwOEYyRUU3RkRDMTFFNTlDRTdCMzU3RjIxRkREMjgiLz4gPC9yZGY6RGVzY3JpcHRpb24+IDwvcmRmOlJERj4gPC94OnhtcG1ldGE+IDw/eHBhY2tldCBlbmQ9InIiPz5uPEkYAAAAYFBMVEVCQUGvrq/a29sZGBjvhhyJiYbfYSQYpKfk5ub4zJ6r293////g39/v8fHrqlvHx8fruJi/4+hiyM/y/P339/fx5+X8/PxRs7f98eX++vj+9fL//Pqfnp/63MBzcnLT0tLhjtFbAAABPUlEQVR42oyS65KDIAyFgYBQLqKV0gso7/+Wm9B2Z3emo80PIMdvToKEuS+Dvfb7Ok2Xcgg+JjlgXI7AVcqByFZ2wXKSPYZh3ndEbuygDnkPfEi5lvsolb7u3/okT6Uss9balgNwdctstb6WfcdVjm62Z61N3gdvo5zOyNnDl7mN2J+el0NwWay1y3dvnfN3QxGqd4a7plSjlG/Ko8hTrjGLuin+BhtUx2EDBiBcwp1BRJEzqA0oUy8wAs8cWEwcalaAtoxlAaSQr2OQ3o4ExuQMgoyJJhR4D69Z9Xxj4Rd0Fas5DzVhfeqh4Zm+1Z6Hf44dzLAl400oooMKtobLBxDbe/6w1kHK8h+Qbh1zd8TrC1OZoDOBwquPpd19w6awfnfMkTpUbzCJ4IJIqAsachOjeYqomNhQTu5HgAEADb0qvmvhoMsAAAAASUVORK5CYII=</value>
    </images>
</ProcessImage>

3.2.2 Exempel på refererad bilaga

I det här exemplet förmedlas två bilagor via ett svarsmeddelande, men samma struktur kan även användas för att förmedla bilagor via ett frågemeddelande.

MultimediaType används i ett element med namnet ”imageData”, som här förekommer två gånger:

<GetImageResponse>
    <startDate>20151103</startDate>
    <endDate>20151109</endDate>
    <numberOfImages>2</numberOfImages>
    <imageData>
        <mediaType>image/jpeg</mediaType>
        <reference> https://attachment.landsting.se/get/f88bf2e4fa51455d8a9f305391f3d704</reference>
    </imageData>
    <imageData>
        <mediaType>image/jpeg</mediaType>
        <reference> https://attachment.landsting.se/get/1640551df160440393d3b7e0c72f764b</reference>
    </imageData>
</GetImageResponse>

4.Regler

Regel #1: Stöd och val av metod

En informationskonsument skall stödja båda metoderna ”inbäddad bilaga” och ”refererad bilaga” eftersom producenter kan välja metod utifrån sina förutsättningar och olika metoder för olika typer av bilagor i samma svar.

En informationsproducent kan välja att stödja en eller båda överföringsmetoderna. Om informationsproducenten inte har tillgång till infrastruktur för att publicera de kortlivade länkar som metoden ”refererad bilaga” kräver, kan metoden ”inbäddad bilaga” väljas. Hänsyn måste då tas till de begränsningar som denna metod medför.

En informationsproducent som stöder båda metoder, kan vid överföringsögonblicket välja vilken metod som ska användas. Även båda metoderna kan användas, exempelvis för att skicka en inbäddad lågupplöst bild och referera till en högupplöst motsvarighet.

Regel #2: Asynkron hantering

En informationskonsument som tar emot en bilaga i begäran (i rollen tjänsteproducent) skall hantera bilagan asynkront. Med asynkront menas att svar/kvittens skickas till tjänstekonsumenten innan bilagan hanteras. Det innebär att en inbäddad bilaga skall avkodas och lagras efter att svar returnerats till tjänstekonsumenten och att vid refererad bilaga hämta denna först efter att svarsmeddelande skickats till tjänstekonsumenten.

4.1 Inbäddad bilaga

Vid användning av inbäddade bilagor gäller följande regler:

Regel #3: Kodning av binär information

Den binära informationen skall kodas med base64 enligt RFC 4648, och placeras i elementet ”value” i MultimediaType.

Regel #4: Kodning av textinformation

Om bilagan är i textformat, i motsats till binärt format, skall dess teckenkodning vara av typen UTF-8, innan den base64-kodning som beskrivs i föregående regel sker.

Regel #5: Storleksbegränsningar vid bilaga i begäran

Om en bilaga förmedlas i begäran får frågemeddelandets totala storlek – inkl base64-kodad bilaga, inte överskrida 5 MB. Storleken kan begränsas ytterligare för tillämpande tjänstekontrakt. Begränsningen syftar till att säkerställa tjänsteplattformars tillgänglighet och transaktionslängd.

Regel #6: Storleksbegränsning vid bilaga i svar

Om en bilaga förmedlas i svaret i ett tjänstekontrakt som ska kunna anropas av aggregerande tjänster, får den base64-kodade bilagan inte överstiga 100 KB. Detta skall anvisas i aktuella tjänstekontrakt. Begränsningen är viktig för aggregerande tjänster eftersom enskilda tjänsteproducenter inte kan ta ansvar för storleken på det aggregerade svaret.

4.2 Refererad bilaga

Vid användning av refererad bilaga gäller följande regler:

Regel #7: Generering av URL

Informationsproducenten ansvarar för att generera den URL som bilagan ska tillgängliggöras via. URL:en skall vara absolut, dvs innehålla både protokoll (https) och fullständigt servernamn inkl. domännamn. Den ska dessutom innehålla en sträng med minst 32 slumpvis valda alfanumeriska tecken, t.ex. en UUID. Denna sträng skall vara unik för varje bilaga.

Den URL som genererats skall placeras i elementet ”reference” i MultimediaType.

Denna anvisning ställer inga krav på att filnamn eller filtyp ska ingå i URL:en. Filtyp kommuniceras istället via MIME-typer i elementet mediaType.

Exempel:

Regel #8: Tillgängliggörande av bilaga

Informationsproducenten ansvarar för att göra aktuell binärfil åtkomlig över Internet via HTTPS-protokollet och den genererade URL:en.

Konsumentspecifika brandväggsregler bör inte förekomma, då verksamhetens natur kan göra det svårt att med framförhållning kunna förutse vilka parter som behöver kommunicera.

Regel #9: Kryptering

Överföringen skall krypteras med protokollet TLS.

Se anvisningen RIV TA Kryptografi för aktuell konfiguration.

Regel #10: Autentisering

Vid hämtning av bilaga skall informationsproducentens infrastruktur initiera ömsesidig autentisering (TLS Mutual Authentication) med anslutande tjänstekonsument.

De certifikat som presenteras av parterna skall uppfylla följande krav:

Vara utfärdade av SITHS.
Vara giltiga beträffande datum.
Inte vara återkallat, dvs inte finnas med i en aktuell revokeringslista från certifikatutfärdaren.

Regel #11: Tidsfönster

Informationsproducenten skall tillgängliggöra bilagan via den förmedlade URL:en under minst 24 timmar. Detta för att kunna stödja ev. manuell hantering eller systemstörningar hos informationskonsumenten eller informationsproducent.

Därefter kan informationsproducenten välja att upphöra att tillgängliggöra bilagan via den förmedlade URL:en. Informationsproducenten kan tillämpa ett längre tidsfönster.

5. Bilaga: Mediatyper

Här följer ett exempel på den MediaTypeEnum, som refereras från elementet ”MediaType”. Listan över tillåtna värden definieras av varje tjänstedomän. Dessa skall vara i MIME-format och bör vara registrerade av IANA eller HL7.

NOTERA: Nedanstående lista är exempel på hur mediatypers ENUM utformas och ska inte ses som en komplett lista över tillåtna mediatyper

    <xs:simpleType name="MediaTypeEnum">
        <xs:restriction base="xs:string">
            <xs:enumeration value="application/dicom"/>
            <xs:enumeration value="application/msword"/>
            <xs:enumeration value="application/pdf"/>
            <xs:enumeration value="audio/basic"/>
            <xs:enumeration value="audio/k32adpcm"/>
            <xs:enumeration value="audio/mpeg"/>
            <xs:enumeration value="image/g3fax"/>
            <xs:enumeration value="image/gif"/>
            <xs:enumeration value="image/jpeg"/>
            <xs:enumeration value="image/png"/>
            <xs:enumeration value="image/tiff"/>
            <xs:enumeration value="model/vrml"/>
            <xs:enumeration value="multipart/x-hl7-cda-level1"/>
            <xs:enumeration value="text/html"/>
            <xs:enumeration value="text/plain"/>
            <xs:enumeration value="text/rtf"/>
            <xs:enumeration value="text/sgml"/>
            <xs:enumeration value="text/x-hl7-ft"/>
            <xs:enumeration value="text/xml"/>
            <xs:enumeration value="video/mpeg"/>
            <xs:enumeration value="video/x-avi"/>
        </xs:restriction>
    </xs:simpleType>