Open	Konfigurationsstyrning tjänstedomäner   Version 2.2.10 ARK_0007   2026-05-11

Ordlista

Referenser

1. Inledning

Detta är en praktisk handledning som kan användas vid utveckling av tjänstekontrakt och tjänstedomäner enligt RIV Tekniska Anvisningar (RIV TA). Dokumentet innehåller vägledning i hur tjänstekontrakten tas fram samt versionshanteras. Dokumentet ägs och förvaltas av Inera. Processen för ny och vidareutveckling av tjänstekontrakt finns även beskriven mer ingående av Ineras gruppering Informationsarkitektur och kodverk. För tillgång till den mer detaljerade processen, vänligen kontakta informationsarkitektur@inera.se. 

1.1 Målgrupp

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

1.2 Förkunskaper

För att använda handledningen krävs förkunskaper i användandet av versionshanteringssystem (specifikt Git), design av WSDL och XML-schema.

1.3 Syfte

Syftet med anvisningen är att säkerställa korrekt versionshantering och release av tjänstekontrakt och tjänstedomäner. Anvisningen innehåller normerande regler och processbeskrivningar för framtagande av nationella tjänstekontrakt hos Inera. För externt administrerade och lokalt framtagna tjänstekontrakt ska anvisningen ses som vägledande.

1.4 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 tjänstekontrakt och tjänstedomäner som avser följa regelverket som beskrivs i RIV TA.  

1.5 Krav på utvecklingsmiljö

De som ska arbeta praktiskt med tjänstekontraktsutveckling enligt denna handledning behöver ha tillgång till en lämplig Git-klient, se http://rivta.se/bitbucket.

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

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 krävs följande:

1. Förberedelse

2. Uppdatera eller skapa dokumentation och tekniska artefakter

3. Kvalitetssäkring

4. Paketering och publicering

2.1 Förberedelser

För att utveckla och förvalta tjänstekontrakt krävs behörighet till nödvändiga resurser. För arbete med nationella domäner behövs ett konto på Bitbucket samt behörighet till aktuell tjänstedomän.

2.2 Uppdatera eller skapa dokumentation och tekniska artefakter

Detta avsnitt beskriver hur man uppdaterar olika artefakter under utveckling/uppdatering av ett tjänstekontrakt. 

Varje tjänstedomän består av dokumentation och tekniska artefakter som antingen publiceras i tjänstedomänpaketet eller hänvisas till från dokumentationen i tjänstedomänpaketen. Nedan finns korta beskrivningar av alla artefakter som ingår i en tjänstedomän samt var dessa ska publiceras. När respektive artefakt är framtagen checkas denna in i tjänstedomänens Git-repository på Bitbucket. För mer information, se "Checka in och publicera till Bitbucket" i appendix 1. Observera att ett releasepaket ska innehålla alla tjänstekontrakt, dokument osv. som ingår i domänen. Detta gäller oavsett om de ändrats i den nya releasen eller ej.

