Versions Compared

Old Version 2

changes.mady.by.user Unknown User (henrik.rikard@capgemini.com)

Saved on

compared with

New Version Current

changes.mady.by.user Jacob Qvortrup

Saved on

Key

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


Table of Contents

Numbered Headings

Introduktion

Dette dokument beskriver krav for komponentleverancer til NSP platformen. Kravene er gældende for udviklingen af komponenter rettet mod nye leverancer til projektet samt ændringer til eksisterende komponenter.

De her beskrevne krav og anbefalinger skal ses som retningslinjer for at skabe en homogen platform, hvor mange forskellige komponenter kan sam-eksistere og fungere i et driftet miljø. Reglerne er fastsat ud fra hensyn til at udviklere til NSP projektet har en stor grad af frihed og samtidig understøtter modtagelsen af komponenter med henblik på kvalitetskontrol af NSP platformen.

Projekter, der skal levere nye komponenter til NSP platformen, skal fastholde, hvilken version af husreglerne der leveres i henhold til. Versionen registreres i OAT beskrivelserne. Læs mere om OAT her.

Såfremt leverandører ønsker at afvige fra kravene i forbindelse med komponent leverancer indledes en dialog med NSP platformen. Specielle begrundede behov tilgodeses så vidt muligt. Dette vil også kunne aftales via OAT.

Skriv til denne email adresse: operator@nspop.dk

Dokument status

Husreglerne er under løbende forandring, da de dækker en platform, der er under stadig udvikling. Forslag til ændringer modtages og vurderes under hensyntagen til NSP platformens interesser.

Skriv til denne email adresse: operator@nspop.dk - skriv "Forslag til husregler" i emnet.

Krav og referencer

Krav er markeret med en entydig designation samt et § efterfulgt af indholdet. Referencer til et krav i Husreglerne, kan beskrives på følgende format:

 HR:<paragraf nr.>

En reference til en paragraf i Husreglerne skal desuden beskrive den aktuelle version af reglerne.

Ved en enkeltstående reference, kan der desuden bruges følgende notation – her givet som et eksempel:

 HR:4.5.1-1.3

Eksemplet refererer til version 1.3 og første paragraf i afsnit 4.5.

Begreber og forkortelser

Få forklaringer på begreber og forkortelser i ordlisten.

Designkrav

Platform

Endelig produktionsplatform defineres i forbindelse med releaseprocessen i samråd med NSP projektet.

NSP Projektet stiller et NSP Docker image til rådighed for udvikling og test. Dog skal der tages hensyn til at platformen kan ændre sig inden endelig release.

Leverancen skal ske som et eller flere Docker images samt tilhørende Docker Compose filer. Se NSP Continuous Integration & Delivery for yderligere detaljer

Udviklingsprojektet skal være opmærksom på, at udviklingsplatformen vil afvige på nogle punkter i forhold til produktionsplatformen.

Inden leverancen afleveres til NSP projektet, skal den kunne bygge i NSP Docker Build image via et Jenkins job.

Til information, men ikke som autoritativ kilde, er her minimumsversioner af platformsafhængighederne, komponenterne forventes at bliver udstillet på:

  • Wildfly 8.2 applikationsserver
  • HAproxy 1.4.13
  • Java (CorrettoJDK) 8 (8.202.08-2)
  • MariaDB (10.3.16)
  • Kafka (1.1.0)
  • Ubuntu Server LTS 18.04
  • Docker (18.09.6)
  • Docker Compose (1.23.2)

Applikationsstack

Info

2.1.1 § Komponenter skal kunne afvikles i platformens applikationsserver i den udstillede platformscontainer

Applikationsserver-platformen stiller standard Java Servlet funktionalitet til rådighed, så som JNDI, JDBC og servlet API.

Info

2.1.2 § Komponenter skal udvikles i programmeringssproget Java passende til den aktuelle platformsversion af JDK.

Info

2.1.3 § Komponenter skal baseres på Java Servlet 3.0 specifikationen. Brug af yderligere JEE features så som EJB mv er ikke tilladt.

Info

2.1.4 § Applikationer må ikke benytte XA transationer mod databaseplatformen, da det ikke understøttes.

Info

2.1.5 § Opslag i stamdata skal ske via dennes opslagsservices, hvis en sådan ikke findes kan der efter aftale med NSP anvendes et database view.

Info

2.1.6 § Adgang til Kafka skal ske gennem NSP Kafka Clients biblioteket (på iNSP findes der p.t. ingen Kafka. Kan evt. etableres i samarbejde med projekt)

Info

2.1.7 § For at opnå inversion of control bruges spring til dependency injection NSP Dependency Injection

Anvendelse af kodebiblioteker

Info

2.2.1 § Komponenter skal bruge de kodebiblioteker, som platformen stiller til rådighed. Derudover skal udviklingsprojektet levere de anvendte kodebiblioteker eller referere til disse i offentlig tilgængelige repositories.

Info

2.2.2 § Komponenter skal stræbe efter at benytte de kodebiblioteker platformen udbyder og, så vidt muligt anvende de standard kodebiblioteker der leveres med  Wildfly platformen.

Info

2.2.3 § Af hensyn til reproducerbarheden, så er det ikke muligt at referere til kodebiblioteker i repositories som er leveret/opstillet af komponentleverandøren.

Info

2.2.

...

Dato:        

...

Version:                         

...

Tilføjet:                    

...

Ændret:                            

...

Fjernet:                   

...

Maven 2

Ant

...

06-01-2016

...

1.7

...

afsnit 3.3.4

...

03-10-2017 

...

Table of Contents

...

2.2.
Numbered Headings

Introduktion

Dette dokument beskriver krav for komponentleverancer til NSP platformen. Kravene er gældende for udviklingen af komponenter rettet mod nye leverancer til projektet samt ændringer til eksisterende komponenter.

De her beskrevne krav og anbefalinger skal ses som retningslinjer for at skabe en homogen platform, hvor mange forskellige komponenter kan sam-eksistere og fungere i et driftet miljø. Reglerne er fastsat ud fra hensyn til at udviklere til NSP projektet har en stor grad af frihed og samtidig understøtter modtagelsen af komponenter med henblik på kvalitetskontrol af NSP platformen.

Projekter, der skal levere nye komponenter til NSP platformen, skal fastholde, hvilken version af husreglerne der leveres i henhold til. Versionen registreres i OAT beskrivelserne. Læs mere om OAT her.

Såfremt leverandører ønsker at afvige fra kravene i forbindelse med komponent leverancer indledes en dialog med NSP platformen. Specielle begrundede behov tilgodeses så vidt muligt. Dette vil også kunne aftales via OAT.

Skriv til denne email adresse: nsp.op@nsi.dk

Dokument status

Husreglerne er under løbende forandring, da de dækker en platform, der er under stadig udvikling. Forslag til ændringer modtages og vurderes under hensyntagen til NSP platformens interesser.

Skriv til denne email adresse: nsp.op@nsi.dk - skriv "Forslag til husregler" i emnet.

Krav og referencer

Krav er markeret med en entydig designation samt et § efterfulgt af indholdet. Referencer til et krav i Husreglerne, kan beskrives på følgende format:

 HR:<paragraf nr.>

En reference til en paragraf i Husreglerne skal desuden beskrive den aktuelle version af reglerne.

Ved en enkeltstående reference, kan der desuden bruges følgende notation – her givet som et eksempel:

 HR:4.5.1-1.3

Eksemplet refererer til version 1.3 og første paragraf i afsnittet om Logning.

Begreber og forkortelser

Få forklaringer på begreber og forkortelser i ordlisten.

Designkrav

Platform (gl 4)

Endelig produktionsplatform defineres i forbindelse med releaseprocessen i samråd med NSP projektet.

NSP Projektet stiller en NSP til rådighed for udvikling og test. Dog skal der tages hensyn til at platformen kan ændre sig inden endelig release.

Udviklingsprojektet skal være opmærksom på, at udviklingsplatformen vil afvige på nogle punkter i forhold til produktionsplatformen.

Inden leverancen afleveres til NSP projektet, skal den kunne bygge på applikationsstack svarende til NSP.

Til information, men ikke som autoritativ kilde, er her minimumsversioner af platformsafhængighederne, komponenterne forventes at bliver udstillet på:

  • Wildfly 8.2 applikationsserver
  • HAproxy 1.4.13
  • Java (JDK) 8 (1.8.0_05)
  • MariaDB (10.1.19)
  • Ubuntu Server LTS 14.01

Applikationsstack (gl 4.1)

Info

2.1.1 § Komponenter skal kunne afvikles i platformens applikationsserver. (gl. 4.1.1)

Applikationsserver-platformen stiller standard JEE funktionalitet til rådighed, så som EJB, JNDI, servlet API og diverse andre Java EE API’er.

Det anbefales at komponentudvikling så vidt muligt kun anvender Java Servlet funktionalitet ved implementering. Eventuel anvendelse af EJB funktionalitet skal ske efter aftale med NSP projektet.

Info

2.1.2 § Komponenter skal udvikles i programmeringssproget Java passende til den aktuelle platformsversion af JDK. (gl. 4.1.2)

Info

2.1.4 § Applikationer må ikke benytte XA transationer mod databaseplatformen, da det ikke understøttes.

Info

