Livscykel och versioner i SDKs meddelandeformat

Innehållsförteckning

Revisionshistorik

Version

Datum

Kommentar

Version

Datum

Kommentar

1.0 (2022)

2022-02-28

Beslutad version för Tjänsten Säker digital kommunikation.

1. Inledning

Syfte: Detta dokument beskriver livscykelhantering av hur DIGGs ramverk och specifikationer respektive SDK-federationens specifikationer ska hanteras. Det är en del av regelverk för tjänsten Säker digital kommunikation och utgör regelverket för förändringar av SDKs dokumenttyper och specifikationer över tid.

Referenser

Stödjande externa dokument

Ref

Dokument-id

Dokumentlänk

Ref

Dokument-id

Dokumentlänk

R1

CEF eDelivery

https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eDeliver

R2

DIGG, Meddelandespecifikation: Meddelandekvittens

Beskrivning av innehållet i meddelandetypen ’meddelandekvittens’

DIGGs informationspaket kan erhållas genom info@digg.se

R3

Inera, RIV Tekniska Anvisningar

http://rivta.se/documents

R4

Inera, RIV Tekniska  Anvisningar, Översikt

https://inera.atlassian.net/wiki/spaces/RTA/pages/3632911/RIV+Tekniska+Anvisningar+versikt#RIVTekniskaAnvisningar%C3%96versikt-8.2Fram%C3%A5t/Bak%C3%A5tkompatibilitet

Se bl.a. avsnitt: 8.2 Framåt/Bakåtkompatibilitet

R5

Inera, RIV Tekniska Anvisningar Tjänsteschema

https://inera.atlassian.net/wiki/spaces/RTA/pages/3632903

Se bl.a. avsnitt: 3 Detaljerade regler

R6

Inera, RIV Tekniska Anvisningar Konfigurationsstyrning tjänstedomäner

https://inera.atlassian.net/wiki/spaces/RTA/pages/3632914/RIV+Tekniska+Anvisningar+Konfigurationsstyrning+tj+nstedom+ner#RIVTekniskaAnvisningarKonfigurationsstyrningtj%C3%A4nstedom%C3%A4ner-2Skapanyreleaseaventj%C3%A4nstedom%C3%A4n

R7

DIGG, Ramverk för
Plattform för eDelivery

DIGGs ramverk innehåller en förteckning av de beståndsdelar som ingår i
Ramverk för Plattform för eDelivery, samt dess versioner, som är styrande vid en
specifik tidpunkt.

DIGGs informationspaket kan erhållas via info@digg.se

 

SDK-dokument

Ref

Dokument-id

Dokumentlänk

Ref

Dokument-id

Dokumentlänk

B1

Specifikation: SDK Innehållsspecifikation - Meddelande

SDK Innehållsspecifikation Meddelande

Specificerar nyttolast för meddelanden inom Säker digital kommunikation, inklusive meddelandekuvert (metadata) och bilagor.

B2

Specifikation: SDK Adressbok Informationsspecifikation

Teknisk dokumentation och specifikationer
Adressbok Informationsspecifikation för innehållet i SDKAdressbok

B3

Specifikation: SDK Adressbok - Teknisk guide användning av Adressbokens API

Teknisk dokumentation och specifikationer
Adressbok, implementerar SDK Adressbok informationsspecifikation.

Teknisk guide för användning av SDK Adressboks API för sökning av adressuppgifter.

B4

SDKs publiceringsplats för fastställda dokumentation

https://inera.atlassian.net/wiki/spaces/OISDK/pages/2710601942

1. Bakgrund - Varför behövs livscykelhantering

Till SDK-federationen är det tänkt att all offentlig verksamhet inkl. privata utförare av offentligt uppdrag ska kunna ansluta. Informationsöverföring mellan parter sker genom s.k. direktöverföring mellan användarorganisationers accesspunkter.

En definierad och överenskommen livscykelhantering är viktig både för att specifikationer och dokumenttyper ska kunna utvecklas över tiden i takt och tillgodose utvecklingsbehov, och för att användarorganisationer ska kunna planera för interna förvaltningsaktiviteter och anpassning av de anslutande system som tillämpar specifikationerna.

För att uppnå ett stabilt och kontinuerligt meddelandeutbyte mellan användarorganisationer behövs därför gemensamma principer för hur specifikationerna förändras över tid och kan samexistera.

Över tid finns det behov av att stödja:

  • Befintliga specifikationer och meddelanden (dokumenttyper) kan förändras och utvecklas

  • Nya specifikationer och meddelanden (dokumenttyper) kan tillkomma

  • Specifikationer och meddelanden (dokumenttyper) kan behöva avvecklas

  • Förändringar i SDK-federationens gemensamma komponenter såsom SDK Adressbok och SDK Testklient

  • Förändringar i DIGGs tekniska ramverk

2. Teknisk versionering av SDKs specifikationer

