Page History
Navitabs | ||||
---|---|---|---|---|
| ||||
Table of Contents |
---|
Introduktion
Formål
Formålet med dette dokument er at beskrive hvordan et udviklingsmiljø, til videreudvikling af NAP SDK, skal sættes op, kodens struktur, samt hvordan koden bygges, deployes og testes.
Sammenhæng med øvrige dokumenter
Dette dokument er en del af den samlede dokumentation for NAP SDK.
Dokumentet er udformet, så det i videst muligt omfang opfylder sit formål uafhængigt af de øvrige dokumenter.
Ønskes mere information omkring arkitektur og design findes dette på NAP SDK - Design og Arkitektur beskrivelse.
Ønskes mere information omkring installationsvejledning til anvender kan findes på NAP SDK - Installationsvejledning.
Ønskes mere information omkring guide til anvendelse findes dette på NAP SDK - Guide til anvendere.
Forudsætninger
Kildekoden til NAP-SDK findes på https://svn.nspop.dk/svn/libraries/nap/
Software requirements
NAP-SDK er udviklet og testet på.
Pakke | Version |
---|---|
npm | 6.14.8 |
node | 14.4.0 |
Nap-typescript-sdk
Udviklingssetup og targets:
Installer
...
afhængigheder
Installer dependecies dependencies ved at køre `npm i`
Build
install --registry https://nexus.nspop.dk/nexus/repository/nsp-npm/`
Byg
Kør "npm run build" Kør `npm run build` for at bygge projektet. Dette giver et output i dist/ folderen.
...
For at køre unit tests med Karma kør `npm "npm run test`test". Det smider genererer en coverage rapport i coverage/ folderenmappen.
Eventuelle fejl skrives til STOUT.
CI
For at bygge SDK til CI køre `npm "npm run ci:build`build". Jenkins filen beskriver jenkins pipelinen.
Releases og snapshots
Der kan laves snapshots og release-candidates fra jenkins til NSP npm repository.
Versionering af Nap-typescript-sdk følger sem.
For at lave et release opdateres versionen i (package.json), hvorefter der køres en `npm i` for at opdatere package-lock.json.
Dernæst laves et tag i SVN på den følgende version manuelt som fx:
Code Block | ||
---|---|---|
| ||
svn copy https://svn.nspop.dk/svn/libraries/nap/nap-typescript-sdk/trunk \
https://svn.nspop.dk/svn/libraries/nap/nap-typescript-sdk/tags/release-1.0.0-rc.1 \
-m "Tagging the 1.0.0-rc.1 release of the 'nap typescript sdk' project."
|
Det er vigtigt at tagget i svn stemmer overens med versionen i package.json og package-lock.json
Linting
Kør `npm "npm run lint` lint" for linting.
Eventuelle fejl skrives til STOUT.
...
Dokumentation
For at generere TsDoc køre `npm run doc`dokumentation til koden, kør "npm run doc". Dokumentation ligger i docs/ mappen.
Projektstruktur
NAPMessages
NAPmessages NAPMessage er meget inspireret af FHIR / FHIRcast (https://fhircast.org/specification/Feb2020Ballot/), og er udgangspunktet i NAPmessage NAPMessage datastrukturen og grundlaget for de events der er implementeret i eventkatalog eventkataloget version 1.
Eventkataloget fungerer som versionering af NAP eventsNAPMessages.
Et anvenderprojekt definerer hvilken version af eventkataloget den implementerer.
Dette fungerer som en kontrakt således, at et givent værtssytem ved at et giventprojekt givent projekt kan håndtere en række events.
Skal der implementeres nye events kræver det nye releases nyt release af nap-typescript-sdketsdk'et.
Bro
Nærmere beskrivelse mangler.
Marshalling
Nærmere beskrivelse mangler.
Message-streams
NAP Bridge (kontekstdeling)
En NAP bridge er et simpelt interface med en send-funktion og en callback handle.
Code Block | ||
---|---|---|
| ||
interface NAPHostBridge {
setCallback: (handler: { handle: (message: string) => void }) => void;
send: (message: string) => void;
} |
Et værtssystem skal ligge en sådan bridge på window.NAP - for nærmere beskrivelse af det, henvises til Guide til anvender.
Når "nap-typescript-sdk" kalder "createNAP()", bruger den referencen til denne bridge. Håndtaget til sendMessage() bruges til at initialisere en toHost kanal (fra det indlejrede system til værtssystemet). Håndtaget for setCallback bruges for at opsætte en fromHost kanal (fra værtssytemet til det indlejrede system).
Dependencies skal installeres for både roden og projektetNærmere beskrivelse mangler.
FhirValueGetter
Der er defineret et fhir-value-getter NameSpace namespace med utility hjælpe funktioner til mappe NapMessages NAPMessages til de værdier, som egentlig er interessaninteressante..
Mapping funktioner | |
Funktionsnavn | Beskrivelse |
---|
getFilteredProjects() | Trækker |
en string liste ud med WebAppShortnames. | |
getPatientInfo() | Trækker familyName, givenName og ssNo ud af et PatientOpenEvent |
FhirValueSetter
Der er defineret et fhir-value-setter NameSpace til setter namespace, som indeholder enums af typiske værdier, der skal sættes i for NapMessagesNAPMessages.
Mapping funktioner | |
Type | Beskrivelse |
---|---|
FHIRResourceType | Resource typen for event ('Patient' | 'Basic') |
FHIRSystem | System identifier ('nap') |
FHIRIdentifierSystem | System identifier til cpr, errorMessage og errorDescription |
FHIRextensionURL | Url for extensions WEBAPPSHORTNAMES, WEBAPPSHORTNAME, WEBAPPAUDIENCE, WEBAPPSERVICEENTRY, WEBAPPPRODUCER, WEBAPPRELEASEDATE, WEBAPPURL, WEBAPPCATALOGUEVERSIONS |
EventKatalog
Fungerer som versionering af de forskellige events, hvor der udstilles håndtag de events der er implementeret i en given version. Desuden udstiller den også hjælpefunktioner til at generere NAPmessages.
Code Block | ||
---|---|---|
| ||
export const EventCatalogue: EventCatalogues = {
v1: {
WebAppSelected: NAPEventType.WebAppSelected,
PatientOpen: NAPEventType.PatientOpen,
PatientClose: NAPEventType.PatientClose,
ProjectsRetrieved: NAPEventType.ProjectsRetrieved,
ProjectsFiltered: NAPEventType.ProjectsFiltered,
SessionClose: NAPEventType.SessionClose,
SessionError: NAPEventType.SessionError,
MessageFactory: {
createPatientOpenMessage: createPatientOpenMessageV1,
createPatientCloseMessage: createPatientCloseMessageV1,
createProjectsRetrievedMessage: createProjectsRetrievedMessageV1,
createSessionCloseMessage: createSessionCloseMessageV1,
createSessionErrorMessage: createSessionErrorMessageV1,
createWebAppSelectedMessage: createWebAppSelectedMessageV1
}
},
}; |
Nap-angular-sdk
Indeholder 3 "projekter".
- Et angular workspace i src-folderen. Her ligger en DEV.README, specifikt egnet til udviklere, som beskriver de npm targets der opsat i projektetDette kræves af angular framework for at serve et library.
- Det egentlige nap-angular-sdk i projecsprojects/nap-angular
- ng-package.json definerer de filer der skal pakkes og publishes.
- En test implementering, som motionerer bruger nap-angular-sdk i projects/test. Heri er injected en fakebridge i index.html. Dette er den egentlige test af SDKet, og der køres derfor ingen unit tests. Sendte beskeder printes i console.log.
Funktionalitet
SDK'et udstiller en service, som sørger for at kalde createNAP() fra nap-typescript-sdket og dermed initialisere NAP bridge (konteksdelingsbroen).
Efterfølgende subscribes der på de forskellige messagestreams, og deres emits bliver håndteret i forhold til Angulars change detection zone og udstillet i nye observables.
|
Effekten for anvenderen bliver, at broen initialiseres som en singleton og at Angular opfanger beskeder sendt over broen og opdaterer UI på baggrund af disse værdier.
Udviklingssetup og targets
Installer afhængigheder
Installer dependencies ved at køre npm install --registry https://nexus.
...
nspop.dk/nexus/repository/nsp-npm/
Vær opmærksom på, at der findes en afhængighed til nap-typescript-sdk både for workspacet (package.json) og for selve sdket (projects/nap-angular/package.json). Begge skal opdateres, for at anvende en nye version.
Byg
Kør "npm run build" for at bygge projeket med sdk. Dette giver et output i dist/ folderen.
Udviklingserver
Testimplementeringen har en afhængig til nap-angular-sdk, derfor skal dette bygges, som beskrevet ovenfor, før en udviklings server kan startes.
For at starte en web pack dev server kør "npm run start:dev". Dette vil starte test implementering på (projects/test) http://localhost:4200/.
CI
Jenkins filen beskriver jenkins pipelinen.
Releases og snapshots
Der kan laves snapshots og release-candidates fra jenkins til NSP npm repository.
Versionering af Nap-angular-sdk følger sem versioneringen af Nap-typescript-sdket.
For at lave et release opdateres versionen i workspacet (package.json) og for selve sdket (projects/nap-angular/package.json) hvorefter der køres en `npm i` for at opdatere package-lock.json.
Dernæst laves et tag i SVN på den følgende version manuelt som fx:
Code Block | ||
---|---|---|
| ||
svn copy https://svn.nspop.dk/svn/libraries/nap/nap-angular-sdk/trunk \
https://svn.nspop.dk/svn/libraries/nap/nap-angular-sdk/tags/release-1.0.0-rc.1 \
-m "Tagging the 1.0.0-rc.1 release of the 'nap angular sdk' project."
|
Det er vigtigt at tagget i svn stemmer overens med versionen i package.json og package-lock.json
Linting
Kør `npm run lint` for linting.
Eventuelle fejl skrives til STOUT.
Dokumentation
For at generere dokumentation til koden, kør "npm run doc". Dokumentation ligger i docs/ mappen.
Nap-react-sdk
Indeholder 2 "projekter".
- Det egentlige nap-react-sdk i src
Nap-react-sdk
Indeholder 2 "projekter".
- Det egentligt nap-react-sdk i src
- Her ligger en DEV.README i projektets rodfolder, specifikt egnet til udviklere, som beskriver de npm targets der opsat i projektet.
- Npm package mangeren bruger .npmignore til at ignore visse filer så som node_modules og example, når pakken skal bundles og publishes
- Et En eksempel implementering, som motionerer nap-react-sdk i example/src. Heri er injected en fakebridge i index.html. Dette er den egentlige test af SDKet, og der køres ingen unit tests. Sendte beskeder printes i console.log.
Funktionalitet
SDK'et sørger for at kalde createNAP() fra nap-typescript-sdket og dermed initialisere kontekstbroen.
Efterfølgende subscribes der på de forskellige messagestreams, hvor deres emits håndteres i React.state.
De forskellige subscriptions håndtag håndteres i react.useCallback
Dette pakkes ind en NAP-Context, som injectes til alle child elementer heraf.
Code Block | ||
---|---|---|
| ||
interface Context {
latestIncoming: NAPMessage | null;
latestError: NAPError | null;
postMessage: (message: NAPMessage) => void;
subscribe: (subscriber: NAPHostSubscriber) => void;
unsubscribe: (subscriber: NAPHostSubscriber) => void;
} |
Udviklingssetup og targets
Installer afhængigheder
Installer dependencies ved at køre npm install --registry https://nexus.nspop.dk/nexus/repository/nsp-npm/
Vær opmærksom på, at der findes en afhængighed til nap-typescript-sdk både for for sdket (package.json) og for eksemplet (example/package.json). Begge skal opdateres, for at anvende en nye version.
Byg
Kør "npm run build" for at bygge projektet. Dette giver et output i dist/ folderen. Brug "npm run build-prod" for et produktionsbyg.
CI
Jenkins filen beskriver jenkins pipelinen.
Releases og snapshots
Der kan laves snapshots og release-candidates fra jenkins til NSP npm repository.
Versionering af Nap-react-sdk følger sem versioneringen af Nap-typescript-sdket.
For at lave et release opdateres versionen i (package.json), hvorefter der køres en `npm i` for at opdatere package-lock.json.
Dernæst laves et tag i SVN på den følgende version manuelt som fx:
Code Block | ||
---|---|---|
| ||
svn copy https://svn.nspop.dk/svn/libraries/nap/nap-react-sdk/trunk \
https://svn.nspop.dk/svn/libraries/nap/nap-react-sdk/tags/release-1.0.0-rc.1 \
-m "Tagging the 1.0.0-rc.1 release of the 'nap react sdk' project."
|
Det er vigtigt at tagget i svn stemmer overens med versionen i package.json og package-lock.json
Development server
Kør "npm run start" for en byggeserver, der bygge sdk'et hver ændringer gemmes. Outputtet er i dist/ folderen.
Start en ny terminal og navigere ind i example/ folderen og køre "npm run start".
Derefter vil en dev server med live deployment af både eksempel-projektet og SDK'et køre på http://localhost:3000/.
Linting
Kør "npm run lint" for linting.
Eventuelle fejl skrives til STOUT.
Documentation
For at generere dokumentation til koden, kør "npm run doc". Dokumentation ligger i docs/ mappen.