2.1.5 § Opslag i stamdata bør så vidt muligt ske via et database view der defineres i samarbejde med NSP.

 Anvendelse af kodebiblioteker (gl 3.3)

Info

2.2.1  § Komponenter skal bruge de kodebiblioteker, som platformen stiller til rådighed. Derudover skal udviklingsprojektet levere de anvendte kodebiblioteker eller referere til disse i offentlig tilgængelige repositories. (gl. 3.3.1)

Info

2.2.2 § Komponenter skal stræbe efter at benytte de kodebiblioteker platformen udbyder og, så vidt muligt anvende de standard kodebiblioteker der leveres med  Wildfly platformen. (gl. 3.3.2)

Info

2.2.3  § Af hensyn til reproducerbarheden, så er det ikke muligt at referere til kodebiblioteker i repositories som er leveret/opstillet af komponentleverandøren. (gl. 3.3.3)

Info

4 § Komponenter skal, når der anvendes 3. parts kodebiblioteker, såvidt det er muligt, anvende nyeste version som stadig er under aktiv udvikling samt, (gennem udviklingsprojektet for 3. parts biblioteket, at have mulighed for at yde support til anvendere af dette 3. parts bibliotek.

(gl. 3.3.4))

)

NSP projektet tilstræber, at komponenter på NSP platformen anvender de samme 3’parts kodebiblioteker. NSP projektet stiller en liste over godkendte kodebiblioteker til rådighed for udviklingsprojekterne.

Info

2.2.5 § Såfremt projekterne har behov for at anvende andre kodebiblioteker til løsningerne end dem der er godkendt, skal det ske efter aftale med NSP projektet.

Anvendelse af produktspecifikke kodebiblioteker bør såvidt som muligt undgås og skal ske efter nærmere aftale med NSP projektet. Eksempler er kodebiblioteker der kan vanskeliggøre en migrering til f.eks. anden applikationsserver eller andet databasesystem.

Et projekt, der bygges med Maven, kan indeholde referencer til andre eksisterende Maven projekter. 

Det forventes, at disse er installeret og er tilgængelige for bygget. Hvis ikke projektet anvender Apache Maven til at bygge løsningen, forventes det, at dokumentationen beskriver, hvor evt. kodebiblioteker skal placeres.

Endvidere henvises der til Platformsapplikationer, som beskriver, hvilke versioner af platformsspecifik programmel der allerede findes på platformen.

HAProxy

(gl 4.2)

Info
2.3.
1 
1 § Som beskrevet i HTTP version 1.1 specifikationen http://www.ietf.org/rfc/rfc2616.txt, skal den sidste værdi benyttes i tilfælde med flere ens header fields.
(gl. 4.2.1)

Loadbalanceren påhæfter altid HTTP forespørgsler en ny header indeholdende klientens IP adressen i X-Forwarded-For. Den vil aldrig fjerne en header og vil altid tilføje til enden, hvorfor duplikater kan forekomme.

HAProxy anvender round-robin til fordeling af forespørgelser, der rammer NSP’en. Desuden understøtter HAProxy ikke session affinitet. 

Info

2.3.

2 

2 § Komponenter kan ikke regne med at, på hinanden følgende forespørgelser rammer samme NSP søjle (applikationsserver).

(gl. 4.2.2)

Konfiguration

(gl 4.3)

Komponenter konfigureres til de forskellige NSP miljøer gennem en række Docker Compose og Ansible scripts. Af hensyn til dette bør komponenters statiske konfiguration være filbaseret. Eventuel initialisering af databasen skal foretages med scripts eller foretages transparent af komponenten.

Info

2.4.1

 §

§ Statisk konfiguration skal være filbaseret

. (gl

.

4.3.1)

Dette sikrer at driftsleverandøren let kan ændre disse ved deployering.

(

Statisk konfiguration defineres som den generelle konfigurering af komponenten, der kun anvendes under komponentens opstart.

)

Statisk konfiguration kan deles op i to grupper. Konfiguration der kun skal ændres ifm. en ny leverance skal ligge inde i det leverede Docker image, konfiguration der skal ændres af driften ifm deployering skal volume mappes ind med Docker Compose.

Info

2.4.2 §

Info2.4.2  §

Database opsætning bør ske vha. en selvstændig Wildfly datasource

descriptor 

descriptor fil og benyttes ud fra JNDI eller lignende tilgang.

(gl. 4.3.2)

Info

2.4.3

 §

§ Konfigurationer, hvor det skal være muligt at ændre efter opstart af komponenten, såsom f.eks. adgangskontrol, må ikke være filbaseret. Komponentdesignet må ikke basere sig på ændringer til platformen efter produktionsdeployment. Konfiguration, der ønskes ændret herefter, skal ske gennem en anden mekanisme; f.eks. en database på NSP databasesystemet

. (gl. 4.3

.

3)

Info

2.4.4 § Komponentkonfiguration skal placeres i højst en fil per service/delkomponent. Anden konfiguration såsom log eller database opsætning kan specificeres andensteds.

(gl. 4.3.4 ) 

Beskrivelse af NSP databaseplatformen kan findes på nspop.dk.

For nogle komponenter vil adgangskontrol såsom whitelistning og blacklistning være et krav. Disse skal som ovenfor beskrevet være konfigurerbare via databasen. I forbindelse med nye anvendere på platformen skal adgangskontrollen kunne udvides. Hertil ønskes sporbarhed.

Info

2.4.5 § Det skal være muligt direkte at associere en kommentar til adgangskontrol-indgange.

(gl. 4.3.5)

Eksempelvis kunne dette muliggøres ved at have en extra kolonne i tabeller med adgangskontrol. 

Snitflade til monitorering (gl 4.4)

Info

2.4.6 § Konfiguration af NSP Kafka Clients skal ske som beskrivet i Den Gode Brug af Kafka

Info

2.

5

4.

