Konfigurationsstyrning tjänstedomäner

Version 2.2.9

ARK_0007

2022-12-07

Revisionshistorik

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.2	2018-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.3	2019-03-06	Bytt ”Bilaga” till ”Appendix”.	Ranjdar Fallyih
2.2.4	2019-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.5	2019-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
2.2.6	2019-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 plats	Björn Hedman
2.2.7	2020-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
2.2.8	2022-05-06	Textuella uppdateringar för att öka tydligheten i dokumentet. Bytt ut Arkitektur och Regelverk mot Inera Arkitektursektion. Lagt till information om hur JoL-headern ska refereras till i berörda tjänstekontrakt. Lagt till ett exempel på hur olika ändringar påverkar versionering Flyttar information om versionering från Appendix till avsnitt 3	Tobias Blomberg Anneli Duveborg
2.2.9	2022-12-07	Tagit bort information om byggskript då dessa ej ska inkluderas i domänpaketeringen framöver. Lagt till bildtexter	Tobias Blomberg

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

Referenser

Namn	Kommentar	Länk
RIVTA tjänstedomäner	Här finns alla nationella tjänstedomäner listade, tillsammans med dess tjänstekontrakt releaser, och granskningsstatus.	http://rivta.se/domains
RIVTA dokument	Här finns länkar till T-boken, RIV tekniska anvisningar samt mallar och anvisningar för SAD, tjänstekontraktsbeskrivning och arkitekturella beslut (AB)	http://rivta.se/documents
Bitbucket	Här finns källkod och dokumentation för alla nationella tjänstedomäner. Varje tjänstedomän har dessutom en ärendehantering, avsedd för buggrapporter och ändringsförslag.	http://rivta.se/source

1 Inledning

Detta är en praktisk handledning att använda vid utveckling av tjänstedomäner. Dokumentet innehåller vägledning i hur olika delar i en tjänstedomän tas fram, inklusive versionshantering. Dokumentet ägs och förvaltas av Ineras Arkitektursektion.

1.1 Målgrupp och förkunskaper

Dokumentet riktar sig i första hand till de som praktiskt utvecklar och förvaltar tjänstekontrakt baserade på RIV Tekniska Anvisningar (RIV TA), men även till de som ansluter till tjänster där interaktionen beskrivs av tjänstekontrakt (tjänsteproducenter och tjänstekonsumenter).

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.

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 korrekt versionshantering och release av tjänstekontrakt och tjänstedomäner.

1.3 Avgränsning

Kravhantering 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 endast de releaser och releasekandidater som är föremål för den kvalitetssäkring och publicering som Ineras Arkitektursektion ansvarar för.

1.4 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:

Funktion	Verktyg
Använda versionshanteringssystemet på Bitbucket	Lämplig Git-klient, se http://rivta.se/bitbucket.
Köra RIVTA verktyg	Groovy 2.1 eller högre, se http://groovy.codehaus.org/ Python 2.7 eller högre, se https://www.python.org/
RIVTA verifiering	verifyRivtaDomain.py Beskrivning och installation: https://bitbucket.org/rivta-tools/verify-scripts/wiki/Home

1.5 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

Detta kapitel beskriver de aktiviteter som ingår vid release av tjänstedomäner tillsammans med hänvisningar till mallar, exempel och anvisningar.

För att skapa en ny release av en tjänstedomän är gången följande:

Vid utveckling av tjänstekontrakt arbetar projektet iterativt i Git
När projektet har en version som är klar för granskning, en så kallad release candidate (RC), görs en begäran till Ineras arkitektursektion för 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 om paketering och publicering genom att kontakta Ineras Arkitektursektion enligt anvisning under http://rivta.se/begaran/ .

Förtydligande