Meddelanden som utbyts via SDK, som i sin tur är en tillämpning av CEF eDelivery (se ref. R1) och DIGGs transportinfrastruktur (se ref R7), följer ett specifikt tekniskt format. Det tekniska formatet kallas dokumenttyper (Document Type) inom eDelivery.

Dokumenttyper specificeras både av DIGG för eDelivery och i SDK-federationen:

  • DIGG Meddelandespecifikation - Meddelandekvittens (se ref. R2)

  • SDK Innehållsspecifikation - Meddelandespecifikation (se ref. B1)

Därutöver omfattar SDKs tekniska specifikationer även:

  • SDK Adressbok Informationsspecifikation (se ref. B2)

  • SDK Adressbok - Teknisk guide användning av Adressbokens API (se ref. B3)

SDKs specifikationer är baserade på Ineras arkitekturramverk RIV-TA (Regelverk för interoperabilitet i vården -Tekniska anvisningar) som bl.a. innehåller dokumentationsmallar och som definierar versionering av specifikationer (se Ref. R3). Inom RIV-TA används begreppen tjänstedomän och tjänstekontrakt vilket i detta sammanhang närmast motsvarar dokumenttyper inom eDelivery.

Inom RIV-TA används två begrepp för en förändring inom livscykelhanteringen:

  • icke bakåtkompatibel (major)

  • bakåtkompatibel (minor)

  • bakåtkompatibel (Subminor)

Observera att dessa begrepp adresserar teknisk och semantisk kompatibilitet.

2.1 Hur fungerar versioneringen i RIV-TA

Följande är en sammanfattning av hur RIV-TAs versionering fungerar.

Version

Beskrivning

Version

Beskrivning

Major (1.0)

  • Strukturändringar som tekniskt bedöms påverka kompatibilitet med tidigare versioner.

    • T.ex. ett fält blir obligatoriskt.

  • En majorversion kan innehålla omfattande förändringar av domänmodellen

En majorversion medför att användarorganisationens komponenter påverkas och behöver anpassas.

Minor (1.1)

  • Enklare ändringar som tekniskt inte bedöms påverka den tekniska bakåtkompabiliteten.

    • T.ex. Ett nytt frivilligt fält har tillkommit där verksamheten inte bedöms påverkas av förändringen.

Subminor (1.0.1)

  • Endast dokumentationsändringar som påverkar versionen av "minor".

För mer detaljer om versionshantering enligt RIV-TA, se Ref. R3-6.

3. Principer för utveckling och förvaltning av SDKs specifikationer

Följande principer gäller för utveckling och förvaltning av SDKs dokumenttyper och övriga specifikationer.

3.1 Princip 1: Utveckling och förvaltning av SDKs specifikationer

Följande utgångspunkter eller principer tillämpas för utveckling och förvaltning:

  • Utveckling är behovsdriven

    • Det skall framgå vilka behov som ligger till grund för funktionalitet

  • Utveckling sker öppet

    • Alla kan följa utvecklingen av nya versioner, s.k. release candidates (RC) publiceras öppet

    • Intressenter kan bidra med önskemål och förbättringsförslag

  • En ny version innehåller alltid

    • En beskrivning av ändringen utifrån ett verksamhetsperspektiv

    • En teknisk beskrivning av förändringen riktad mot teknisk förvaltning

      • Releasenotes som stöder utvecklare att grovt uppskatta mängden omarbetning som krävs för en uppgradering/anpassning till ny version

    • Schema, valideringsscript och exempelmeddelanden.

  • Etablerad förvaltning

    • Det finns en utpekad förvaltning av dokumenttyper och specifikationer.

3.2 Princip 2: Publicering, test och godkännande av SDKs specifikationer

  • Publicering, test och godkännande av SDKs dokumenttyper och övriga specifikationer sker enligt:

    • Gällande specifikationer finns publicerade på tjänsten SDKs publiceringsplats (Se ref B4).

    • Releasekandidater (RC) publiceras löpande på SDKs publiceringsplats (Se ref B4).

    • En releasekandidat godkänns alltid i SDKs externa testmiljö, SDK Testbädd, av SDK federationsoperatör och minst två användarorganisationer.

  • När SDK-federationsoperatör och minst två användarorganisationer anmäler att version skall tas i produktion kommer RC markeras som “fastslagen”. Detta innebär att en produktionsverifiering planeras att genomföras inom kort.

    • Efter att produktionsverifiering är genomförd kan alla användarorganisationer registrera stöd för versionen, dvs. versionen är tillgänglig för breddinförande. En användarorganisation deklarerar och registrerar stöd för ny version via SDKs anslutningsblankett. detta förfarande beskrivs i SDKs anslutningsdokumentation.

3.3 Princip 3: Samexistens/livscykelhantering av flera versioner

Följande regler gäller för att hantera flera samtidiga versioner av SDKs dokumenttyper och övriga specifikationer:

