Utgåvehistorik för dokumentet

Ordlista

Referenser

1                Inledning

Detta är en handledning gällande hur tjänstedomäner ska lagras, versionshanteras och releasas på RIVTA (http://rivta.se). Dokumentet innehåller också instruktioner för framtagning av de utvecklingshjälpmedel (”byggfiler”) för Microsoft .Net och Java-plattformen som ska medfölja en release av en tjänstedomän. RIVTA ägs och förvaltas av Inera Arkitektur och Regelverk.

1.1                 Målgrupp

Dokumentet riktar sig i första hand till de som praktiskt utvecklar och förvaltar tjänstekontrakt baserade på RIV Tekniska anvisningar men även till tjänstekonsumenter och tjänsteproducenter som använder tjänstekontrakt i sina system. För att använda handledningen krävs förkunskaper i användandet av versionshanteringssystem (specifikt Git), design av WSDL och XML-schema, grundläggande kunskaper i hur s.k. WSDL-first-utveckling av tjänster bedrivs i .Net och Java EE samt i kommandobaserad exekvering av byggskript för respektive miljö.

1.2                 Syfte

Det övergripande syftet med denna handledning är att underlätta arbetet för de som utvecklar och vidareutvecklar tjänstekontrakt för att säkerställa en effektiv och korrekt hantering av versioner och releaser av tjänstekontrakt och tjänstedomäner.

1.3                 Avgränsning

Kravhantering och ändringshantering ingår inte i denna handledning, inte heller aktiviteter relaterade till att samordna och informera tjänstedomänens intressenter.  Detta förutsätts ske inom aktuellt projekt eller förvaltning.

Dokumentet hanterar de releaser och release candidates som är föremål för den kvalitetssäkring och publicering som Inera Arkitektur och Regelverk ansvarar för.

1.4                 Förutsättningar

Vid utveckling av en ny tjänstedomän ska denna vara namnsatt av Inera Arkitektur och Regelverk. Vid tillägg av ett nytt tjänstekontrakt inom befintlig domän ska Inera Arkitektur och Regelverk ha kontrollerat att tjänstekontraktet finns inom rätt domän. 

1.5                 Krav på utvecklingsmiljö

Dokumentet beskriver bland annat aktiviteter i versionshanteringssystem. De som ska arbeta praktiskt med tjänstekontraktsutveckling enligt denna handledning behöver ha följande verktyg installerade på sina lokala datorer:

1.6                 Regelverk och mallar

Länkar till regelverk, mallar och exempel som ligger till grund för denna handledning finns på:

http://rivta.se/documents.

2               Skapa ny release av en tjänstedomän

Förtydligande:

Utvecklingen av nya tjänstekontrakt eller nya versioner av befintliga tjänstekontrakt ska ske i samarbete mellan MINST en producent och en konsument och SKA acceptanstestas i en teknisk leverans av konsument och producent kod mellan dessa innan granskning.

Om den/de nya versionerna är minor versioner så SKA de även testas för bakåtkompabilitet. Om det inte finns tillgång till testmiljöer för verkliga konsumenter och producenter för dessa tester så kan testsviter användas istället (se också kapitel 2.7)

Gången är i korthet följande:

• Vid utveckling av tjänstekontrakt arbetar projektet iterativt i Git med olika versioner.
• När projektet har en version, release candidate (RC), som är klar för granskning görs en begäran till Inera Arkitektur och regelverk om kvalitetssäkring
• Projektet fortsätter sitt arbete och kan vid behov leverera ytterligare RC för granskning .
• Då projektet har testat en version (normalt är detta en release candidate) som man beslutat tillämpa i produktion gör projektet en begäran till Inera Arkitektur och Regelverk om att skapa en fastställd release

Detta kapitel innehåller de aktiviteter som ingår vid hantering av nya releaser av tjänstedomäner tillsammans med hänvisningar till mallar, exempel och anvisningar.

2.1                 Förberedelser

Utvecklare och förvaltare av tjänstekontrakt behöver tillgång till nödvändiga resurser för att kunna hantera versioner av, dokumentera och utveckla tjänstekontrakt. För versionshantering behövs ett konto på Bitbucket samt behörighet till aktuell tjänstedomän.

Beslut om domännamn

Om det är aktuellt att skapa en ny tjänstedomän, ta först kontakt med till bestall@inera.se.och beskriv vilken typ av information som ska hanteras samt inom vilken verksamhetsprocess. Inera Arkitektur och Regelverk kommer då att besluta ifall en ny tjänstedomän skall skapas, samt tilldela svenska och engelska domännamn.

Därefter skapas ett repository på Bitbucket som ska rymma tjänstedomänens källkod, dokumentation och ärendehantering.

Ansök om behörighet i Bitbucket

Ansökan om behörighet sker genom att kontakta Inera Arkitektur och Regelverk till bestall@inera.se. Meddela din e-postadress samt vilken tjänstedomän du ska arbeta med. Om du inte har ett Bitbucket-konto associerat med din e-postadress sedan tidigare kommer du att få ett automatiskt välkomstmail från Bitbucket med instruktioner om hur du skapar ett konto och får tillgång till din behörighet.

Installera programvaror på lokal dator

Installera programvaror på din lokala dator enligt kapitel 1.5.

Klona Git-repository

Om det finns filer tillhörande domänen incheckade sedan tidigare behöver du göra en s.k. ”klon” (lokal kopia) av tjänstedomänens Git-repository. Beskrivning om hur det görs finns på http://rivta.se/bitbucket/.

2.2                Skapa katalogstruktur

Om du arbetar med en helt ny tjänstedomän behöver du själv skapa dess katalogstruktur. En tjänstedomän ska strikt följa en gemensam och fastställd katalog- och filstruktur.  Hur denna ser ut och hur man skapar strukturen för en ny tjänstedomän beskrivs i appendix 2.

2.3                Uppdatera eller skapa tjänstekontraktsbeskrivning

Uppdatera eller skapa (vid ny tjänstedomän) tjänstekontraktsbeskrivning och dokumentera arkitekturella beslut (AB). Om inga arkitekturella beslut har fattats ska det stå ”inga avsteg gjorda” i AB-dokumentet.

Länkar till mallar och exempel på tjänstekontraktsbeskrivning och arkitekturella beslut finns här: http://rivta.se/documents

Under arbetet med framtagning av tjänstekontraktsbeskrivning kan Inera Arkitektur och Regelverk vara behjälplig med synpunkter och vägledning.

2.4                Utveckla tekniska kontrakt och checka in i RIVTA

Utveckla tekniska kontrakt och checka in artefakter i tjänstedomänens Git-repository på Bitbucket. Vi rekommenderar starkt att en testsvit tas fram för tjänstekontrakten, se http://rivta.se/ ”Utveckling av testsvit för tjänstekontrakt”.

2.5    RIVTA Verifiering

En ny release ska verifieras mot regelverket i RIVTA. Detta görs med hjälp av python-scriptet ”verifyRivtaDomain.py” (se kapitel 1.5).

Scriptet kontrollerar

• Att katalogstrukturen som beskrivs i RIV TA Konfigurationsstyrning följs
• Att XML-filer följer XML-scheman (XML Schema 1.0 och WSDL 1.0)
• Att WSDL-filer följer reglerna i RIV TA Basic Profile
• Att Domän- och tjänstescheman följer RIV TA-ansvisningarna

Om resultatet påvisar fel och/eller varningar i releasen, ska dessa korrigeras och hanteras före begäran om kvalitetssäkring.

Observera att en release ska innehålla alla tjänstekontrakt, dokument, script, o d som ingår i domänen. Detta gäller oavsett om de ändrats i den nya releasen eller ej.

2.6                Skapa Tag i Git för release candidate (RC) och begär kvalitetssäkring

För att få en formell kvalitetssäkring av en tjänstedomän skapas en release candidate. Det görs genom att skapa en Tag i Git. Hur man namnsätter en tag beskrivs i appendix 2. Hur man skapar och publicerar en tag beskrivs på http://rivta.se/bitbucket.

Skicka sedan en begäran om kvalitetssäkring till  till bestall@inera.se med angivande av namn på tjänstedomän och vilken RC som begäran avser.

Inera Arkitektur och Regelverk ansvarar för att paketera och skapa de Zip-filer som kvalitetssäkrats av Inera samt att publicera dessa på http://rivta.se/domains.

För att få implementera en RC i den nationella tjänsteplattformens QA-miljö (acceptanstestmiljö) krävs att den har kvalitetssäkrats av Inera Arkitektur och Regelverk och att Tjänstedomänansvarig/Tjänsteansvarig har godkänt installation.

Tjänstedomänansvarig/Tjänsteansvarig beställer installation av tjänstekontrkat av till bestall@inera.se

2.7                 Skapa Tag i Git och begär paketering och publicering av release av tjänstedomän

En release kan skapas när acceptanstesterna är genomförda i en QA-miljö (regional eller gemensam tjänsteplattform) och domänens tjänstekontrakt står inför en driftsättning i produktionsmiljö.

Skapa en Tag i Git och begäran om paketering och publicering som skickas till till bestall@inera.se med angivande av namn på tjänstedomän och aktuell release.  Denna tag ska referera till samma Git commit som den senast godkända release candidate. Regler för namnsättning finns i appendix 2.

Inera Arkitektur och Regelverk skapar Zip-fil på RIVTA och publicerar den nya releasen på http://rivta.se/domains.

3                   Ändringsfrysning av release

När någon av de parter som medverkar i framtagandet av en ny release behöver ensamrätt till att införa ändringar, kan de begära en ändringsfrysning. Det sker genom att parten meddelat att de är beredda att gå i produktion på aktuell kandidat och att man planerar för att göra det inom kort. I praktiken innebär det ofta att man i sin egen produktcykel går in i en fas där man inte längre kan hantera ändringar utifrån, för att kunna gå i mål med sin tidplan. Om övriga accepterar frysningsbegäran, är kandidat-versionen ändringsfryst. Det innebär att det bara är parten som fått frysningen (= låst aktuell version) som kan be om en ny RC.

4               Ta bort release av tjänstedomän

När en release eller ”release candidate” är inaktuell ansvarar Tjänstedomänansvarig/Tjänsteansvarig för att begära borttagning av den. Begäran skickas till kundservice@inera.se med information om namn på tjänstedomän och aktuell RC/release som ska tas bort.

Inera Arkitektur och Regelverk tar bort Zip-fil från RIVTA samt i tabeller över godkända tjänstedomäner.

Appendix 1 – Skapa Git-repository

Om ett nytt Git-repository ska skapas för aktuell tjänstedomän på Bitbucket, behöver du själv initiera denna och skapa nödvändig katalogstruktur. Alla tjänstedomäner ska följa en gemensam och fastställd katalog- och filstruktur. Denna struktur och namnstandard är inkorporerad i script och måste därför strikt följas.

• Tjänstekontraktsbeskrivningen, arkitekturella beslut och informationsspecifikation ska ligga i docs katalogen. Namnen på dessa dokument skall baseras på tjänstedomänens engelska namn, med dess delar avskilda med underscore och följa mönstret:[1]
  • TKB_ <tjänstedomännamn>.docx, ex TKB_clinicalprocess_activityprescription_actoutcome.docx
  • AB_ <tjänstedomännamn>.docx, ex AB_clinicalprocess_activityprescription_actoutcome.docx
  • IS_<tjänstedomännamn>.docx, ex IS_clinicalprocess_activityprescription_actoutcome.docx
• WSDL: er och scheman ordnas i katalogen ”schemas”
• I ”schemas” ska två underkataloger finnas: ”core_components” och ”interactions”.
  • I ”core_components” ska scheman ligga som är generella för domänen (t.ex. domän-scheman och header-scheman).
  • Under  ”interactions” skall det finnas en underkatalog per interaktion. I dessa ska schema och WSDL ligga som är specifika för respektive tjänsteinteraktionen.
• I ”code_gen”-katalog ska det finnas bygg-script för att generera kod från WSDL-filerna, som stöd för utveckling av tjänstekonsumenter och tjänsteproducenter. Underkataloger till code_gen ska skapas för Javaplattformens standard (JAX-WS) och .Net.

Strukturen för tjänstedomäner, enligt regelverket, ser ut på följande sätt:

• code_gen
• code_gen/jaxws
  • byggscript för att generera kod från WSDL-filer
• code_gen/wcf
  • byggscript för att generera kod från WSDL-filer
• docs
  • tjänstekontraktsbeskrivning
  • arkitekturella beslut
• schemas
• schemas/core_components
  • scheman som är generella för domänen
• schemas/interactions
• schemas/interactions/TjänsteNamnInteraction
  • schema och WSDL specifikt för tjänsten ”TjänsteNamn”
• test-suite
  • testsvit, ej obligatorisk

Initiera Git-repository

Innan kataloger och filer kan lagras för en tjänstedomän på Bitbucket, behöver dess Git-repository initieras. Detta görs på en lokal dator. Här beskrivs hur det görs med en kommandobaserad Git-klient, men motsvarande kan även göras med grafiska verktyg.

Gör så här:

1. Skapa en lokal katalog med samma namn som det repository som skapats på Bitbucket, t.ex. ”riv.clinicalprocess.healthcond.actoutcome”.
2. Ställ dig i katalogen och skriv kommandot ”git init”.
3. Registrera sökvägen till Bitbucket. Exakta uppgifter hittar du på repository-sidan i Bitbucket, men kommandot följer detta mönster: ”git remote add origin https://username@bitbucket.org/rivta-domains/riv.xxx.yyy.zzz.git”

Skapa katalogstruktur

Skapa följande katalogstruktur i ditt Git-repository:

code_gen

code_gen/jaxws

code_gen/wcf

docs

schemas

schemas/core_components

schemas/interactions

Checka in och publicera till Bitbucket

Det är inte möjligt att checka in tomma kataloger i ett Git repository. Därför kan du checka in och publicera dina kataloger i först när du fyller dem med innehåll.

För mer information om hur du arbetar med Git, se http://rivta.se/bitbucket.

Appendix 2 – Namnsättning och versionshantering

Version av tjänstedomän

En tjänstedomäns version utrycks med siffror i en två eller treställig kombination

Ex 2.1 eller 2.1.1

En tjänstedomän kan alltså innehålla tjänstekontrakt med olika versionsnummer.  Grundregeln för versionsnumrering är att tjänstedomänens major & minor-version ska motsvara den högsta versionen på något av de ingående tjänstekontrakten. Till detta kommer en tredje siffra som räknas upp vid all annan förändring.

Ingen slutsats om omfattningen av en uppdatering ska dras av att uppräkning endast sker av tredje siffran. Omfattningen av förändringar i en version ska framgå av tjänstekontraktsbeskrivningen och eventuella releasenotes som bifogas paketeringen.

Nya tjänstekontrakt som tillkommer ska alltid börja med version 1.0 oavsett domänens version. (och då räknas alltså tredjesiffran upp om det inte även sker andra förändringar som påverkar major.minor)

En tjänstedomän kan alltså innehålla tjänstekontrakt med olika versioner och även tjänstekontrakt med fler olika majorversioner. En viss version av tjänstedomän innehåller dock bara den en version inom en major

dvs 1.1 ersätter 1.0

NOTERA: Även fast tjänstedomäner kan ha samexisterande tjänstekontrakt men olika huvudversioner (Major) så kan dessa av tekniska skäl inte paketeras tillsammans givet hur installationsskripten fungerar (baserat på hur man gjort historiskt) så därför måste tidigare huvudversioner tas bort ur taggningen för en viss version. Domäner som har tjänstekontrakt i flera olika huvudversioner kan därför behöva ha flera samtidiga paketeringar som är publicerade

Exempel 1

• Tjänstekontrakt A 1.0
• Tjänstekontrakt B 1.1
• Tjänstedomän 1.1

Exempel 2

• Tjänstekontrakt A 1.0
• Tjänstekontrakt B 2.0
• Tjänstedomän 2.0

Uppdatering av major och/eller minor

Vissa förändringar av ingående tjänstekontrakt innebär att tjänstedomänens major och/eller minor ska uppdateras.

Exempel 1 - Bakåtkompatibel ändring av kontrakt, ny minor nu högst

• Före ändring
  • Tjänstekontrakt A 1.0
  • Tjänstekontrakt B 1.1
  • Tjänstedomän 1.1
  • Efter ändring
    • Tjänstekontrakt A 1.0
    • Tjänstekontrakt B 1.2
    • Tjänstedomän 1.2

Exempel 2 - Icke bakåtkompatibel ändring av kontrakt, ny major och minor nu högst

• Före ändring
  
  • Tjänstekontrakt A 2.0
  • Tjänstekontrakt B 2.3
  • Tjänstedomän 2.3
  • Efter ändring
    • Tjänstekontrakt A 3.0
    • Tjänstekontrakt B 2.3
    • Tjänstedomän 3.0

Lägga till/uppdatera tredje siffra

Andra förändringar innebär inte att domänens major och/eller minor ska uppdateras. I dessa fall används en tredje siffra i domänens versionsnummer. Den tredje siffran läggs till, alternativt räknas upp. Den första tredje siffran som används är alltid 1.

Exempel 1 - Dokumentationsuppdatering, ingen förändring av kontrakt, tredje siffra läggs till

• Före uppdatering
  • Tjänstekontrakt A 1.0
  • Tjänstekontrakt B 1.1
  • Tjänstedomän 1.1
  • Efter uppdatering
    • Tjänstekontrakt A 1.0
    • Tjänstekontrakt B 1.1
    • Tjänstedomän 1.1.1

Exempel 2 - Bakåtkompatibel ändring av kontrakt, nuvarande major och minor fortfarande högst, tredje siffra läggs till

• Före ändring
  • Tjänstekontrakt A 1.1
  • Tjänstekontrakt B 2.0
  • Tjänstedomän 2.0
  • Efter ändring
    • Tjänstekontrakt A 1.2
    • Tjänstekontrakt B 2.0
    • Tjänstedomän 2.0.1

Exempel 3 - Ett helt nytt tjänstekontrakt tillkommer i en befintlig domän, nuvarande major och minor fortfarande högst, tredje siffra läggs till

• Före ändring
  • Tjänstekontrakt A 1.1
  • Tjänstekontrakt B 2.0
  • Tjänstedomän 2.0
  • Efter ändring
    • Tjänstekontrakt A 1.2
    • Tjänstekontrakt B 2.0
    • Tjänstekontrakt C 1.0
    • Tjänstedomän 2.0.1

Exempel 4 - Icke bakåtkompatibel ändring av kontrakt, nuvarande major och minor fortfarande högst, tredje siffran används redan så denna räknas då upp.

• Före ändring
  • Tjänstekontrakt A 1.4
  • Tjänstekontrakt B 2.2
  • Tjänstedomän 2.2.1
  • Efter ändring
    • Tjänstekontrakt A 2.0
    • Tjänstekontrakt B 2.2
    • Tjänstedomän 2.2.2

Versionshantering av interaktionsspecifika scheman

Ändringa och tillägg för typer som deklareras direkt i tjänsteinteraktionsschemat versionshanteras alltid via en utökningsfil om ändringen ska anses vara bakåtkompatibel se regel #9 i RIV Tekniska Anvisningar Tjänsteschema http://rivta.se/documents/ARK_0005/

Versionshantering av domängemensamma scheman

Typer som används i flera interaktioner kan deklareras i en eller flera domängemensamma schemafiler som placeras i katalogen /schemas/core_components/

Vid behov av förändringar och tillägg av gemensamma typer behöver följande beaktas:

Om förändringen rör utökning av en befintlig typ och som rör nya valfria element och där ändringen ska vara bakåtkompatibel så görs denna via ett utökningsschema. se Regel #6 i RIV Tekniska Anvisningar Domänschema http://rivta.se/documents/ARK_0006/

Om förändringen görs i en befintlig gemensam schemafil så får denna en ny version som påverkar filnamnet. Det innebär att alla referenser till denna behöver uppdateras vilket i praktiken innebär att alla interaktioner (som refererar detta schema) kommer behöva ändras för att länka in schemat. Och då får dessa en ny version oavsett om interaktionen använder de nya objekten eller ej. Dvs interaktionerna skulle få en ny (sub)version utan att det praktiskt tillförs någon funktionalitet. 

För att undvika detta kan förändringar istället placeras i en ny fil. Eftersom det rör sig om gemensamma deklarationer vars användning sedan definieras i de scheman som importerar det gemensamma schemat så är det inte nödvändigt att använda strukturen för utökningsscheman. I stället så namnsätts filen och namnrymden unikt.

Därefter så importeras det nya gemensamma schemat i de interaktionsscheman som behöver använda de nya deklarationerna.

Exempel 1 - Två nya tjänsteinteraktion har behov av en eller flera nya typer för att hantera personal som bedöms vara lämplig att deklarera globalt, i nuläget finns inget behov av att använda de nya typerna i befintliga interaktionerna. Därför tillförs dessa i filen DomainSchemaProfession1.0 och detta schema importeras i Tjänstekontrakt C & D

• Före uppdatering
  • Tjänstekontrakt A 1.0
  • Tjänstekontrakt B 1.1
  • Core_components
    • DomainSchema1.0
  • Tjänstedomän 1.1
  • Efter uppdatering
    • Tjänstekontrakt A 1.0
    • Tjänstekontrakt B 1.1
    • Tjänstekontrakt C 1.0
    • Tjänstekontrakt D 1.0
    • Core_components
      
      • DomainSchemaProfession1.0
      • DomainSchema1.0
    • Tjänstedomän 1.1.1

Om det senare behövs ytterligare förändringar kring dessa nya typer kan DomainSchemaProfession sättas till 1.1 eller 2.0 (beroende på förändringens karaktär) och importeras i tjänstekontrakten C & D som i sin tur versioneras utifrån om förändringen är bakåtkompatibel eller ej.

På detta sätt minimeras påverkan på tjänsteinteraktionerna av en förändring i ett gemensamt schema.

Exempel 2 - En ändring behöver göras av en befintlig typ som är deklarerad i en domängemensam schemafil och som används i två tjänsteinteraktioner 

Före uppdatering

• Tjänstekontrakt A 1.0
• Tjänstekontrakt B 1.1
• Core_components
  
  • DomainSchema1.0
• Tjänstedomän 1.1
• Efter uppdatering
  • Tjänstekontrakt A 1.1
  • Tjänstekontrakt B 1.2
  •  Core_components
    • DomainSchema1.1
    • DomainSchema1.1_ext

Båda tjänsteinteraktionernas version räknas upp eftersom de har förändrats

Release candidates (Domän)

Under arbetet med att fastställa en ny version av en domän så kan justeringar behöva göras och detta markeras då med vad som kallas "release candidate" (RC) . Versionsnumret för release candidates börjar med versionsnumret för den tilltänkta releasen följt av ett underscore, RC och löpnummer. Exempel: 1.1_RC2

För att underlätta spårbarheten används samma versionsnummer i dokumentens revisionshistorik som för tjänstedomänen (exempelvis RCn i stället för PAn).

Förtydligande: det är bara domänens paktering och numrering i dokumentation som markeras som RC och alltså inte de ingående tjänstkontrakten eller andra tekniska komponenter

Namnsättning av tag

Taggen namnges efter tjänstedomänens aktuella version.

• Exempel för Release Candidate: 2.1_RC3
• Exempel för Release: 2.1

I tidigare versioner av denna anvisning ingick även tjänstedomänens namn i tag-namnet. Detta underlättade i den tidigare projektplatsen Google Code, men är överflödigt och snarare försvårar i Bitbucket, då långa tag-namn i vissa fall trunkeras i webbgränssnittet. Alla nya domäner ska använda den nya formen av namnsättning.

Namnsättning av Zip-fil

I normalfallet skapas och publiceras ZIP-filen av Inera Arkitektur och regelverk i samband med en godkänd T-granskning. Den ges alltid samma version som den tag den baseras på. Dessutom adderas prefixet ”ServiceContracts” till namnet:

Release:

ServiceContracts_<tjänstedomän>_<domänversion>.zip

Ex. ServiceContracts_clinicalprocess_activityprescription_actoutcome_2.1.zip

Release candidate:

ServiceContracts_<tjänstedomän>_<domänversion>_RC<RC-nummer>.zip

Ex. ServiceContracts_clinicalprocess_activityprescription_actoutcome_2.1_RC3.zip

[1] Ett tidigare krav på att filnamnet för TKB och AB även skulle innehålla versionsbeteckning har tagits bort.