Utvecklingen av nya tjänstekontrakt eller nya versioner av befintliga tjänstekontrakt bör ske i samarbete med minst en tjänsteproducent och en tjänstekonsument. Nya tjänstekontrakt och nya versioner av befintliga tjänstekontrakt bör även acceptanstestas i en teknisk leverans av tjänstekonsument och tjänsteproducent mellan dessa innan granskning. Det är dock möjligt att, om det bedöms lämpligt, fastställa tjänstekontrakt utan acceptanstest mellan tjänstekonsument och tjänsteproducent.

Om den nya versionen är en minor, så ska den även testas för bakåtkompabilitet. Om det inte finns tillgång till testmiljöer för verkliga tjänstekonsumenter och tjänsteproducenter för dessa tester, så kan testsviter användas istället (se även kapitel 2.5)

2.1 Förberedelser

För att kunna utveckla och förvalta tjänstekontrakt krävs behörighet till nödvändiga resurser. För arbetet 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)

Vid utveckling av en ny tjänstedomän ska denna namnsättas av Ineras Arkitektursektion. Vid tillägg av ett nytt tjänstekontrakt inom befintlig domän ska Ineras Arkitektursektion ha godkänt tillägg av det nya tjänstekontraktet i den befintliga domänen.

Om det är aktuellt att skapa en ny tjänstedomän kontaktas Ineras Arkitektursektion enligt anvisning under http://rivta.se/begaran/

Beskriv vilken typ av information som ska hanteras, samt inom vilket verksamhetsområde. Ineras Arkitektursektion kommer då att besluta ifall en ny tjänstedomän skall skapas, samt tilldela svenskt och engelskt 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 Stödsystem. 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 behörighet.

Installera programvaror på lokal dator

Installera programvaror på din lokala dator enligt kapitel 1.4.

Klona Git-repository

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

2.2 Uppdatera eller skapa dokumentation och tekniska artefakter

Detta avsnitt beskriver hur man uppdaterar olika artefakter under utveckling/uppdatering av ett tjänstekontrakt. Processen för ny och vidareutveckling av tjänstekontrakt finns även beskriven mer ingående av Ineras Tjänstekontraktsförvaltning. För tillgång till den mer detaljerade processen, vänligen kontakta Ineras Tjänstekontraktsförvaltning, tk-forvaltningen@inera.se.

Under arbetet med framtagning av tjänstekontraktsbeskrivning kan Ineras Arkitektursektion vara behjälplig med vägledning. Checka in dokument, tekniska artefakt och testsviter i tjänstedomänens Git-repository på Bitbucket. För mer information, se "Checka in och publicera till Bitbucket" i appendix 1.

2.2.1 Dokumentation

Skapa dokumentation

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

