Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

 

Konfigurationsstyrning tjänstedomäner


Version 2.2.57

ARK_0007


20192020-12-0408



Table of Contents


Utgåvehistorik för dokumentet

Rev. Nr

Rev. Datum

Beskrivning av ändringar

Ändringarna gjorda av

1.0

2012-01-03

RIVTA Konfigurationsstyrning 1.0


2.0

2013-10-29

Handledning konfigurationsstyrning 2.0


2.0.1

2014-01-30

Uppdatera exempel för namnsättning av TAG-namn


2.0.2

2014-02-11

Flyttade test-suite till rätt plats i mappstrukturen.

Förtydligade namnsättningsreglerna för TKB och AB.

Ändrade ”ServiceContracts” till ”ServiceInteractions” i sökväg till domänerna.


2.0.3

2014-02-20

Förtydligande av krav och hantering av release av Tjänstedomän.


2.0.4

2014-06-04

Fixade typo i exempel av namnsättning av tjänstedomän (ändrade ”Clinicalprocess….” till ”clinicalprocess….”.

Byte till Inera-mall.


2.0.5

2014-06-30

Ersatte alla referenser till ”CeHis” med ”Inera”.


Tog bort alla referenser till självdeklaration av följsamhet.


Fixade enstaka typos.


Ändrade namnsättningsregeln för TKB och AB. Dessa skall inte längre ha versionsbeteckning i filnamnet.


Förtydliga mappstrukturen och kravet på en undermapp per intraktion (WSDL-fil).


Förtydliga versionreglerna. Tredje versionstalet uppstår endast efter den första dokumentationsuppdateringen och kan därför aldrig vara 0.


Förtydliga att Inera Arkitektur och regelverk skapar zip-filerna vid release.


Förtydliga att en tag alltid skapas mha kommandot ”svn copy”.

Adderade Bilaga 5 som beskriver hur en tjänstedomän byter namn (namnrymnd).


2.0.6

2014-08-07

Förtydligade att en release skall ske baserat på en godkänd RC, inte från trunk.


2.0.7

2014-10-07

Endast redaktionella ändringar samt ny label på WEB.


2.0.8

2015-05-20

Beskrivning av den nya hanteringen som innebär att inga RC produktionssätts.


2.1

2015-06-17

Anpassat instruktionen till Bitbucket och Git.

Tagit bort Bilaga 1 ”Checka ut källkodsrepository” då den inte längre gäller.

Tagit bort Bilaga 4 ”Skapa Release-tag” pga att det skiljer sig mellan olika verktyg. Hänvisar istället till http://rivta.se/bitbucket

Tagit bort Bilaga 5 ”Namnbyte av tjänstedomän”, då den beskrev ett Subversion-specifikt förfarande.


2.1.1

2015-12-17

Rättat uppgifter om var anvisning om testsvit hittas och var dessa skall placeras i katalogstrukturen.

Lagt till information om korrekt namn på dokumentet Informationsspecifikation.

Förändrat namngivning av tags.


2.2

2016-10-18

Ändrat språkliga fel och gjort en del förtydliganden

Rensat ordlista på begrepp som inte är specifika för detta dokument

Ändrat till att genomgående använda begreppen tjänstekonsument och tjänsteproducent

Lagt till att verktyget Python behövs

Lagt till rollen Tjänsteansvarig

Bytt ”Bilaga” till ”Appendix”.

Förtydligat att alla nya tjänstedomäner ska använda den nya formen för namngivning av en tag

Kompletterat och förtydligat versionsnumrering i Appendix 2.

Definitioner av begreppen fastställd release och ändringsfryst

Ändrade uttrycket formell release till fastställd i texten

Beskrivning av ”frysningskonceptet”

Lagt till steget RIVTA Verifiering

Förtydligat att allt innehåll ska ingå i varje release av en domän


2.2.1

2016-11-09

Ändrat uppgifter om var man ska kontakta till (kundservice@inera.se).


2.2.22018-10-01

Lagt till förtydligande gällande versionering av tjänstekontrakt som tillkommer i befintlig tjänstedomän

Uppdaterat exempel kring domänversionering med major.minor och tredje siffra

Lagt till kolumn i utgåvehisstorik (ändringarna utförda av)

Lagt till avsnitt kring versionshantering av gemensamma scheman

Lagt till förtydligande kring hur siffrorna i versionsnumrering ska användas

Björn Hedman
2.2.32019-03-06Bytt ”Bilaga” till ”Appendix”.Ranjdar Fallyih
2.2.42019-03-13

Ändrat exempel för paketering i Appendix A så att dessa återspeglar hur installationsskripten hanterar paketering.

Förtydligat att en viss paketering inte kan innehålla flera huvudversioner av samma tjänstekontrakt även om det finns flera som är giltiga för domänen

Björn Hedman
2.2.52019-12-04

Förtydligat att utvecklingen av nya tjänstekontrakt eller nya versioner av kontrakt måste göras med en konsument och en producent

samt att versionen ska ha testats i en teknisk leverans för konsument och producent innan fastställande sker (Kapitel 2)

Rättat exempel kring hantering av schemafiler i core_components (och ändrat från common objects till just core_components)

Björn Hedman

Ordlista

Konfigurationsstyrning används för att identifiera

Ord som används i dokumentet

Beskrivning

Konfigurationsstyrning/ konfigurationshantering

2.2.62019-12-11Ändrat skrivningar kring ändring av domängemensamma scheman, tagit bort skrivning om hur version i filnamn påverkas eftersom detta ska beskrivas på annan platsBjörn Hedman
2.2.72020-01-30Ändrat och kompletterat kapitel 2 för att förtydliga mot nuvarande process för ny- och vidareutveckling av tjänstekontrakt.

Ranjdar Fallyih

Claudia Ehrentraut

Ordlista

Ord som används i dokumentet

Beskrivning

Konfigurationsstyrning/ konfigurationshantering

Konfigurationsstyrning används för att identifiera versioner, komponenters utvecklingsstatus och ändringar.

För att underlätta hanteringen, genom att enkelt kunna identifiera och spåra olika versioner används automatiserade verktyg för versionshantering.

Version

Tjänstekontrakt kan ha olika utgåvor. Varje utgåva benämns version och ska ha en versionsbeteckning.

Release

När en ny version av den slutgiltiga tjänstedomänen paketerats och är fastställd benämns den Release.

Release Candidate (RC)

När en version av en tjänstedomän har paketerats och är klar att testas/verifieras benämns den Release Candidate

Fastställd release

Den release man beslutat gå i produktion med. Efter genomförda regressionstester i QA/SIT är releasen färdig för installation i PROD 

Ändringsfryst

Någon av de parter som medverkar i framtagandet av en ny release har fått ensamrätt till att införa ändringar och be om nya RC. Se mer utförlig beskrivning i sektion 2.7

Git

Automatiserat verktyg för versionshantering. https:/Git

Automatiserat verktyg för versionshantering. https://git-scm.com/

RIVTA Källkodsrepository

Ett centralt register (repository) för att samla och spara tjänstedomänens artefakter och göra dem sökbara genom att märka upp (tagga) dem.

...

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.

...

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.75)

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 releaseom paketering och publicering genom att kontakta med Arkitektur och Regelverk enligt anvisning under http://rivta.se/begaran/ .

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.