Open Figur 1. Exempel 1 domänpaketering       Open Figur 2. Exempel 2 domänpaketering	a) Tjänstekontraktsbeskrivning ARK_0015	Varje tjänstedomän måste ha minst en tjänstekontraktsbeskrivning. Tjänstekontraktsbeskrivningen kompletterar de regler som finns i de tekniska artefakterna avseende strukturen på meddelande. Beroende på tjänstedomänens egenskaper finns olika sätt att strukturera tjänstekontraktsbeskrivningen på: En tjänstekontraktsbeskrivning per tjänstekontrakt som ingår i tjänstedomänen. En gemensam tjänstekontraktsbeskrivning för tjänstedomänens ingående tjänstekontrakt. En kombination av ovanstående alternativ, dvs. några av tjänstedomänens tjänstekontrakt publiceras i en gemensam tjänstekontraktsbeskrivning medan andra publiceras i egna tjänstekontraktsbeskrivningar.
	b) Tjänsteschema ARK_0005	Varje tjänstekontrakt har sitt eget XML-schema vilket definierar element som utgör tjänstens begäran och svar. I detta schema beskrivs tjänstespecifika element.
	c) Domänschema ARK_0006	Tjänstedomänen har ett domänschema per majorversion av domänen som definierar element som är gemensamma för två eller fler tjänstekontrakt inom tjänstedomänen.
	d) Informationsspecifikation ARK_0026	De element som ingår i tjänstekontraktens begäran och svar är utformade med stöd av information som finns beskriven i en informationsspecifikation. Tjänstekontrakten kan baseras på en eller flera informationsspecifikationer. Informationsspecifikationen publiceras med fördel på Öppen info: Informatik för att kunna återanvändas (se figur 1). Om den hanterade information är mycket specifik och avgränsad är det även möjligt att publicera informationsspecifikationen i tjänstedomänpaketet (se figur 2). Det finns även möjlighet att paketera en version av en informationsspecifikation som publicerats på Öppen info: Informatik i tjänstedomänpaketet.
	e) Övergripande dokumentation om aktuella tjänstekontrakt	I de fall flera tjänstekontrakt (i en eller flera tjänstedomäner) har likvärdig arkitektur samt krav och regler är det tillåtet att publicera denna dokumentation utanför tjänstedomänpaketen för att underlätta förvaltning av dokumentationen (se figur 1). I dessa fall hänvisas till denna information från tjänstekontraktsbeskrivningen. Information som hänvisas till utanför tjänstedomänpaketeringen behöver versionshanteras separat. Om detta inte är aktuellt publiceras denna dokumentation i tjänstekontraktsbeskrivningen (se figur 2).
	f) Självdeklaration Tas fram av Inera test och utveckling.	Anslutning till nationella tjänsteplattformen bygger på en tillitsmodell som innebär att anslutande part själv kan testa att anslutningen följer tjänstekontraktsbeskrivningen. Det finns två självdeklarationer per tjänstekontrakt, en för producenter och en för konsumenter.
	g)  Testsvit Tas fram av Inera test och utveckling.	Används för att verifiera anslutningar.
	h) Schematron Tas fram av Inera test och utveckling.	Används för att kontrollera logiska regler som gäller för ett visst tjänstekontrakt. Dessa regler finns också listade i TKB, kapitel ”Övriga regler”.
	i) Release notes release notes för tjänstedomän	Release notes för en nyskapad tjänstedomän eller för en uppdaterad tjänstedomän riktar sig främst till dem som vill ansluta sig till en tjänstedomänsversion och ska få en överblick över: varför versionen har skapats och vad den omfattar (i form av kontrakt och tillhörande dokumentation och artefakter) vad som har ändrats i tjänstedomänen jämfört med föregående version Release notes publiceras här och ska finnas för varje ny release.

2.3 Kvalitetssäkring

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 . När all dokumentation samt alla tekniska artefakter tagits fram eller uppdaterats ska tjänstedomänen kvalitetssäkras. Detta görs i två steg, RIV TA verifiering samt kvalitetssäkring av Ineras gruppering Informationsarkitektur och kodverk. 

2.3.1    RIV TA Verifiering

Det projekt eller den förvaltning som ansvarar för utvecklingen verifierar sin RC mot regelverket i RIV TA. Detta görs med hjälp av python-scriptet ”verifyRivtaDomain.py” (se kapitel 1.4) lokalt eller med hjälp av automatiseringsverktyget Jenkins.

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 RC, ska dessa korrigeras och hanteras före begäran om kvalitetssäkring.

2.3.1 Kvalitetssäkring

Begäran om kvalitetssäkring sker enligt anvisning under http://rivta.se/begaran/ .

2.4 Paketering och publicering

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 enligt anvisning under 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.  

Inera 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 (se figur 3).

Open

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

3.1.1 Tjänstedomäner med fler än ett tjänstekontrakt

De flesta tjänstedomäner innehåller flera tjänstekontrakt i olika versioner.  Grundregeln för versionsnumrering är att tjänstedomänens major- och minorversion 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.