Dokumenttyper:

  • Hantering av major-versioner:

    • I huvudsak kommer endast major-versioner att släppas.

    • I undantagsfall kan minor-versioner användas efter beslut av ansvarig förvaltning för dokumenttypen.

    • Vid release av ny version av en dokumenttyp kommer två major-versioner att vara aktiva samtidigt i produktionsmiljö.

    • Om det uppstår ett akut behov av en ny major-version kan denna produktionssättas och därmed antal samtidiga major-versioner utökas.

    • Upp till tre major-versioner av en dokumenttyp kan vara aktiva i SDK Testbädd (QA) för test och verifiering (omfattar ej akut major-version). SDK-federationen tillhandahåller en SDK Testbädd (QA) som del i anslutningsprocessen till SDK. SDK Testbädd (QA) är produktionslik (dock: endast testdata får förekomma) och som också tillåter tester av nyare versioner.

  • En dokumenttypsversion som är markerad som “expired“ får ej användas längre.

Övriga specifikationer:

  • Hantering av major-versioner:

    • Major-versioner släpps vid behov

    • Vid release av ny specifikation kan två major-versioner vara aktiva samtidigt i produktionsmiljö.

    • Vid flera aktiva major-versioner är dessa aktiva i SDK Öppen testmiljö för tjänsteleverantörer, SDK Testbädd (QA) för test och verifiering (omfattar ej akut major-version).

    • Minor-versioner släpps löpande vid behov

  • En specifikation som är markerad som “expired“ får ej användas längre.

3.4 Princip 4: Stegning av version för användarorganisation

3.4.1 Användarorganisationer

  • Användarorganisationer förbinder sig att (SKA) följa fastställd livscykelhantering för dokumenttyper och specifikationers livscykel.

  • Användarorganisationer förbinder sig att (SKA) stödja ny major-version av dokumenttyp och specifikation senast 12 månader efter att release är fastslagen, dvs. satt i produktion.

  • Användarorganisationer BÖR stödja två versioner av dokumenttyper och specifikationer i produktionsmiljö.

    • SKA stödja: den version som är obligatorisk* version, dvs. tidigare (lägre) version (t.ex. 1.0)

    • BÖR stödja: senaste aktuell version (t.ex. 2.0)
      *Obligatorisk version är den version som alla användarorganisationer måste stödja vid anslutning till SDK-federationen.

  • Användarorganisation anmäler stöd för ny version till SDK-federationsoperatör via anslutningsblankett

3.4.2 Hantering av livscykel i användarorganisationers anslutande system

  • De användarorganisationer som är anslutna till SDK-federationen förbinder sig att (SKA) följa fastställd livscykelhantering för dokumenttyper och specifikationers livscykel.

  • SDK-federationsoperatör godkänner nya anslutningar till SDK Testbädd för dokumenttyper och specifikationer med obligatorisk version, senaste aktuell version eller ev. nyare version under öppen utveckling (release candidate)

  • SDK-federationsoperatör godkänner nya anslutningar till SDK PROD för dokumenttyper och specifikationer med obligatorisk version och senaste aktuell version

3.4.3 SDK.federationens gemensamma komponenter

  • Utöver fastställd livscykelhantering uppdateras gemensamma komponenter enligt följande:

    • Minor-versioner: Löpande förbättringar och uppdateringar släpps löpande

    • Releasenotes publiceras på tjänstens öppna informationsyta i verktyget Confluence

4. Tillämpning av principerna på SDKs specifikationer

Detta avsnitt beskriver hur principerna tillämpas på SDKs specifikationer samt DIGGs ramverk för eDelivery i livscykelhanteringen för Säker digital kommunikation samt påverkan på användarorganisation respektive AP-operatör.

Följande principer gäller för respektive specifikation.

Specifikation

Principer för livscykelhantering

Påverkar

Specifikation

Principer för livscykelhantering

Påverkar

SDK Innehållsspecifikation (se ref. B1)

SDK Adressbok Informationsspecifikation (se ref. B2)

SDK Adressbok - Teknisk guide användning av Adressbokens API (se ref. B3)

Princip 1: Utveckling och förvaltning av SDKs specifikationer
Princip 2: Publicering, test och godkännande av SDKs specifikationer
Princip 3: Samexistens/livscykelhantering av flera versioner
Princip 4: Stegning av version för användarorganisation

Användarorganisation

  • Meddelandetjänst

  • Meddelandeklient

DIGG Meddelandespecifikation - Meddelandekvittens (se ref. R2)

 

Princip 3: Samexistens/livscykelhantering av flera versioner
Princip 4: Stegning av version för användarorganisation

Användarorganisation

  • Meddelandetjänst

  • Meddelandeklient

DIGGs Ramverk för Plattform för eDelivery (se ref. R7)

Se DIGGs regelverk för livscykelhantering

Not: Fastställt regelverk saknas. Ändringar hanteras per ändring och kommuniceras av Ansvarig för Plattform för eDelivery.

Användarorganisation

  • Meddelandetjänst

AP-operatör

  • Accesspunkt