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

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

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

1.3. Begreber og forkortelser

Få forklaringer på begreber og forkortelser i ordlisten.

2. Designkrav

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

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.

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

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

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

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.

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)

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

2.2. Anvendelse af kodebiblioteker

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.

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.

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.

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

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.

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.

2.3. HAProxy

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

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. 

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

2.4. Konfiguration

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.

2.4.1 § Statisk konfiguration skal være filbaseret.

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.

2.4.2 § Database opsætning bør ske vha. en selvstændig Wildfly datasource descriptor fil og benyttes ud fra JNDI eller lignende tilgang.

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.

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.

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.

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

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

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

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

2.5. Snitflade til monitorering

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.

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.

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.

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

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. 

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.

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

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

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.

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

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.

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.

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

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.

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.

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.

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. 

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.

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.

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. 

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

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.

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.


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

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. 

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

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.

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)

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.

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.

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

2.8. Komponentinteraktion

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

Se. afsnit 7. Krav til dokumentation.

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.

2.9. Webservices

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

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

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.


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. 


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

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.

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 

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

Namespaces skal yderligere være datoversionerede.

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

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.

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.

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

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:

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.


2.11. Særlige komponentspecifikationer

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

2.12. Fejlsvar

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

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.

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


2.13. Kodestruktur

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

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.

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:

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

2.14. Sikkerhedstoken-principper

Afsnittet omhandler brug og genbrug af sikkerhedstokens på NSP.

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.

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.

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

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.

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.

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.

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

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


3. Krav til udviklingsværktøjer og metode

3.1. Værktøjer

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:

docker pull registry.nspop.dk/tools/nspbuilder:jdk8

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.

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

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

3.2. Nexus

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

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.

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

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.

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

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.

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

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

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

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

3.5.2 § Javaklasser skal dokumenteres med javadoc i koden

3.6. Udviklingsmetodik

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

Udviklingsmetodikken er beskrevet i yderligere detaljer her

4. Krav til test metode og værktøjer

4.1. Unit test – JUnit

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.

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

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.

4.3. Performance test - JMeter

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

Krav ifm performancetest er specificeret i dokumentet Performancekrav

5. Krav til leverance og installation

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

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.

5.2. Licens

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

5.3. Subversion

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.

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.

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"

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.

5.4. Tests

Testdokumentation

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

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

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

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.

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.

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

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

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.

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

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

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

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.

6. Krav til driftsmæssige forhold

6.1. Afhængigheder


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

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.

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.

7. Krav til dokumentation

Gennerelle krav til dokumentation er beskrevet grundigt her.

7.1. Dokumentation af værktøjer

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

7.2. Test dokumentation

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.

7.3. SLA logpunkter

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

7.4. Ressourceforbrug

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

8. Krav til ændringer

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

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.

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



10. Appendix

10.1. Licens

Licens header

Licens header
The MIT License
 
Original work sponsored and donated by The Danish Health Data Authority (http://www.sundhedsdatastyrelsen.dk)
 
Copyright (C) 2020 The Danish Health Data Authority (http://www.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.
  • No labels