Page History
...
Numbered Headings | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
IntroduktionDette 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 statusHusreglerne 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 referencerKrav 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 forkortelserFå forklaringer på begreber og forkortelser i ordlisten. DesignkravPlatformEndelig 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å:
Applikationsstack
Applikationsserver-platformen stiller standard Java Servlet funktionalitet til rådighed, så som JNDI, JDBC og servlet API.
Anvendelse af kodebiblioteker
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.
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
Loadbalanceren påhæfter altid HTTP forespørgsler en ny header indeholdende klientens IP adressen i HAProxy anvender round-robin til fordeling af forespørgelser, der rammer NSP’en. Desuden understøtter HAProxy ikke session affinitet.
KonfigurationKomponenter 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.
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.
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.
Eksempelvis kunne dette muliggøres ved at have en extra kolonne i tabeller med adgangskontrol.
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
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.
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.
JMX snitflader til rapportering understøttes på platformen; specielt ifht. statistiske forhold kan dette være at foretrække. LogningKomponenter forventes at forholde sig til følgende typer af log:
Hvis komponenter kalder andre komponenter, hvortil det ikke skønnes at være et viderestillingskald, så skal headeren,
Logpunkterne skal bla. omfatte, webservices, schedulerede jobs, kald til andre services og ligende tasks.
NSP-Util indeholder en de’facto standard for omtalte logformat, og det anbefales at komponenter anvender biblioteket til SLA-logning.
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
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.
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.
Fejlsituationer vil blive behandlet af driftsleverandøren, såfremt dette kan lade sig gøre, og at dette er beskrevet i medfølgende dokumentationen.
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. PersistensPlatformen 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.
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.
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 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)
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.
Databasetabeller og feltnavne skal være sigende og angives med bogstaverne fra A-Z, 0-9 og _. Danske bogstaver (æøå) er således ikke tilladte.
Komponentinteraktion
Se. afsnit 7. Krav til dokumentation.
WebservicesEn udstillet webservice snitflade skal understøtte UTF-8 jvf. DGWS. For krav til REST services, se Husregler for REST services.
Brugere af services kan herved nemt generere klienter.
Se afsnit "2.2. Anvendelse af kodebiblioteker" ang. hvilke værktøjer der vælges til kodegenerering.
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
Namespaces skal yderligere være datoversionerede.
Et eksempel på en URL version kunne være https://nspop.dk/nsp/<service-navn>/2020/02/24
Hvis komponenten udstiller en SOAP service på pathen
Hvis komponenten udstiller en DGWS service på pathen Ligeledes for en OIO-IDWS service udstillet på pathen 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. DCCDCC 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.
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:
Særlige komponentspecifikationerImplementering af Stamdata import moduler skal anvende modulerne; SDM-Core, SDM-Parent. FejlsvarSvar fra udstillede DGWS services skal følge standarden og skal være til nytte for både anvendere og i supportøjemed.
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.
KodestrukturFor at sikre en ensartet kodestruktur skal følgende husregler så vidt muligt overholdes.
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.
Følgende standard for pakker skal anvendes:
Sikkerhedstoken-principperAfsnittet omhandler brug og genbrug af sikkerhedstokens på NSP.
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.
Den udviklede service skal derfor have udstedt et systemcertifikat specifikt til kald af disse støtteservices. BaggrundsjobNogle 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.
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.
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.
Jobbet skal anvende det almindelige NSP Docker Image.
For at sikre simpel parsning bør en log linie indeholde key=value par med mellemrum omkring f.eks:
Snitfladen skal overholde alle reglerne i afsnittet "2.5. Snitflade til monitorering". Krav til udviklingsværktøjer og metodeVærktøjer
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:
Dette er f.eks. vigtigt mht.
NexusProjektet stiller et maven repository til rådighed for leverandører. Detaljer heromkring findes på NSP Nexus vejledning.
I repositoriet findes NSP projektets bibliotekter samt andre afhængigheder. Det vil desuden være muligt at udvide repositoriet med yderligere artefakter. BygKomponenter 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.
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 integrationKomponentleverandøren skal anvende NSP's Continuous integration and Delivery miljø og tilhørende Docker images. Dette vil ligeledes blive brugt ved modtagelse af komponentleverancer.
JavadocKomponentleverandø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.
Udviklingsmetodik
Udviklingsmetodikken er beskrevet i yderligere detaljer her Krav til test metode og værktøjerUnit test – JUnit
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 – overordnetDer 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.
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
Krav ifm performancetest er specificeret i dokumentet Performancekrav Krav til leverance og installationLeverance genereltEn 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.
Licens
En ikke autoritativ udgave af headeren kan findes under § 9.1 Subversion
NSP repositories benyttes jvf. normale subversion konventioner, se iøvrigt NSP SVN anvendelse.
NSP repositories udstilles offentligt med læseadgang, inklusiv "commit" kommentarer.
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"
NSP komponenter der tagges som <major.minor.micro>, skal ved snitfladeændringer have ændret minor-version. TestsTestdokumentation
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
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.
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.
InstallationKomponenterne 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.
SagshåndteringJIRA 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.
Krav til driftsmæssige forholdAfhængigheder
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.
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 dokumentationGennerelle krav til dokumentation er beskrevet grundigt her. Dokumentation af værktøjer
Test dokumentation
SLA logpunkter
Ressourceforbrug
Krav til ændringerPost-leverance ændringerNSP 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.
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
AppendixLicensLicens header
|