Introduktion
Formål
Formålet med dette dokument er at beskrive hvordan et udviklingsmiljø, til videreudvikling af Min Spærring services, kan sættes op, samt hvordan koden bygges, deployes og testes.
I afsnit 3 beskrives de softwaremæssige krav der er til miljøet samt hvordan kode hentes og bygges. I afsnit 4 beskrives deploymentmiljøet.
Kodestrukturen, kodemæssige afhængigheder til tredjeparts moduler og de forskellige servicemodulers ansvar og design beskrives i afsnit 6.
Testdesign findes i afsnit 7.
Sammenhæng med øvrige dokumenter
Dette dokument er en del af den samlede dokumentation for DDS projektet.
Dokumentets relation til de øvrige dokumenter er beskrevet i dokumentationsoversigten for projektet [Oversigt].
Læsevejledning
Læser forventes at have kendskab til Java softwareudvikling med anvendelse af Maven, WildFly applikationsserver og MySQL samt docker og docker-compose.
Hvor der i teksten er angivet <component base> refereres til topniveaufolderen for kildekoden for komponenten.
Dokumenthistorik
Version | Dato | Ansvarlig | Beskrivelse |
---|---|---|---|
1.0 | 29.06.2012 | Systematic | Initiel udgave |
1.1 | 21.08.2012 | Systematic | Ændring i afsnit 3.2, 4.2 og 7.2 grundet opdateret bygge- og testprocedure. |
1.2 | 18.09.2012 | Systematic | Ændring grundet ny profile til byg uden mysql adgang fra byggeserver |
1.3 | 23.05.2014 | Systematic | Ændring afspejler opsplitning af tidl. NPI-projekt i selvstændige komponenter. |
1.4 | 28.11.2014 | Systematic | Referencer til Nationalt Patientindeks (NPI) fjernet |
1.5 | 27.02.2015 | Systematic | Nye kommandoer til maven og ændring af npi og npiservices til dds |
1.6 | 02.02.2016 | Systematic | Opgradering til WildFly Forbedret codecoverage beskrivelse |
1.7 | 16.12.2016 | Systematic | Fjernet beskrivelse af code-coverage generering for unittest. |
1.8 | 13.06.2018 | Systematic | Migreret til NSPOP SVN |
22.10.2018 | KIT | Dokument flyttet fra Word til Confluence. Original dokument navn var: PHB0007 Guide til Udviklere Samtykke Service.docx | |
19.03.3030 | KIT | Docker | |
14.05.2020 | KIT | SDS-3883 Etablering af IDWS snitflade | |
03.08.2020 | KIT | Beskrivelse af hvordan code coverage fra integrationstest flettes ind i code coverage fra unittest | |
09.11.2020 | KIT | SDS-3685: Min Spærring skal anvende SORES til SOR-SHAK opslag | |
06.05.2021 | KIT | SDS-2416: MinSpærring skal ændres til at kalde minlog2 |
Definitioner og referencer
Definition | Beskrivelse |
---|---|
NSI | National Sundheds-IT |
NSP | Den nationale service platform (inden for sundheds-IT) |
SHAK | Sygehusafdelingsklassifikation |
SOR | Sundhedsvæsenets organisationsregister |
STS | Security Token Service |
Alias | Beskrivelse |
---|---|
Oversigt | Dokumentationsoversigt (SSE/11734/SOD/0001) |
DGWS | Den Gode WebService 1.0.1 |
IDWS | OIO-IDWS 1.1 |
Design | Design og Arkitektur Min Spærring Service (SSE/11734/SDD/0003) |
Installationsvejledning | Installationsvejledning Min Spærring Service (SSE/11734/INS/0002) |
Min-log | Design og Arkitektur Min-log Service (SSE/11734/SDD/0002) |
Introduktion til Min Spærring services
Realisering af Min Spærring services omfatter to Java-baserede webservices:
Min Spærring administrationsservice
Der tillader registrering og vedligehold af afgivne samtykke/spærring for en borger.
Ved registrering af samtykker/spærringer for borger hvor den aktive bruger handler på vegne af borgeren, skal hændelsen registreres i Min-log-registreringsservicen (se MinLog).
Administrationsservicen udstilles via NSP DCC og implementeres på NSI platform med dataansvar.
Min Spærring verifikationsservice
Der gør det muligt at undersøge samtykke- og spærringsforholdene mellem en borger og en sundhedsperson.
Verifikationsservicen udstilles som en webservice på NSP'erne.
DoDi'en (Data opsamling og Distributions platformen i NSP regi) anvendes til replikering af Min Spærring databasen til NSP’ere.
For en dybere introduktion til de to services og baggrunden bag, se [Design].
Opsætning af udviklingsmiljø
I det følgende antages at koden er hentet ned fra softwarebørsen el.lign.
Krav til software
Krav til applikationsserveren, operativsystemet og databasen er de samme som til produktionsmiljøet. De specifikke krav kan ses i [Installationsvejledning] afsnit 2.
Derudover er der en række krav til de anvendte udviklingsværktøjer:
- Maven 3.0.3 eller højere anvendes.
- docker-compose der understøtter compose version 2 formatet.
Bygge EAR filen
Følgende software er nødvendig for at bygge projektet
Maven (min. version 3.0.3)
- Docker
Gennemfør følgende steps for at bygge EAR filerne.
mvn package
Afvikler integrations-test mod det miljø der er angivet i property fil.
mvn verify –Pexternal-test \ -Denvironment-property-file=<sti til tilpasset environment.properties> \ -Dtestclient-property-file=<sti til tilpasset testclient.properties>
Bemærk at -Pexternal-test kræver at Minlog Registration er deployeret på WildFly.
Deployment på WildFly
Der henvises til installationsvejledningen [Installationsvejledning] for nærmere instrukser.
Udviklers workstation
Når man udvikler kan det være praktisk at starte docker-compose setup i compose/development og afvikle integrationsstest mod dette.
Beskrivelse af systemdesign
Systemdesign er beskrevet i [Design].
Beskrivelse af kildekodens strukturering og design
Kode strukturering
Projektet er delt i følgende moduler:
consentservices/common – modul der indeholder DAO komponenter til consent services og SORES service, samt fælles funktionalitet til Min Spærring webservices.
consentservices/consentadministration – modul der indeholder webservice til Min Spærring administration.
consentservices/consentverification – modul der indeholder webservice til verifikation af samtykker/spærringer.
- nas-notification – modul der indeholder funktionalitet til kald af NAS Notification Broker, for at advisere om ændringer på en borgers spærringer.
- sores-integration - modul der indeholder funktionalitet til kald af SORES-servicen.
Der er afhængigheder til forskellige artefakter, hvoraf følgende er skabt i regi af NSI:
services-common – modul der indeholder de dele af koden der er fælles for alle komponenterne, herunder interface til opslag i SORES service, DGWS fejlkoder, samt utilities til logning med mere.
hsuid – modul der indeholder implementering af OIO attributter til identifikation af sundhedsfaglige personer, der er fælles for webservicekomponenter, der anvender DGWS.
dgws/common – modul der indeholder implementering af DGWS fælles funktionalitet til håndtering af DGWS header og fejlkoder.
dgws/provider – modul der indeholder implementering af DGWS provider funktionalitet, der anvendes af alle komponenter der anvender DGWS i rollen som web service provider.
dgws/consumer – modul der indeholder implementering af DGWS consumer funktionalitet, der anvendes af komponenter der anvender DGWS i rollen som web service consumer (aktuelt ConsentAdministration, der kalder Min-log-registration webservicen).
minlog-registration-client – modul der indeholder funktionalitet til kald af webservice til registrering af hændelser i en borgers Minlog.
- security-api – modul der indeholder implementering af IDWS funktionalitet.
Generelt design af Min Spærring services
De to Min Spærring services består hver af en række mavenmoduler under deres respektive moduler (consentadministration og consentverification):
application: Indeholder webservice, EJB og forretningslogik
ear: Bygger ear-filen der skal deployes
serviceinterface: Indeholder Java-interfacet til webservicen
client: Indeholder webserviceklienten
integrationtest: Indeholder integrationstests af webservicen
Snitfladen for de to services adskiller sig på følgende måde:
Min Spærring administrationsservice er implementeret ved brug af IDWS, hvor Seal.Java er anvendt til at håndtere headers.
Min Spærring verifikationsservice er implementeret ved brug af Den Gode Webservice [DGWS], hvor Seal.Java er anvendt til at håndtere headers.
Derudover er der en række generelle designvalg for de to services:
JAX-WS er anvendt til kodegenerering ud fra WSDL-filer og XJC er anvendt til JAXB kodegenerering ud fra XSD-filer.
Servicen er implementeret som en EJB stateless session bean.
Hibernate er anvendt som framework til mapning af Min Spærring data i SQL-databasen.
Generelt design af Min Spærring administration
Nedenstående figur giver et overblik over de væsentligste package dependencies for Min Spærring administrationsservicen (consent-administration). Der er ikke tale om en komplet nedbrydning.
Figur 1 consent-administration dependencies
Generelt design af Min Spærring verifikation
Nedenstående figur giver et overblik over de væsentligste package dependencies for Min Spærring verifikationsservice (consent-verification). Der er ikke tale om en komplet nedbrydning.
Figur 2 consent-verification dependencies
Beskrivelse af testsetup
Unittests (JUnit)
JUnit anvendes til implementering af unit tests. Der er kontinuert gennemført unit tests på alle komponenter i projektet.
Unit tests kan afvikles ved at køre:
mvn test
Integrationstests (Failsafe)
Maven Failsafe plugin anvendes til gennemførelse af integrationstests af Min Spærring webservices.
Integrationstestene af Min Spærring administration er afhængige af at Min-log-registreringsservicen er deployet.
Det nødvendige testdata læses automatisk på af maven-scriptet, inden integrationstestene afvikles.
Integrationstests kan afvikles ved at køre:
mvn verify –Pexternal-test
Bemærk at dette forudsætter at docker-compose setup er startet.
Code coverage
Code coverage analyse er foretaget i projektet med anvendelse af Maven Jacoco plugin. Code coverage beregnes automatisk ved byg. Dette er både lokalt og på Jenkins.
Code coverage fra integrationstest
Det er muligt at inkludere code coverage fra integrationstesten. Det kan gøres på følgende måde:
1. Tilføj følgende til development/docker-compose.yml (det der er markeret med fed skrift):
consentverification:
volumes:
- ../configuration/jacoco/jacocoagent.jar:/jacoco/jacocoagent.jar
- ../../integrationtest/target/jacoco-it:/jacoco-report
environment:
- JAVA_OPTS="-javaagent:/jacoco/jacocoagent.jar=output=file,destfile=/jacoco-report/jacoco-it-verification.exec,dumponexit=true,append=true"
consentadministration:
volumes:
- ../configuration/jacoco/jacocoagent.jar:/jacoco/jacocoagent.jar
- ../../integrationtest/target/jacoco-it:/jacoco-report
environment:
- JAVA_OPTS="-javaagent:/jacoco/jacocoagent.jar=output=file,destfile=/jacoco-report/jacoco-it-administration.exec,dumponexit=true,append=true"
2. Kopier jacocoagent.jar under compose/configuration/jacoco/
3. Start servicen op i docker-compose
4. Verificer ved at logge ind i docker-containeren at følgende filer findes:
- /jacoco/jacocoagent.jar
- /jacoco-report/jacoco-it-verification.exec (den er tom)
- /jacoco-report/jacoco-it-administration.exec (den er tom)
De to sidste filer skal også findes på ens egen maskine under:
- ../../integrationtest/target/jacoco-it/jacoco-it-verification.exec
- ../../integrationtest/target/jacoco-it/jacoco-it-administration.exec
5. Kør integrationstesten
6. Stop docker-compose (meget vigtigt, da det først er der man kan se indholdet af de to .exec-filer)
8. Verificer at der nu er indhold i disse to filer:
- ../../integrationtest/target/jacoco-it/jacoco-it-verification.exec
- ../../integrationtest/target/jacoco-it/jacoco-it-administration.exec
9. Inkluder følgende i pom.xml så jacoco-it.exec bliver flettet ind i resultatet af unittesten:
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<executions>
<execution>
<id>exec-merge</id>
<phase>verify</phase>
<goals>
<goal>merge</goal>
</goals>
<configuration>
<fileSets>
<fileSet implementation='org.apache.maven.shared.model.fileset.FileSet'>
<directory>${basedir}</directory>
<includes>
<include>**/*.exec</include>
</includes>
</fileSet>
</fileSets>
</configuration>
</execution>
</executions>
</plugin>
10. Kør et alm maven build, så de to .exec-filer bliver flettet sammen med jacoco-output fra unittests (Det er vigtigt den bliver kør uden "clean"):
mvn install
Performancetests (JMeter)
Performance test gennemføres med anvendelse af JMeter.
Testen består i at SOAP-requestet fra to integrationstests, i Min Spærring verifikationsservicen, sendes til servicen 100 gange i streg i 10 parallelle tråde.
SOAP-requestet genereres ved at køre alle integrationstestene til verifikationsservicen (ConsentVerificationServiceIT). De to udvalgte integrationstests er verifyDataForPositiveConsentForDataForOrg og verifyDataSpecificResultForNegativeConsentForDataForAll.
Performancetesten findes i dds/performance.