Informationsspecifikation (se VI-boken för mer information, ARK_0026)
Tjänstekontraktsbeskrivning (ARK_0015)
Arkitekturella beslut (ARK_0023. 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 ett dokument ska uppdateras görs det i den senaste versionen av dokumentet som finns för den domänversion som ska uppdateras.

2.2.2 Skapa/uppdatera schemafiler

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

2.2.3 Skapa/uppdatera testsvit och självdeklaration

Vanligtvis tas testsviter och självdeklarationer fram av Nordic Medtest (NMT).

2.2.4 Skapa/uppdatera schematron

Schematron används för att kontrollera de logiska regler som gäller för ett visst tjänstekontrakt. Vanligtvis tas schematron fram av NMT.

2.2.4 Journal- och läkemedelsheadern

Journal- och läkemedelsheadern (JoL-headern) är en gemensam header som används av nyare versioner av tjänstekontrakt som hanterar journal- och läkemedelsinformation.

När denna header används, läggs en kopia av fältreglerna som PDF i "docs"-katalogen. Schemat för den aktuella versionen av headern klipps in i tjänstekontraktets schemafil. Detsamma gäller för headerns schematron som klipps in i tjänstekontraktets schematron.

Dokument med JoL-headerns fältregler samt schematron finns på Bitbucket: https://bitbucket.org/rivta-domains/best-practice/wiki/Home

2.3 Kvalitetssäkring

2.3.1 RIVTA Verifiering

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

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 anvisningarna i RIV TA

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

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

2.3.1 Skapa Tag i Git för releasekandidat (RC) och begär kvalitetssäkring

Formell kvalitetssäkring görs på en releasekandidat (RC) som taggats i Git. Namnsättning av tag beskrivs i appendix 3. Hur man skapar och publicerar en tag beskrivs på http://rivta.se/bitbucket.

Begäran om kvalitetssäkring sker genom att kontakta Ineras Arkitektursektion enligt anvisning under http://rivta.se/begaran/. Granskning av teknik och säkerhet görs av granskare på Ineras Arkitektursektion medan granskning av informatik/verksamhet görs genom en självgranskning. Självgranskningsprotokollet delges utvecklaren i samband med att begäran om kvalitetssäkring skett.

För att få implementera en RC i den nationella tjänsteplattformens QA-miljö (acceptanstestmiljö) krävs att den har kvalitetssäkrats och att Integrationsansvarig/Tjänsteansvarig har godkänt installation. Integrationsansvarig/Tjänsteansvarig beställer installation av tjänstekontrakt genom att skicka in en A-blankett (finns på inera.se)

2.4 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 testmiljö (QA/ÖTM) 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 Ineras Arkitektursektion (se http://rivta.se/begaran/). Den skapade taggen ska referera till samma Git commit som den senast godkända releasekandidaten. Regler för namnsättning finns i appendix 3. Ange namn på tjänstedomän och aktuell release.

Ineras Arkitektursektion skapar en zip-fil och publicerar den nya releasen på http://rivta.se/domains.

3. Versionshantering

3.1 Versionshantering av tjänstedomän

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

Ex 2.1 eller 2.1.1

Figur 1. Beskrivning av versionering av tjänstedomän.

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 release notes som bifogas paketeringen.

Nya tjänstekontrakt som tillkommer ska alltid börja med version 1.0 oavsett domänens version. När ett nytt tjänstekontrakt lagts till i en domän räknas bara tredje siffran upp i domänversionen såvida det inte även skett andra förändringar som påverkar domänversionen.

De flesta tjänstedomäner innehåller flera tjänstekontrakt i olika versioner, se exempel i grön kolumn nedan. Varje tjänstedomänsversion innehåller dock bara en tjänstekontraktsversion inom varje major, dvs version 3.1 ersätter version 3.0. Det fiktiva exemplet i den röda kolumnen nedan strider således mot reglerna.

clinicalprocess:healthcon:actoutcome 4.0.2	clinicalprocess:healthcon:actoutcome 4.0.2
GetLaboratoryOutcome 4.0	GetLaboratoryOutcome 4.0
GetReferralOutcome 3.1	GetReferralOutcome 3.0
GetImagingOutcome 1.0	GetReferralOutcome 3.1
GetMaternityMedicalHistory 2.0	GetImagingOutcome 1.0
	GetMaternityMedicalHistory 2.0

Exempel gällande domänversionering finns under Appendix 2.

3.2 Versionshantering av scheman

3.2.1 Versionshantering av tjänstekontraktsspecifika scheman

Ändringar och tillägg för datatyper som deklareras direkt i tjänsteinteraktionsschemat ska, vid en minor-uppdatering, alltid versionshanteras via en utökningsfil. Detta för att ändringen ska vara bakåtkompatibel (se regel #9 i RIV Tekniska Anvisningar Tjänsteschema http://rivta.se/documents/ARK_0005/). Vid major-uppdateringar kan sådana ändringar göras direkt i tjänsteinteraktionsschemat.

3.2.2 Versionshantering av domängemensamma scheman

Typer som används i flera tjänstekontrakt 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 en utökning av en befintlig (komplex) typ, avser nya valfria element och ändringen ska vara bakåtkompatibel görs förändringen via ett utökningsschema. Se Regel #6 i RIV TA Domänschema http://rivta.se/documents/ARK_0006/

Helt nya element och typer läggs till direkt i den nya versionen av schemat. Där behövs det alltså inte något utökningsschema (EXT fil).

3.3 Releasekandidater

Under utvecklingsarbetet av en ny domänversion så kan justeringar behöva göras. Detta markeras som en releasekandidat (RC). Versionsnummer för releasekandidater 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årbarhet 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 paketering och numrering i dokumentation som markeras som RC och alltså inte de ingående tjänstekontrakten eller andra tekniska komponenter.

4 Ta bort release av tjänstedomän

När en release är inaktuell ansvarar Integrationsansvarig/Tjänsteansvarig för att begära borttagning av den genom att kontakta Inera Arkitektursektion enligt anvisning under http://rivta.se/begaran/. Ange namn på tjänstedomän och aktuell release som ska tas bort.

Inera Arkitektursektion tar bort zip-fil från rivta.se samt i tabeller över fastställda tjänstedomäner.

Appendix 1 – Skapa Git-repository

Översikt

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

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

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 filstruktur. Denna struktur och namnstandard är inkorporerad i script och måste därför strikt följas.

Exempel:

Figur 2. Filstruktur i tjänstedomän.

docs

I "docs"-katalogen finns tjänstekontraktsbeskrivning (TKB), informationsspecifikation (IS), arkitekturella beslut (AB) och självdeklarationer. Om något eller några tjänstekontrakt i domänen använder JoL-headern, ska denna katalog även innehålla fältregeldokument för de versioner av JoL-headern som används i domänen.

Namnen på dokumenten skall baseras på tjänstedomänens engelska namn, med dess delar avskilda med underscore, och följa mönstret nedan:[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
SjD_TK_<tjänstekontraktsnamn>.docx, ej obligatoriskt

Exempel:

Figur 3. Filstruktur i mappen docs.

Schemas

WSDL:er och scheman ordnas i katalogen ”schemas”. I ”schemas” ska två underkataloger finnas: ”core_components”, och ”interactions”.

Exempel:

Figur 4. Filstruktur i mappen schemas

”core_components” innehåller scheman som är generella för domänen (t.ex. domän-scheman och header-scheman)
”interactions” innehåller en underkatalog per tjänstekontrakt. I dessa ska schema och WSDL ligga som är specifika för respektive tjänstekontrakt.
"engagementindex" (ej obligatorisk) innehåller verktyg för validering av de delar av schemat som används av engagemangsindex.

test-suite

Innehåller tester tillhörande respektive tjänstekontrakt.

README

README är en textfil som innehåller länkar till Release Notes, gemensamma datatyper samt eventuella interaktionsöverenskommelsedokument och mappningsdokument tillhörande domänen.

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:

Skapa en lokal katalog med samma namn som det repository som skapats på Bitbucket, t.ex. ”riv.clinicalprocess.healthcond.actoutcome”.
Ställ dig i katalogen och skriv kommandot ”git init”.
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:

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 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 – Exempel versionshantering

Versionshantering för olika typer av ändringar - Exempel

Nedan figur visar ett exempel på hur olika typer av ändringar påverkar versioneringen av tjänstekontrakt och tjänstedomäner. Kolumnen Ändring visar vilken typ av ändring som skett i domänen med en streckad linje till tjänstekontraktet i vilket förändringen skett. Sista kolumnen redovisar utfallet på domänversionen baserad på den aktuella förändringen.

Figur 5. Flöde över versionering av tjänstedomän.

Textuell beskrivning av domänversionering

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

Appendix 3

Namnsättning av tag

Taggen namnges efter tjänstedomänens aktuella version.

Exempel för Releasekandidat: 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. Långa tag-namn kan trunkeras i Bitbuckets webbgränssnitt. Alla nya domäner ska därför använda den nya formen av namnsättning.

Namnsättning av Zip-fil

I normalfallet skapas och publiceras ZIP-filen av Inera Arkitektursektion 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.