...

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 (enbart vid framtagning av ny domän)

Om det är aktuellt att skapa en ny tjänstedomän, ta först kontakt med till kundservice@inera.sekontakt med Arkitektur och Regelverk enligt anvisning under http://rivta.se/begaran/ 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 Bitbucketi Bitbucket

Ansökan om behörighet sker genom att kontakta Inera Arkitektur och Regelverk till kundservice@inera enligt anvisning under http://rivta.se/begaran/. Meddela  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å 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 Gör en s.k. ”klon” (lokal kopia) av tjänstedomänens Git-repository. Beskrivning om hur det görs finns på http://rivta.se/bitbucket/.

...

Skapa katalogstruktur (enbart vid framtagning av ny domän)

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 21.


2.

...

2               Uppdatera eller skapa

...

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.

...

dokumentation och tekniska artefakter

Skapa/uppdatera dokumentation

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

Skapa dokumentation

Följande dokument ska skapas när en ny domän tas fram (mallarna för dokumenten finns på: http://rivta.se/

...

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 kundservice@inera.se med angivande av namn på tjänstedomän och vilken RC som begäran avser.

...

documents.html):

  • Informationsspecifikation

  • Tjänstekontraktsbeskrivning

  • Arkitekturella beslut (Om inga arkitekturella beslut har fattats ska det stå ”inga avsteg gjorda” i AB-dokumentet.)

  • Release notes (Se release notes för tjänstedomän)

Uppdatera dokumentation

När dokumentation ska uppdateras görs det i senaste version av dokumenten som finns för den versionen av domänen som ska uppdateras.


Skapa/uppdatera schemafiler/byggscript

På http://rivta.se/development.html finns referens till verktyg som kan användas vid skapandet/uppdatering av schemafilerna. Anvisningar som finns på samma sida bör följas.

För att skapa byggscripten, ta hjälp av rivta-tools/build-script-generators


Skapa/uppdatera testsviter

För att ta fram testsviter för tjänstekontrakten, se rivta-tools/servicedomain-test-framework


Checka in dokumentationen, de tekniska artefakterna och testsviterna i tjänstedomänens Git-repository på Bitbucket. För mer information, se "Checka in och publicera till Bitbucket" i appendix 1.

2.3    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.4                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 http://rivta.se/domainsbitbucket.

För att få implementera en RC i den nationella tjänsteplattformens QA-miljö (acceptanstestmiljö) krävs att den har kvalitetssäkrats av Begäran om kvalitetssäkring sker genom att kontakta 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 kundservice@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 kundservice@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å  enligt anvisning under http://rivta.se/begaran/.

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änstekontrat genom att skicka in en A-blankett (som finns på inera.se


2.5               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är paketering och publicering genom att kontakta Inera Arkitektur och Regelverk enligt anvisning under http://rivta.se/begaran/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

...

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.

...

  • 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

...

. Ange 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               Ta bort release av tjänstedomän

När en release är inaktuell ansvararTjänstedomänansvarig/Tjänsteansvarigför att begära borttagning av den, genom att kontakta Inera Arkitektur och Regelverk enligt anvisning under http://rivta.se/begaran/. Ange namn på tjänstedomän och aktuell 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.

...

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 (komplex) 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ändratsHelt nya element och typer läggs till direkt i den nya versionen av schemat det behövs alltså inte något utökningsschema (EXT fil) för detta


Release candidates (Domän)

...