1 § Komponenter skal stille en simpel HTTP service til rådighed for load balanceren på platformen. Denne bruges til at afgøre om servicen på søjlen er aktiv. Servicen skal levere sin status som et simpelt ja/nej; hhv. HTTP status kode 200 eller 5xx. (Se http://www.ietf.org/rfc/rfc2616.txt afsnit 10). (gl. 4.4.1) Med begrebet “aktiv” forstås at servicen kan

7 § En komponent må ikke indeholde default konfiguration for om den er i et testmiljø eller et produktionsmiljø.

En konfigurationsparameter der f.eks. styrer hvilken Seal føderation der anvendes må ikke have nogen default værdi i de konfigurationsfiler der leveres. Denne værdi skal altid udfyldes af driften. Dette sikrer at der ikke kan køre komponenter i produktion der tager imod testcertifikater.

Snitflade til monitorering

Info

2.5.1 § Komponenter skal stille en simpel HTTP service til rådighed for load balanceren på platformen. Denne bruges til at afgøre om servicen på søjlen er aktiv. Servicen skal levere sin status som et simpelt ja/nej; hhv. HTTP status kode 200 eller 5xx. (Se http://www.ietf.org/rfc/rfc2616.txt afsnit 10).

Med begrebet “aktiv” forstås at servicen kan svare på forespørgsler ud fra fungerende lokale services. Hvis en service funktion afhænger af eksterne (for NSP) services, så skal disse ikke indgå i svaret.
Specifikt behandles følgende HTTP status koder:
200: Komponenten fungerer og kan anvendes.
5xx: Komponenten melder at den ikke kan anvendes.
404: Komponenten er ikke deployet.
Andre: Servicen er ikke tilgængelig.

Info

2.5.2 § Servicen skal kunne håndtere hyppige forespørgelser (cirka et hvert 10 sekund). Den må deslige ikke blokere på andre services uden

for NSP platformen. (gl. 4.4.2)
Info

2.5.3 § Et svar på 200 vil i loadbalanceren afgøre om forespørgelser kan routes til pågældende service. Det er derfor vigtig at alle afhængigheder, en service måtte have, indgår i dette svar. Dette skal ses i sammenhæng med paragraf 2.5.2. (gl. 4.4.3) 

Info

2.5.4 § Det skal være muligt at udtrække en service version fra en HTTP snitflade. (gl. 4.4.4) 

Info

2.5.5 § Udstillede HTTP monitorerings snitflader skal opfylde formatet defineret i sektion 3.1 i RFC822, ECMA-404 (JSON) eller XML 1.0 (gl. 4.4.5) 

Derudover skal tidsangivelser overholder ISO-8601. Hvis servicen f.eks. afhænger af databasen, skal svaret afhænge af, om servicen faktisk kan udføre et succesfuldt SQL statement mod databasen.
Tilsvarende bør komponenter stille en separat service til rådighed for driftsleverandørens overvågning, som kan angive status på eventuelle afhængigheder, interne såvel som eksterne; blandt andet til brug for alarmering af driftsvagt og til præliminær test i produktion.
Komponenter kan desuden vælge at udstille en service til brug for diagnosticering og support; eksempelvis udførselstider og anden information, som driftleverandør kan vælge at stille til rådighed i forbindelse med fejlsøgning/optimering. 

Info

2.5.6 § Dokumentationen skal indeholde en beskrivelse af hvor monitorerings snitfladen kan findes samt hvilke andre snitflader, der måtte bruges i samme kontekst. (gl. 4.4.6) 

JMX snitflader til rapportering understøttes på platformen; specielt ifht. statistiske forhold kan dette være at foretrække.

Logning (gl 4.5)

Komponenter forventes at forholde sig til følgende typer af log:

  • SLA log: Foretages normalt gennem komponenten; NSP-Util.
  • Audit log: Afhængig af udbudte funktionalitet og opstillede krav. 
    • Applikationslog: Generel log efter behov pr. komponent.
    Info

    2.6.1 § Al logning på platformen skal være filbaseret. Logfiler centraliseres til en central log server af NSP infrastruktur services. (gl. 4.5.1)

    Info

    2.6.2  § Konfiguration af logningen skal ske gennem en log4j-kompatibel xml eller property-fil. Filen skal kunne ændres separat fra den binære komponent. (gl. 4.5.2)

    Info

    2.6.3  § Logkonfiguration skal kunne specificeres individuelt per komponent. Dette forventes at fremgå af den leverede dokumentation. (gl. 4.5.3)

    Info

    2.6.4  § Generelt skal logning overholde følgende: (gl. 4.5.4)

    • Logformat skal være tekstuelt og liniebaseret indeholdende en dato-tid for hver log-enhed.
    • Anvendte dato-tid-format skal overholde ISO-8601.
    • Logfilerne skal placeres i folderen log/ under Wildfly profilen.
    • Rotation skal kunne konfigureres baseret på størrelse.
    • Logfilerne skal ikke komprimeres.
    Info

    2.6.5 § Det foretrækkes at der logges i et format, som senere kan maskin-parses for at tilgodese log-inspektion på tværs af komponenterne samt, at dette så vidt muligt er dokumenteret.(gl. 4.5.5)

    Info

    2.6.6  § Til logning, hvor kalderens IP logges, skal HTTP headeren X-Forwarded-For bruges såfremt den er sat. (gl. 4.5.6)

    Info

    2.6.7  § Komponenter, der kalder andre komponenter på platformen, skal sætte headeren, X-Forwarded-For, i det omfang det skønnes relevant for forespørgelsen. (gl. 4.5.7)

    Hvis komponenter kalder andre komponenter, hvortil det ikke skønnes at være et viderestillingskald, så skal headeren, X-NSI-Original-Client-IP, i stedet benyttes.

    Info

    2.6.8  § Enkelte komponenters services skal opsætte logpunkter, der reflekterer komponentens funktionalitet. Disse logpunkter dækker SLA-logning for en komponent. (gl. 4.5.8)

    Logpunkterne skal bla. omfatte, webservices, schedulerede jobs, kald til andre services og ligende tasks.

    Info

    2.6.9  § SLA-logning skal overholde et bestemt format, som pt. dikteres af biblioteket NSP-Util. (gl. 4.5.9)

    NSP-Util indeholder en de’facto standard for omtalte logformat, og det anbefales at komponenter anvender biblioteket til SLA-logning.

    Info

    2.6.10  § Til hvert logpunkt høres der en entydig identifikation. Denne skal afstemmes med NSP-projektet. (gl. 4.5.10)

    Logpunkter bruges i høj grad til at etablere performance målinger på platformen som helhed, hvorfor det er vigtigt at disse dokumenteres, både hvilke der findes, men så vidt muligt også hvor stor en andel af komponentens funktionalitet, de dækker over.

    En anden målsætning med SLA log er også at kunne spore forespørgsler gennem systemet, hvorfor anvendte MessageId skal overvejes nøje. 

    Info

    2.6.11  § MessageId skal udfyldes ud fra modtagne DGWS forespørgelse såfremt det er muligt. Alternativt kan komponenten selv generere et, som skal være unikt. (gl. 4.5.12) 1 

    Info

    2.6.12 § Auditlog skal logges til filer med filnavne, der opfylder mønsteret: *-audit.log. (gl. 4.5.13)

    Det er dog ikke et krav at komponenter audit logger. Audit log indeholder ofte personhenførbare data, hvorfor det er vigtigt at dette kan adskilles fra øvrig log.

    Øvrige logfiler anses af drift som applikationslog, eller generel komponent log. Disse filer kan bruges af leverandør til debugging formål. Det skal bemærkes at logfilerne dog overvåges mht. fejl.

    Info

    2.6.13  § Komponenter skal anvende loglevels fornuftigt; der ses her på 4 inddelinger: DEBUG, som ikke bør være aktiveret i produktion, INFO, som anvendes til sparsom logning om relevant information, WARN, som bør anvendes til at gøre opmærksom på en uheldig situation og sidst, ERROR, som udelukkende skal bruges når der indtræffer en fejl, som menes skal behandles med aktiv indvirken af driften. (gl. 4.5.14)

    Fejlsituationer vil blive behandlet af driftsleverandøren, såfremt dette kan lade sig gøre, og at dette er beskrevet i medfølgende dokumentationen. 

    Info

    2.6.14  § Applikationslog bør ikke indeholde personhenførbare oplysninger. (gl. 4.5.14)

    Info

    2.6.15  § Applikationsspecifikke logs skal dokumenteres i forhold til formål, placering og indhold. Logformater for nye komponenter skal være dokumenteret i forhold til deres forretningsmæssige indhold, herunder om et felt er obligatorisk eller valgfrit, og de mulige feltværdier.

    Persistens (gl 4.6)

    Platformen stiller pt. en ikke-clustered database til rådighed for persistens.

    Info

    2.7.1  § Komponenter kan ikke forvente at kunne anvende databasen i scenarier med samtidig dataintegritet på tværs af søjler. (gl. 4.6.1)

    Platformen tilbyder pt. ikke clustered persistens. Persistens tilbydes kun lokalt per NSP søjle. På NSP’ens centrale databaseplatform er situationen dog anderledes, da denne leverer data til stamdata databasen, som distribueres til alle NSP’er. 

    Info

    2.7.2  § Komponenter skal levere opdateringsfunktionalitet til databaseskema såfremt data skal bevares ved opdatering. (gl. 4.6.2)

    Info

    2.7.3  § Der tages ikke backup af databaserne udover på den centrale NSP databaseplatform. (gl. 4.6.3)

    Databaseplatformen er, så vidt mulig, sat op med default opsætning, hvilket der skal tages hensyn til. Specielt skal der tages hensyn til default opsætning af anvendte tabeller mht. lokalisering. Denne opsætning kan, hvis det ønskes ændres, leveres som individuelle parametre under skemaoprettelse. Mht. sortering og danske bogstaver er collate og charset vigtige – default er dog hhv. latin1_swedish_ci og latin1.

    Info

    2.7.4  § UTF8 skal anvendes som codepage med mindre andet er aftalt.

    Komponentinteraktion (gl 5.2)

    Info

    2.8.1  § En komponents ressourcekrav skal være kendt og videre gives til NSP platformen. (gl. 5.2.1) 

    Se. afsnit 7. Krav til dokumentation.

    Info

    2.8.2  § Hvis en komponent kalder en anden service i systemet, skal det overvejes hvilke attributer der skal medsendes. Der skal etableres sporbarhed af både forespørgsel og klient, dvs. omtalte MessageId skal sættes og enten X-Forwarded-For eller X-NSI-Original-Client-IP skal sættes. (gl. 5.2.2). Oplysningerne skal logges i SLA-loggen for komponenten.

    Webservices (gl. 5.3)

    En udstillet webservice snitflade skal understøtte UTF-8 jvf. DGWS.

    Info

    2.9.1 § En udstillet webservice snitflade skal kunne håndtere forespørgelser med og uden BOM. (gl. 5.3.1)

    Info

    2.9.2 § WSDL kontrakter samt tilhørende artefakter for udbudte services skal kunne hentes via HTTP. Dokumentationen skal tilmed angive placeringen heraf. (gl. 5.2.2)

    Brugere af services kan herved nemt generere klienter.

    Info

    2.9.3 § Eksterne kald til webservices som udstilles på NSP platformen, skal altid kaldes gennem DCC (Decoupeling Component).

    DCC (gl 5.4)

    DCC tilbyder en fælles indgang til NSP services baseret på SOAP action; forespørgelser viderestilles til det rette service i det aktuelle miljø baseret på den SOAP-Action, der specificeres i forespørgelsen.

    DCC konfigurationen styres centralt og kræver at services udstiller en speciel snitflade hertil.

    Info

    2.10.1 § En service, der udstilles gennem DCC, skal have en DKS snitflade. Dennes placering skal være dokumenteret. (gl. 5.4.1)

    En DKS, DCC Konfiguration Service, er specificeret her.

    Særlige komponentspecifikationer

    Implementering af Stamdata import moduler skal anvende modulerne; SDM-Core, SDM-Parent.

    Fejlsvar

    Svar fra udstillede DGWS services skal følge standarden og skal være til nytte for både anvendere og i supportøjemed.

    Info

    2.12.1 § Fejlbeskeder skal være på dansk (gl. 5.5.1)

    Krav til udviklingsværktøjer og metode

    Værktøjer

    Info

    3.1.1  § Apache Maven skal anvendes til byg af komponenter til NSP platformen. (gl. 3.1.1)

    Info

    3.1.2  § Generelle retningslinjer angående brug af Maven skal være overholdt. (gl. 3.1.2)

    Dette er f.eks. vigtigt mht. install-fasen, hvis bygget ønskes brugt i andre sammenhænge, hvor maven artifakterne kan genbruges.

    Info

    3.1.3  § Build scripts må ikke skulle ændres for at kunne bygge til NSP, dog kan parameterisering benyttes. (gl. 3.1.3)

    Info

    3.1.4  § Leveret dokumentation skal beskrive anvendelse af de brugte værktøjer samt angive specifikke versioner deraf. (gl. 3.1.7)

    Nexus (gl 3.4)

    Projektet stiller et maven repository til rådighed for leverandører. Detaljer heromkring findes på NSP Nexus vejledning.

    Info

    3.2.1  § Leverancer skal begrænse sig til at bruge projektets maven repository. (gl 3.4.1)

    I repositoriet findes NSP projektets bibliotekter samt andre afhængigheder. Det vil desuden være muligt at udvide repositoriet med yderligere artefakter.

    Byg

    Komponenter til NSP platformen skal kunne bygges og testes på en NSP platform. Til det formål stiller projektet NSP til rådighed i et udviklingsmiljø, som også anvendes til modtagelse af leverancer og derfor bør anvendes af komponentleverandørne til kvalitetssikring før leverance.

    Info

    3.3.1 § Komponenter skal kunne bygges, testes og afvikles på den af driftleverandøren leverede NSP. Byggeværktøjer må dog installeres, da disse ikke følger med og ikke vil være til stede i produktion. (gl. 3.0.1)

    Da NSP versionen kan ændre sig efter en leverance, bør man stræbe efter at benytte seneste version på leverancetidspunktet. Det påhviler NSP projektet at informere komponentleverandører om seneste NSP version.

    for NSP platformen.

    Info

    2.5.3 § Et svar på 200 vil i loadbalanceren afgøre om forespørgelser kan routes til pågældende service. Det er derfor vigtig at alle afhængigheder, en service måtte have, indgår i dette svar. Dette skal ses i sammenhæng med paragraf 2.5.2.

    Info

    2.5.4 § Det skal være muligt at udtrække en service version fra en HTTP snitflade.

    Info

    2.5.5 § Udstillede HTTP monitorerings snitflader skal opfylde formatet defineret i sektion 3.1 i RFC822, ECMA-404 (JSON) eller XML 1.0

    Derudover skal tidsangivelser overholder ISO-8601. Hvis servicen f.eks. afhænger af databasen, skal svaret afhænge af, om servicen faktisk kan udføre et succesfuldt SQL statement mod databasen.
    Tilsvarende bør komponenter stille en separat service til rådighed for driftsleverandørens overvågning, som kan angive status på eventuelle afhængigheder, interne såvel som eksterne; blandt andet til brug for alarmering af driftsvagt og til præliminær test i produktion.
    Komponenter kan desuden vælge at udstille en service til brug for diagnosticering og support; eksempelvis udførselstider og anden information, som driftleverandør kan vælge at stille til rådighed i forbindelse med fejlsøgning/optimering. 

    Info

    2.5.6 § Dokumentationen skal indeholde en beskrivelse af hvor monitorerings snitfladen kan findes samt hvilke andre snitflader, der måtte bruges i samme kontekst.

    JMX snitflader til rapportering understøttes på platformen; specielt ifht. statistiske forhold kan dette være at foretrække.

    Logning

    Komponenter forventes at forholde sig til følgende typer af log:

    • SLA log: Foretages normalt gennem komponenten; NSP-Util.
    • Audit log: Afhængig af udbudte funktionalitet og opstillede krav. 
    • Applikationslog: Generel log efter behov pr. komponent.

    Info

    2.6.1 § Al logning på platformen skal være filbaseret. Logfiler centraliseres til en central log server af NSP infrastruktur services.

    Info

    2.6.2 § Konfiguration af logningen skal ske gennem en log4j-kompatibel xml eller property-fil. Filen skal kunne ændres separat fra den binære komponent.

    Info

    2.6.3 § Logkonfiguration skal kunne specificeres individuelt per komponent. Dette forventes at fremgå af den leverede dokumentation.

    Info

    2.6.4 § Generelt skal logning overholde følgende:

    • Logformat skal være tekstuelt og liniebaseret indeholdende en dato-tid for hver log-enhed.
    • Anvendte dato-tid-format skal overholde ISO-8601.
    • Logfilerne skal placeres i folderen log/ under Wildfly profilen.
    • Rotation skal kunne konfigureres baseret på størrelse.
    • Logfilerne skal ikke komprimeres.
    Info

    2.6.5 § Det foretrækkes at der logges i et format, som senere kan maskin-parses for at tilgodese log-inspektion på tværs af komponenterne samt, at dette så vidt muligt er dokumenteret.

    Info

    2.6.6 § Til logning, hvor kalderens IP logges, skal HTTP headeren X-Forwarded-For bruges såfremt den er sat.

    Info

    2.6.7 § Komponenter, der kalder andre komponenter på platformen, skal sætte headeren, X-Forwarded-For, i det omfang det skønnes relevant for forespørgelsen.

    Hvis komponenter kalder andre komponenter, hvortil det ikke skønnes at være et viderestillingskald, så skal headeren, X-NSI-Original-Client-IP, i stedet benyttes.

    Info

    2.6.8 § Enkelte komponenters services skal opsætte logpunkter, der reflekterer komponentens funktionalitet. Disse logpunkter dækker SLA-logning for en komponent.

    Logpunkterne skal bla. omfatte, webservices, schedulerede jobs, kald til andre services og ligende tasks.

    Info

    2.6.9 § SLA-logning skal overholde et bestemt format, som pt. dikteres af biblioteket NSP-Util.

    NSP-Util indeholder en de’facto standard for omtalte logformat, og det anbefales at komponenter anvender biblioteket til SLA-logning.

    Info

    2.6.10 § Til hvert logpunkt høres der en entydig identifikation. Denne skal afstemmes med NSP-projektet.

    Logpunkter bruges i høj grad til at etablere performance målinger på platformen som helhed, hvorfor det er vigtigt at disse dokumenteres, både hvilke der findes, men så vidt muligt også hvor stor en andel af komponentens funktionalitet, de dækker over.

    En anden målsætning med SLA log er også at kunne spore forespørgsler gennem systemet, hvorfor anvendte MessageId skal overvejes nøje. 

    Info

    2.6.11 § MessageId skal udfyldes ud fra modtagne DGWS forespørgelse såfremt det er muligt. Alternativt kan komponenten selv generere et, som skal være unikt.

    I situationer hvor forespørgsler ikke er hverken DGWS eller IDWS (f.eks. REST baserede snitflader) skal disse også indeholde et unikt ID (UUID), som skal hele vejen med ned i applikationsstakken.

    Alle komponenter skal overholde gældende lovgivning ang. audit logning. NSP har et fælles framework som skal anvendes til at producere struktureret auditloging.

    Info

    2.6.12 § Auditlog skal foretages gennem NSP Audit API-'et

    Retningslinier for auditlogning findes i dokumentet Krav til Auditlogning

    Øvrige logfiler anses af drift som applikationslog, eller generel komponent log. Disse filer kan bruges af leverandør til debugging formål. Det skal bemærkes at logfilerne dog overvåges mht. fejl.

    Info

    2.6.13 § Komponenter skal anvende loglevels fornuftigt; der ses her på 4 inddelinger: DEBUG, som ikke bør være aktiveret i produktion, INFO, som anvendes til sparsom logning om relevant information, WARN, som bør anvendes til at gøre opmærksom på en uheldig situation og sidst, ERROR, som udelukkende skal bruges når der indtræffer en fejl, som menes skal behandles med aktiv indvirken af driften.

    Fejlsituationer vil blive behandlet af driftsleverandøren, såfremt dette kan lade sig gøre, og at dette er beskrevet i medfølgende dokumentationen. 

    Info

    2.6.14 § Applikationslog må ikke indeholde personhenførbare oplysninger.

    Info

    2.6.15 § Applikationsspecifikke logs skal dokumenteres i forhold til formål, placering og indhold. Logformater for nye komponenter skal være dokumenteret i forhold til deres forretningsmæssige indhold, herunder om et felt er obligatorisk eller valgfrit, og de mulige feltværdier.

    Info

    2.6.16 § Hvis der sker en uventet fejl i applikationen (Exception) skal denne logges sammen med MessageId eller anden nøgle der kan bruges til at finde frem til den relevante kaldskontekst.

    MessageId eller lignende skal f.eks. kunne bruges til at finde frem til Access- og Audit-log som er produceret af platformen. Logningen bør også indeholde alt relevant ikke-personfølsom information omkring den handling der var i gang da fejlen opstod. Dette skal lette arbejdet med at identificere og mitigere fejl i produktion.


    Persistens

    Platformen stiller en ikke-clustered database til rådighed for persistens på NSP noderne (dNSP og cNSP) samt en fuld clusteret database på NSP Backoffice. Derudover stilles en streaming platform (Kafka) til rådighed både lokalt på hver node og som en clustered løsning på backoffice. Data skrevet til databasen på backoffice kan distribueres til databaserne på NSP noderne, omvendt kan data skrevet til streaming platformen på NSP noderne samles i backoffice.

    Info

    2.7.1 § Komponenter kan ikke forvente at kunne anvende databasen på NSP noderne i scenarier med samtidig dataintegritet på tværs af søjler.

    Platformen tilbyder pt. ikke clustered persistens på NSP noderne. Persistens tilbydes kun lokalt per NSP søjle. På NSP Backoffice databaseplatform er situationen dog anderledes, da denne leverer data til stamdata databasen, som distribueres til alle NSP’er. 

    Info

    2.7.2 § Komponenter skal levere opdateringsfunktionalitet til databaseskema såfremt data skal bevares ved opdatering.

    Info

    2.7.3 § Der tages ikke backup af databaserne på NSP noderne, kun på NSP Backoffice.

    Databaseplatformen er, så vidt mulig, sat op med default opsætning, hvilket der skal tages hensyn til. Specielt skal der tages hensyn til default opsætning af anvendte tabeller mht. lokalisering. Denne opsætning kan, hvis det ønskes ændres, leveres som individuelle parametre under skemaoprettelse.

    Info

    2.7.4 § UTF8 skal anvendes som codepage med mindre andet er aftalt.

    Mht. sortering og danske bogstaver er collate og charset vigtige – default er dog hhv. latin1_swedish_ci og latin1, tabellerne skal derfor defineres med følgende streng ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin

    Streaming platformen er primært sat op for at tilbyde samling af data fra NSP noderne på NSP Backoffice hvor dette er nødvendigt. (Den modsatte vej tilbydes med databasereplikering)

    Info

    2.7.5 § Brug af streaming platformen må kun ske gennem NSP Kafka Clients

    Brug af streaming platformen kræver der er lavet et analysedokument der præcis beskriver anvendelsen af topics, partitions, replication factor mv. samt en realistisk prognose for datamængder. Se Den Gode Brug af Kafka for yderligere detaljer.

    Info

    2.7.5 § Brug af streaming platformen kræver specifik aftale med NSP.

    Databasetabeller og feltnavne skal være sigende og angives med bogstaverne fra A-Z, 0-9 og _. Danske bogstaver (æøå) er således ikke tilladte.

    Info

    2.7.6 § Tabel og feltnavne i databasen skal være A-Z og 0-9. Underscore _ er ligeledes tilladt.

    Komponentinteraktion

    Info

    2.8.1 § En komponents ressourcekrav skal være kendt og videre gives til NSP platformen.

    Se. afsnit 7. Krav til dokumentation.

    Info

    2.8.2 § Hvis en komponent kalder en anden service i systemet, skal det overvejes hvilke attributer der skal medsendes. Der skal etableres sporbarhed af både forespørgsel og klient, dvs. omtalte MessageId skal sættes og enten X-Forwarded-For eller X-NSI-Original-Client-IP skal sættes. Oplysningerne skal logges i SLA-loggen for komponenten.

    Webservices

    En udstillet webservice snitflade skal understøtte UTF-8 jvf. DGWS. For krav til REST services, se Husregler for REST services.

    Info

    2.9.1 § En udstillet webservice snitflade skal kunne håndtere forespørgelser med og uden BOM (gælder ikke JSON snitflader)

    Info

    2.9.2 § WSDL kontrakter og OpenAPI kontrakter samt tilhørende artefakter for udbudte services skal kunne hentes via HTTP. Dokumentationen skal tilmed angive placeringen heraf.

    Brugere af services kan herved nemt generere klienter.


    Info

    2.9.2.1 § Udstiller en service WSDL-kontrakt(er) og/eller OpenAPI-kontrakt(er) skal andre NSP-komponenter/klienter, der anvender disse, bruge kontrakterne til at generere klienter til kald imod servicen.

    Se afsnit "2.2. Anvendelse af kodebiblioteker" ang. hvilke værktøjer der vælges til kodegenerering. 


    Info

    2.9.2.2 § Udstiller en service WSDL-kontrakt(er) og/eller OpenAPI-kontrakt(er) skal dens egen integrationstest også benytte en genereret klient.

    Info

    2.9.2.3 § Alle operationer i WSDL-kontrakterne og/eller OpenAPI-kontrakterne skal være implementerede. Det er ikke tilladt at have operationer der altid returnerer en fejl eller et tomt/ugyldigt svar.

    Info

    2.9.3 § Eksterne kald til webservices som udstilles på NSP platformen, skal altid kaldes gennem DCC (Decoupeling Component).

    I forhold til konstruktionen af xml skemaer og wsdl-filer, skal der, såfremt der anvendes domænenavne i namespaces, anvendes det SDS specifikke dk.nspop 

    Info

    2.9.4 § Domænenavne i namespaces prefikses med dk.nspop

    Namespaces skal yderligere være datoversionerede.

    Info

    2.9.5 § Namespaces skal være versionerede efter dato

     Et eksempel på en URL version kunne være https://nspop.dk/nsp/<service-navn>/2020/02/24

    Info

    2.9.6 § En SOAP service på NSP skal udstille en WSDL uden nogle sikkerhedsprotokolspecifikke headers på servicens endpoint hvis der medsendes query parameteren "wsdl"

    Hvis komponenten udstiller en SOAP service på pathen /komponent/service skal den protokoluafhængige WSDL returneres hvis anvenderen laver et HTTP GET kald mod /komponent/service?wsdl eller /komponent/service?wsdl=1. Dette matcher best practice indefor SOAP verdenen.

    Info

    2.9.7 § En SOAP service på NSP skal udstille sikkerhedsprotokolspecifikke WSDL'er på servicens endpoint hvis der medsendes query parameteren "wsdl" og "protocol"

    Hvis komponenten udstiller en DGWS service på pathen /komponent/service skal den sikkerhedsprotokolspecifikke WSDL returneres, hvis anvenderen laver et HTTP GET kald mod /komponent/service?wsdl&protocol=dgws eller /komponent/service?wsdl=1&protocol=dgws.

    Ligeledes for en OIO-IDWS service udstillet på pathen /komponent/service skal den sikkerhedsprotokolspecifikke WSDL returneres, hvis man laver et HTTP GET kald mod /komponent/service?wsdl&protocol=oioidws eller /komponent/service?wsdl=1&protocol=oioidws

    Hvis servicen udstilles med JaxWS eller lign. skal dette opnåes ved brug af et ServletFilter der redirecter til en specifik Servlet hvis de omtalte query parametre er med i kaldet.

    DCC

    DCC tilbyder en fælles indgang til NSP services baseret på SOAP action; forespørgelser viderestilles til det rette service i det aktuelle miljø baseret på den SOAP-Action, der specificeres i forespørgelsen.

    DCC konfigurationen styres centralt og kræver at services udstiller en speciel snitflade hertil.

    Info

    2.10.1 § En service, der udstilles gennem DCC, skal have en DKS snitflade. Dennes placering skal være dokumenteret.

    En DKS, DCC Konfiguration Service, er specificeret her.

    Facader (iNSP) udstilles ikke igennem DCC.


    Da vi jf. husregel 2.9.3 har krav om at eksterne webservices skal kunne kaldes via DCC, skal anvenderguiden tydeligt instruere i hvordan dette lader sig gøre:

    Info

    2.10.2 § En service, der udstilles gennem DCC, skal i anvenderguiden dokumentere hvordan servicen kaldes via DCC. SOAP-action skal fremgå, evt. path og ServiceIdentifier skal fremgå, hvis de anvendes.


    Særlige komponentspecifikationer

    Implementering af Stamdata import moduler skal anvende modulerne; SDM-Core, SDM-Parent.

    Fejlsvar

    Svar fra udstillede DGWS services skal følge standarden og skal være til nytte for både anvendere og i supportøjemed.

    Info

    2.12.1 § Fejlbeskeder skal være på dansk


    Webservices må, ved uhåndterede exceptions i servletten, ikke svare generisk med denne exception og "fejl 500". Der skal som minimum være en central håndtering i Servlet'en, således at fejl-situationen er mere sigende for anvenderen.

    Info

    2.12.2 § En webservice må i fejlsituationer ikke svare med en uhåndteret exception. 


    Kodestruktur

    For at sikre en ensartet kodestruktur skal følgende husregler så vidt muligt overholdes.

    Info

    2.13.1 § En NSP komponent skal i det omfang det giver mening opsplittes i flere Maven moduler med tydelige ansvarsområder

    Alt efter størrelsen af en komponent skal det vurderes (og dokumenteres i Guide til Udviklere) om komponenten består af nogle logiske moduler med hvert deres ansvar og veldefineret snitflade. Det kan f.eks være et modul der indeholder anvendelsen af NSP Kafka eller en særlig specifik del af forretningslogikken. Modulerne skal dokumenteres i Design og Arkitektur dokumentet.

    Info

    2.13.2 § Java klasser i Maven modulerne skal være placeret i fornuftige pakker som alle hører under dk.nsp.<project>.

    Følgende standard for pakker skal anvendes:

    Code Block
    dk.nsp.<project>.ws          - Webservice protokollag
dk.nsp.<project>.ws.resource - Restfull ressourcer.
dk.nsp.<project>.ws.filter   - Servlet filters.
dk.nsp.<project>.service     - Forretningslogik
dk.nsp.<project>.log         - Logning
dk.nsp.<project>.db          - Database integration og DAO'er
dk.nsp.<project>.kafka       - NSP Kafka integration

    Sikkerhedstoken-principper

    Afsnittet omhandler brug og genbrug af sikkerhedstokens på NSP.

    Info

    2.14.1 § Services, der benytter andre interne NSP forretningsservices, skal videresende de indkommende sikkerhedstokens i de videre kald.

    Såldes skal fx. et medarbejder idkort (DGWS niveau 4) medsendes til de forretningsservices, der af servicen anvendes til at generere det ønskede forretningsmæssige svar. Bemærk at der i denne sammenhæng også kan være behov for yderligere whitelisting i de bagvedliggende forretningsservices.

    Såfremt der er tale om støtteservices, som Minlog, Minspærring (verifikation) eller Behandlingsrelationsservicen skal der anvendes et systemcertifikat til disse kald.

    Info

    2.14.2 § Services, der benytter interne NSP støtteservices, skal kalde disse med et systemtoken, såfremt der for servicen er krav om sikkerhedstokens.

    Den udviklede service skal derfor have udstedt et systemcertifikat specifikt til kald af disse støtteservices.

    Baggrundsjob

    Nogle NSP komponenter kan have behov for at få udført periodiske baggrundsjob. Dette afsnit indeholder de særlige husregler, der gælder for disse job.

    Info

    2.15.1 § Et Baggrundsjob på NSP består af en Servlet, der udstiller de forskellige operationer på hver deres unikke path.

    Hver logisk operation i et baggrundsjob skal kunne opdeles i flere delmængder, der til sammen får løst den samlede opgave, da der jf. følgende paragraf er et begrænset tidsrum til eksekvering ad gangen. Et eksempel herpå er den logiske operation "Slet alle data associeret til patienter, der er døde for mere end ét år siden", hvor en delmængde vil være data tilhørende et nærmere begrænset antal af disse patienter.

    Baggrundsjobbet skal understøtte, at der aktiveres et vilkårligt antal samtidige kørsler af delmængderne, uden at dette giver anledning til fejl.

    Disse samtidige kørsler kan forekomme på den samme instance eller fordelt på flere instancer af komponenten. Der skal derfor indbygges synkronisering og/eller idempotens i udførslen af delmængden af opgaven.

    Info

    2.15.2 § Aktivering af en delmængde sker via et HTTP GET kald til baggrundsjobbets Servlet.

    Hver aktivering af jobbet skal udføre sin delmængde af den samlede opgave og må ikke overstige 20 sekunder i udførselstid.

    Selve aktiveringen foregår fra en specifik server i NSP driftsmiljøerne og styres af driftsorganisationen - f.eks. via Cron/Curl kombination.

    Hvis komponenten er placeret på NSP Backoffice miljøet, er det muligt at anvende en MariaDB database eller et Kafka Cluster til at holde styr på hvor langt jobbet er nået samt til at fordele delmængderne mellem forskellige samtidige kørsler.

    En aktivering af baggrundsjobbet må kun returnere HTTP status 200 uden en HTTP Body. Detaljer om aktiveringen samt eventuelle fejl skal i stedet skrives til logfilerne.

    Info

    2.15.3 § Et NSP Baggrundjob skal pakkes i egen container og være inkluderet i Docker Compose setupet i releaset.

    Jobbet skal anvende det almindelige NSP Docker Image.

    Info

    2.15.4 § Hver aktivering af baggrundsjobbet skal logge hvor langt jobbet er kommet, og hvor langt der er igen.

    For at sikre simpel parsning bør en log linie indeholde key=value par med mellemrum omkring f.eks:
    "Cleanup iteration deleted=42 remaining=119 done."

    Info

    2.15.5 § Baggrundsjobbet skal have sin egen snitflade til monitorering af status.

    Snitfladen skal overholde alle reglerne i afsnittet "2.5. Snitflade til monitorering".


    Krav til udviklingsværktøjer og metode

    Værktøjer

    Info

    3.1.1 § Apache Maven på NSP Docker Build image skal anvendes til byg af komponenter til NSP platformen.

    Se NSP Continuous Integration & Delivery for en detaljeret gennemgang af hvordan NSP komponenter bygges. NSP Docker Build image kan anskaffes med følgende docker kommando:

    Code Block
    docker pull registry.nspop.dk/tools/nspbuilder:jdk8
    Info

    3.1.2 § Generelle retningslinjer angående brug af Maven skal være overholdt.

    Dette er f.eks. vigtigt mht. install-fasen, hvis bygget ønskes brugt i andre sammenhænge, hvor maven artifakterne kan genbruges.

    Info

    3.1.3 § Build scripts må ikke skulle ændres for at kunne bygge til NSP, dog kan parameterisering benyttes.

    Info

    3.1.4 § Leveret dokumentation skal beskrive anvendelse af de brugte værktøjer samt angive specifikke versioner deraf.

    Nexus

    Projektet stiller et maven repository til rådighed for leverandører. Detaljer heromkring findes på NSP Nexus vejledning.

    Info

    3.2.1 § Leverancer skal begrænse sig til at bruge projektets maven repository.

    I repositoriet findes NSP projektets bibliotekter samt andre afhængigheder. Det vil desuden være muligt at udvide repositoriet med yderligere artefakter.

    Byg

    Komponenter til NSP platformen skal kunne bygges og testes på en NSP platform. Til det formål stiller NSP et Docker image til rådighed, som også anvendes til modtagelse af leverancer og deployment i NSP miljøerne.

    Info

    3.3.1 § Komponenter skal kunne testes og afvikles på det af driftleverandøren leverede NSP image.

    Da NSP versionen kan ændre sig efter en leverance, bør man stræbe efter at benytte seneste version på leverancetidspunktet. Det påhviler NSP projektet at informere komponentleverandører om seneste NSP version.

    Continuous integration

    Komponentleverandøren skal anvende NSP's Continuous integration and Delivery miljø og tilhørende Docker images. Dette vil ligeledes blive brugt ved modtagelse af komponentleverancer.

    Info

    3.4.1 § Komponenter skal kunne bygges vha. en automatiseret proces. Afhængigheder skal enten kunne angives som en konfiguration til byggeprocessen eller komponentleverancen skal understøtte opløsning af disse uden intervention.

    Info

    3.4.2 § Bygge scripts skal være udformet således at byg af komponentleverancer er idempotent

    Info

    3.4.3 § Unittest eller andre komponentspecifikke test skal være inkluderet i denne proces

    Javadoc

    Komponentleverandøren skal dokumentere interfaces og hver javaklasse i koden med javadoc. Klassernes overordnede ansvar/formål beskrives. Interfaces bør have beskrevet de enkelte metoder.

    Info

    3.5.1 § Metoderne på Javainterfaces skal dokumenteres med javadoc i koden

    Info

    3.5.2 § Javaklasser skal dokumenteres med javadoc i koden

    Udviklingsmetodik

    Info

    3.6.1 § Vedligehold af NSP komponenter skal følge den udviklingsmetodik som SDS har valgt

    Udviklingsmetodikken er beskrevet i yderligere detaljer her

    Krav til test metode og værktøjer

    Unit test – JUnit

    Info

    4.1.1 § Test af komponenter skal kunne udføres med , seneste version af JUnit (anbefalet).

    Afvikling af unittests er en del af NSP bygge- og releaseprocessen, og skal enten indgå direkte i bygget, eller kunne udføres separat efter anvisning i medfølgende dokumentation.

    Code coverage – overordnet

    Der er fra SDS’s side sat et mål for code coverage for leverancer. Dette tal kan variere afhængigt af hvilket værktøj og opsætning, der benyttes.

    Info

    4.2.1 § Code coverage målet er 80%. NSP Projektet kontrollere graden af code coverage ved modtagelse.

    Desuden kan dele af leverancer fravælges at blive dækket; f.eks. fordi en del kode er genereret. I medfølgende dokumentation, under beskrivelse af genereringen af code coverage, bør dette være beskrevet.

    Performance test - JMeter

    Info

    4.3.1 § Performance test af komponenter skal foretages med NSP Performance Framework

    Krav ifm performancetest er specificeret i dokumentet Performancekrav

    Krav til leverance og installation

    Leverance generelt

    En leverance består af komplet kildekode for komponenten/komponenter, konfigurationsfiler, Maven (POM), Index og Database skema ændringer, samt dokumentation.

    Krav omkring dokumentation fremgår af NSP projektets dokumentationskrav.

    Info

    5.1.1 § NSP projektet har til hensigt at offentliggøre kildekoden. Derfor skal hensyn desangående beskrives. Dette vil imødekommes på offentliggørelsestidspunktet.

    Licens

    Info

    5.2.1 § Kildekoden skal være udstyret med MIT licens. Den eksakte ordlyd af denne kan erhverves hos SDS.

    En ikke autoritativ udgave af headeren kan findes under § 9.1

    Subversion

    Info

    5.3.1 § Kildekode samt dokumentation skal leveres til et subversion repository på http://svn.nspop.dk

    NSP repositories benyttes jvf. normale subversion konventioner, se iøvrigt NSP SVN anvendelse.

    Info

    5.3.2 § Komponenter skal placeres i Components repositoriet og fælles biblioteker skal placeres i Libraries repositoriet.

    NSP repositories udstilles offentligt med læseadgang, inklusiv "commit" kommentarer.

    Info

    5.3.3 § Alle manuelle commits skal ske med reference til et specifikt Jira issue

    Commit-kommentaren skal starte med Jira Key for det issue som er årsagen til ændringen i koden. Dette kan f.eks. være på formen "SDS-NNNN" eller "PROJEKTX-NNNN"

    Info

    5.3.4 § Snitfladeændringer på en service skal som minimum give anledning til en ændring af minor-versionen på komponenten.

    NSP komponenter der tagges som <major.minor.micro>, skal ved snitfladeændringer have ændret minor-version.

    Tests

    Testdokumentation

    Info

    5.4.1 § Den leverede dokumentation skal beskrive, hvordan de forskellige typer af tests skal udføres. Her refereres i særdeleshed til følgende typer:

    • Unit tests, som udføres under byg.
    • Integrationstests, som udføres mod den deployerede komponent.

    Som minimum vil de blive brugt på følgende måder: unit-tests til at generere code coverage information, og integrationstests til at verificere korrekt deployeret komponent. 

    Testspecifikationer

    Info

    5.4.2 § Leverancen skal indeholde unit tests, der bruges som ovenfor nævnt.

    Info

    5.4.3 § Leverancen skal indeholde integrationstest, der bruges som ovenfor nævnt.

    Info

    5.4.4 § En integrationstest skal kunne køres flere gange uden manuelle ændringer i konfiguration eller datagrundlag

    Derudover må leverancen indeholde andre former for tests, så som performance- og endurance tests. Disse vil ligeledes indgå i kvalitetssikringen af releaset så vidt det er muligt at gentage disse. Derfor er det vigtigt at udførslen af disse tests er dokumenteret.

    Info

    5.4.5 § Unittests skal være uafhængige af eksterne services.

    Database og div. snitflader skal under unittests mockes eller holdes in-memory, således der ikke er krav om eksterne opstillede databaser. For databaseanvendelse kan H2 anvendes.

    Info

    5.4.6 § De funktionelle tests skal følge kravene i dokumentet "Krav til projekternes funktionelle test på NSP"

    Installation

    Komponenterne skal deployes i et miljø med 2 søjler med henholdsvis load-balancere, app-servere og database-servere, i alt 6 instanser, som enten sættes op i regionerne eller på central lokation, dog altid forbundet til sundhedsdatanettet. Komponenterne bør være forberedt på de krav det måtte medføre.

    Info

    5.5.1 § NSP komponenter har kun adgang til services udstillet på sundhedsdatanettet, og iNSP/Facade komponenter har kun adgang til NSP backend. Det skal specielt bemærkes, at der kun er begrænset adgang til certifikatinfrastrukturen: HTTP adgang til CRL og krydscertifikat er muligt på normal vis. Desuden udstilles RID/CPR tjenesten.

    Info

    5.5.2 § Der skal kunne opsættes timeouts på kald til eksterne services. Komponenter skal endvidere behandle timeout forventelig overfor klienten/klientsystemet.

    Sagshåndtering

    JIRA systemet anvendes til håndtering af sager der omhandler komponent-releases, fejlrettelser, ny funktionalitet eller andre opgaver relateret til komponenter leveret til NSP-projektet. Se NSP projektets instruktion i brug af på NSP sagshåndtering.

    Info

    5.6.1 § Henvendelser vedrørende forhold omkring releases, der ikke kan spores tilbage til en sag i JIRA, vil blive afvist.

    Info

    5.6.2 § En sag i JIRA bør begrænses til at omhandlet én opgave. Dette gælder både når en sag startes og senere i forløbet.

    Krav til driftsmæssige forhold

    Afhængigheder


    Info

    6.1.1 § Komponenter skal kunne starte op (deploye), selvom deres afhængigheder ikke er tilgængelige.

    Info

    6.1.2 § Komponenter skal logge en ERROR eller WARN fejltype såfremt de driftsmæssige forudsætninger ikke er opfyldt.

    Hvis en komponent f.eks. er afhængig af certifikater placeret i filsystemet, skal komponenten verificere at disse tilgængelige .

    Udløb af certifikater skal checkes jvnf ovenstående.

    Info

    6.2.3 § Komponenter skal desuden være i stand til at genoprette deres tilstand, når afhængighederne igen er tilgængelige.

    En manglende afhængighed kan f.eks. være forbindelsen til databasen. Når databaseforbindelsen igen kan etableres, skal komponenter være i stand til at bemærke dette og genforbinde.

    Krav til dokumentation

    Gennerelle krav til dokumentation er beskrevet grundigt her.

    Dokumentation af værktøjer

    Info

    7.1.1 § Leverede dokumentation skal beskrive anvendelse af de brugte værktøjer samt angive specifikke versioner deraf.

    Test dokumentation

    Info

    7.2.1 § Den leverede dokumentation skal beskrive, hvordan de forskellige typer af tests skal udføres. Her refereres i særdeleshed til følgende typer:

    • Unit tests, som udføres under byg.
    • Integrationstests, som udføres mod den deployerede komponent.

    SLA logpunkter

    Info

    7.3.1 § Identifikationen samt beskrivelse af SLA-logpunkter skal indskrives i dokumentationen.

    Ressourceforbrug

    Info

    7.4.1 § En komponents ressource krav skal fremgå af dokumentationen.

    Krav til ændringer

    Post-leverance ændringer

    NSP projektet kan forke/ændre en komponent efter leverance for at tilgodese et driftsaspekt eller rette op på en mindre fejl. Ændringer af binære artefakter er et eksempel på en mindre ændring.

    Info

    8.1.1 § Hvis NSP projektet har foretaget ændringer i en komponents funktionalitet, så skal disse eller tilsvarende ændringer som minimum inkluderes i næste release.

    Processen vil generelt være beskrevet af følgende: NSP projektet vil enten i samråd med komponentleverandøren eller selvstændigt foretage en ændring i en komponent til et givet release. Denne ændring forventes herefter at være inkluderet i komponenten, enten i samme form eller implementeret på anden vis. Ændringerne vil være tilgængelige for leverandøren.

    Generelt vil der stræbes mod ikke at foretage større ændringer uden at leverandøren er inddraget.

    Ændringslog

    Dato:        

    Version:                         

    Tilføjet:                    

    Ændret:                            

    Fjernet:                   

    29-08-20141.5


    05-10-20151.6

    Maven 2

    Ant

    06-01-2016

    1.7

    afsnit 3.3.4



    14-01-20161.7i afsnit 3.3 afsluttende bemærkning omkring platformsapplikationer

    13-05-20161.8
    		3.5, 4.3, 4.4.54.2
    08-12-20161.94.6.4, 4.6.5, 4.6.6MariaDB istedet for MySql, 5.2
    14-12-20161.9
    		8.1 NSI ændret til sundhedsdatastyrelsen

    03-10-2017 

    		2.0Produktionsplatform opdateringer

    Omstrukturering af indhold

    2.2.4 strammere krav til anvendelse af 3. parts libraries.

    MIT licens ajourført med hensyn til navn på Sundhedsdatastyrelsen


    19-07-20182.1Den Gode Brug af Kafka og NSP Audit API.2.1, 2.2, 2.4, 2.6, 2.7

    24-04-2019

    		2.2Q1 ajourføring af husregler

    Brug af Servlet specifikationen er gjort tydeligt i afsnit 2.

    Afsnit 2.1 ændret til OpenJDK.

    Afsnit 2.6.12 udvidet med krav til auditlogning

    Afsnit 5.4.4 tilføjet


    19-09-20192.3Q3 ajourføring af husregler. CI/CD regler og reference til tilhørende dokument. Default konfigurationerOprydning af "gl" referencer
    29-03-20202.4

    Databasetabeller og feltnavne

    Håndtering af Facader/iNSP

    Afsnit 2.7.6 tilføjet

    Afsnit 2.1.6 tilføjet tekst omkring manglende Kafka på iNSP

    Afsnit 2.6.11 tilføjet en beskrivende tekst omkring ID'er ved ikke DGWS/IDWS snitflader

    Afsnit 2.9.1 tilføjet undtagelse omkring JSON snitflader

    Afsnit 2.9.2 tiføjet OpenAPI kontrakter

    Afsnit 2.10.1 tilføjet bemærkning omkring DCC og iNSP/Facader

    Afsnit 5.5.1 tilføjet tekst omkring iNSP/Facader


    17-12-20202.5

    Javadoc

    Skema/wsdl namespaces

    Afsnit 3.5 omkring javadoc tilføjet

    Afsnit 2.9.4 krav om dk.nspop i domænenavn tilføjet

    Afsnit 2.9.5 krav om versionering i namespaces tilføjet


    15-09-20222.6

    2.6.16 Omkring Exception-logging med relevante detaljer.

    2.9.2.1, 2.9.2.2 Omkring brugen af programmatisk genererede klienter pba. fx WSDL- eller OpenAPI-kontrakter.

    2.10.2 Omkring dokumentation af DCC-udstillede services.

    2.12.2 Omkring svar fra webservics i fejlsituationer.

    2.13.1, 2.13.2 Omkring modul-opdeling i Java-projekter.

    Afsnit 2.14 (med 2.14.1, 2.14.2) Omkring brug af sikkerhedstokens mellem NSP-services.



    17-11-20222.7

    5.4.6 tilføjet omkring krav til funktionelle tests



    09-01-20232.8

    2.9.2.3 tilføjet omkring operationer der ikke er implementeret.

    2.7.4 Udvidet hjælpetekst



    27-04-20232.9

    Afsnit 3.6 tilføjet ang udviklingsmetodik



    15-06-20232.10

    Afsnit 2.15 tilføjet ang baggrundsjob



    20-02-20242.11

    Afsnit 2.1.7 tilføjet ang. DI



    20-02-20242.12

    Afsnit 2.9.6 og 2.9.7 tilføjet ang udstilling af WSDL med og uden sikkerhedsheaders

    Continuous integration (gl 3.5)

    Komponentleverandøren kan etablere internt CI til kvalitetssikring af den enkelte komponent. NSP projektet benytter også et CI miljø – dette vil som minimum blive brugt ved modtagelse af komponentleverancer.

    Info

    3.4.1 § Komponenter skal kunne bygges vha. en automatiseret proces. Afhængigheder skal enten kunne angives som en konfiguration til byggeprocessen eller komponentleverancen skal understøtte opløsning af disse uden intervention. (gl 3.5.1)

    Info

    3.4.2 § Bygge scripts skal være udformet således at byg af komponentleverancer er idempotent (gl 3.5.2)

    Info

    3.4.3 § Unittest eller andre komponentspecifikke test skal være inkluderet i denne proces. (gl 3.5.3)

    Krav til test metode og værktøjer

    Unit test – JUnit

    Info

    4.1.1  § Test af komponenter skal kunne udføres med , seneste version af JUnit (anbefalet). (gl. 3.1.4)

    Afvikling af unittests er en del af NSP bygge- og releaseprocessen, og skal enten indgå direkte i bygget, eller kunne udføres separat efter anvisning i medfølgende dokumentation.

    Code coverage – overordnet

    Der er fra SDS’s side sat et mål for code coverage for leverancer. Dette tal kan variere afhængigt af hvilket værktøj og opsætning, der benyttes.

    Info

    4.2.1 § Code coverage målet er 80%. NSP Projektet kontrollere graden af code coverage ved modtagelse (gl. 3.2.1)

    Desuden kan dele af leverancer fravælges at blive dækket; f.eks. fordi en del kode er genereret. I medfølgende dokumentation, under beskrivelse af genereringen af code coverage, bør dette være beskrevet.

    Performance test - JMeter

    Info

    4.3.1  § Performance test af komponenter bør foretages med JMeter. (gl. 3.1.6)

    Krav til leverance og installation

    Leverance generelt

    En leverance består af komplet kildekode for komponenten/komponenter, konfigurationsfiler, Maven (POM), Index og Database skema ændringer, samt dokumentation.

    Krav omkring dokumentation fremgår af NSP projektets dokumentationskrav.
    Info

    5.1.1 § NSP projektet har til hensigt at offentliggøre kildekoden. Derfor skal hensyn desangående beskrives. Dette vil imødekommes på offentliggørelsestidspunktet. (gl. 2.0.2)

    Licens

    Info

    5.2.1 § Kildekoden skal være udstyret med MIT licens. Den eksakte ordlyd af denne kan erhverves hos SDS. (gl. 2.0.1)

    En ikke autoritativ udgave af headeren kan findes under § 9.1

    Subversion

    Info

    5.3.1§ Kildekode samt dokumentation skal leveres til et subversion repository på (gl. 2.0.3)

    svn.nspop.dk.

    Hver komponentleverandør vil have adgang til et subversion repository, hvortil også NSP projektet har adgang. Dette repository benyttes jvf. normale subversion konventioner, se iøvrigt NSP SVN anvendelse.  

    Tests

    Testdokumentation

    Info

    5.4.1  § Den leverede dokumentation skal beskrive, hvordan de forskellige typer af tests skal udføres. Her refereres i særdeleshed til følgende typer: (gl. 3.6.1)

    • Unit tests, som udføres under byg.
    • Integrationstests, som udføres mod den deployerede komponent.

    Som minimum vil de blive brugt på følgende måder: unit-tests til at generere code coverage information, og integrationstests til at verificere korrekt deployeret komponent. 

    Testspecifikationer

    Info

    5.4.2  § Leverancen skal indeholde unit tests, der bruges som ovenfor nævnt. (gl. 3.6.2)

    Info

    5.4.3  § Leverancen skal indeholde integrationstest, der bruges som ovenfor nævnt. (gl. 3.6.3)

    Derudover må leverancen indeholde andre former for tests, så som performance- og endurance tests. Disse vil ligeledes indgå i kvalitetssikringen af releaset så vidt det er muligt at gentage disse. Derfor er det vigtigt at udførslen af disse tests er dokumenteret.

    Installation (gl 6)

    Komponenterne skal deployes i et miljø med 2 søjler med henholdsvis load-balancere, app-servere og database-servere, i alt 6 instanser, som enten sættes op i regionerne eller på central lokation, dog altid forbundet til sundhedsdatanettet. Komponenterne bør være forberedt på de krav det måtte medføre.

    Info

    5.5.1  § Komponenter har kun adgang til services udstillet på sundhedsdatanettet. Det skal specielt bemærkes, at der kun er begrænset adgang til certifikatinfrastrukturen: HTTP adgang til CRL og krydscertifikat er muligt på normal vis. Desuden udstilles RID/CPR tjenesten. (gl. 6.0.1) 2 

    Info

    5.5.2  § Der skal kunne opsættes timeouts på kald til eksterne services. Komponenter skal endvidere behandle timeout forventelig overfor klienten/klientsystemet. (gl. 6.0.2)

    Sagshåndtering (gl 7)

    JIRA systemet anvendes til håndtering af sager der omhandler komponent-releases, fejlrettelser, ny funktionalitet eller andre opgaver relateret til komponenter leveret til NSP-projektet. Se NSP projektets instruktion i brug af på NSP sagshåndtering.

    Info

    5.6.1  § Henvendelser vedrørende forhold omkring releases, der ikke kan spores tilbage til en sag i JIRA, vil blive afvist (gl. 7.1.2)

    Info

    5.6.2  § En sag i JIRA bør begrænses til at omhandlet én opgave. Dette gælder både når en sag startes og senere i forløbet. (gl. 7.1.3)

    Krav til driftsmæssige forhold

    Afhængigheder

    Info

    6.1.1  § Komponenter skal kunne starte op (deploye), selvom deres afhængigheder ikke er tilgængelige. (gl. 5.1.1)

    Info

    6.1.2  § Komponenter skal logge en ERROR eller WARN fejltype såfremt de driftsmæssige forudsætninger ikke er opfyldt (gl. 5.1.2)

    Hvis en komponent f.eks. er afhængig af certifikater placeret i filsystemet, skal komponenten verificere at disse tilgængelige .

    Udløb af certifikater skal checkes jvnf ovenstående.

    Info

    6.2.3  § Komponenter skal desuden være i stand til at genoprette deres tilstand, når afhængighederne igen er tilgængelige. (gl. 5.1.3)

    En manglende afhængighed kan f.eks. være forbindelsen til databasen. Når databaseforbindelsen igen kan etableres, skal komponenter være i stand til at bemærke dette og genforbinde.

    Krav til dokumentation

    Gennerelle krav til dokumentation er beskrevet grundigt her.

    Dokumentation af værktøjer

    Info

    7.1.1  § Leverede dokumentation skal beskrive anvendelse af de brugte værktøjer samt angive specifikke versioner deraf. (gl. 3.1.7)

    Test dokumentation

    Info

    7.2.1  § Den leverede dokumentation skal beskrive, hvordan de forskellige typer af tests skal udføres. Her refereres i særdeleshed til følgende typer: (gl. 3.6.1)

    • Unit tests, som udføres under byg.
    • Integrationstests, som udføres mod den deployerede komponent.

    SLA logpunkter

    Info

    7.3.1  § Identifikationen samt beskrivelse af SLA-logpunkter skal indskrives i dokumentationen. (gl. 4.5.11)

    Ressourceforbrug

    Info

    7.4.1  § En komponents ressource krav skal fremgå af dokumentationen. (gl. 5.2.1)

    Krav til ændringer

    Post-leverance ændringer (gl 3.7)

    NSP projektet kan forke/ændre en komponent efter leverance for at tilgodese et driftsaspekt eller rette op på en mindre fejl. Ændringer af binære artefakter er et eksempel på en mindre ændring.

    Info

    8.1.1 § Hvis NSP projektet har foretaget ændringer i en komponents funktionalitet, så skal disse eller tilsvarende ændringer som minimum inkluderes i næste release. (gl. 3.7.1)

    Processen vil generelt være beskrevet af følgende: NSP projektet vil enten i samråd med komponentleverandøren eller selvstændigt foretage en ændring i en komponent til et givet release. Denne ændring forventes herefter at være inkluderet i komponenten, enten i samme form eller implementeret på anden vis. Ændringerne vil være tilgængelige for leverandøren.

    Generelt vil der stræbes mod ikke at foretage større ændringer uden at leverandøren er inddraget.



    Appendix

    Licens

    Licens header

    Code Block
    titleLicens header
    The MIT License
 
Original work sponsored and donated by
    National
    The
    Board of
    Danish
    e-
    Health
    (NSI), Denmark
    Data Authority (http://www.
    nsi
    sundhedsdatastyrelsen.dk)
 
Copyright (C)
    2011
    2020
    National
    The
    Board
    Danish
    of e-
    Health
    (NSI), Denmark
    Data Authority (http://www.
    nsi
    sundhedsdatastyrelsen.dk)
 
 
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
 
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

    ...