3.1.2 Tjänstedomänpaketering efter uppdatering av tjänstekontrakt

En tjänstedomän av en viss version får enbart innehålla en version av ett givet tjänstekontrakt. Detaljerade exempel gällande domänversionering finns i Appendix 2.

3.1.2.1 Minoruppdatering av tjänstekontrakt

Om ett tjänstekontrakt genomgått en minoruppdatering ersätter den nya versionen av tjänstekontraktet den gamla inom paketeringen (se figur 4). 

Open

Figur 4. Tjänstedomänpaketering i samband med minoruppdatering av tjänstekontrakt.

3.1.2.2 Majoruppdatering av tjänstekontrakt

När ett tjänstekontrakt genomgått en majoruppdatering ligger den äldre versionen ofta kvar i produktion under en övergångsperiod. I detta fall ersätts den gamla domänpaketeringen av två nya. Den ena domänpaketeringen innehåller den gamla majorversionen av det uppdaterade tjänstekontraktet. Den andra domänpaketeringen innehåller den nya majorversionen av det uppdaterade tjänstekontraktet samt resterande tjänstekontrakt i domänen (se figur 5a).

När en majoruppdatering sker av ett av de “gamla” tjänstekontrakten i den nya tjänstedomänversionen, flyttas den gamla versionen av tjänstekontraktet till den tidigare versionen av domänpaketeringen och den nya tjänstekontraktsversionen ligger kvar i den senaste versionen av domänpaketeringen (se figur 5b).

Denna komplexa hantering sker för att kunna fortsätta förvalta (göra uppdateringar) av parallella tjänstekontraktsversioner.

Open

Figur 5a. Tjänstedomänpaketering i samband med majoruppdatering av tjänstekontrakt.

 

 

 

 

 

 

 

 

Open

Figur 5b. Tjänstedomänpaketering i samband med en andra majoruppdatering av tjänstekontrakt.

 

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 minoruppdatering, alltid versionshanteras via en utökningsfil. Detta för att ändringen ska vara bakåtkompatibel (se regel #9 i RIV TA Tjänsteschema http://rivta.se/documents/ARK_0005/ ). Vid majoruppdateringar 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 se Regel #6 i RIV TA Domänschema http://rivta.se/documents/ARK_0006/

Nedan finns en illustration samt beskrivning av var datatyper deklareras.

Open Figur 6	Open Figur 7	Open Figur 8
I tjänstedomän version 1.0 finns en datatyp (orange triangel) som domänens båda tjänstekontrakt nyttjar. Datatypen deklareras i det gemensamma domänschemat.	I tjänstedomän version 2.0 har tjänstekontrakt B genomgått en majoruppdatering och använder inte längde datatypen orange triangel. Den använder istället datatypen turkos cirkel som inte används i tjänstekontrakt A. Datatypen orange triangel flyttas till tjänsteschema A och datatypen turkos triangel deklareras i tjänsteschema B. Om tjänstedomänens ingående tjänstekontrakt inte har några gemensamma datatyper är det inte nödvändigt att ha ett domänschema.	I tjänstedomän version 2.0.1 har tjänstekontrakt A genomgått en majoruppdatering och använder inte längre datatypen orange triangel. Den använder dock datatypen turkos cirkel som tidigare bara användes av tjänstekontrakt B. Datatypen turkos cirkel flyttas till domänschemat.

4. Ta bort release av tjänstedomän

När en viss version av en tjänstedomän är inaktuell ansvarar Integrationsansvarig/Tjänsteansvarig för att begära borttagning av den genom att följa instruktionerna här http://rivta.se/begaran/ . Ange namn på tjänstedomän och aktuell release som ska tas bort. 

Appendix 1 – Skapa Git-repository

Katalogstruktur

Alla tjänstedomäner ska följa en gemensam och fastställd katalodstruktur. 

Exempel:

Open

Figur 9. Katalogstruktur i tjänstedomän

docs