Introduktion

Formål

Dette dokument er ment som en vejledning til anvendelse af den Nationale Afprøvningsplatform (NAP). 

På baggrund af dokumentet, er det muligt for leverandører af både lægepraksissystemer og afprøvningsprojekter, at udvikle systemer som integrerer med NAP. 

Kom i gang med NAP som projektudvikler

I følgende beskrives opsætningstrinene for at komme i gang med NAP platformen, hvis man vil oprette et ny projekt som skal ind i NAP'en. 

Krav til software:

Docker skal være installeret, da opsætningen foregår via docker-compose.

Et docker netværk kaldet nap_net skal laves (`docker network create nap_net`)

Komponenterne fra https://svn.nspop.dk/svn/components/nap/ skal hentes ned.

Start nap-host-java

OBS vi har ikke nogen distributionskanal for denne executeable endnu. Så foreløbigt: 

Kør `mvn install -P generateexecutable` og start den executable det bliver generate i /target.

Login ved at trykke på localhost og bruge default login credentials. Dette vil trække en SAMLassertion fra STS på test1. Du kan bruge denne i 30 min.

Skriv et cpr nummer på en test person (Eksempelvis "2708599967", som er et hyppigt anvendt test cpr nummer). Du kan nu browse rundt i fanerne.

For at fanen "afprøvningsplatformen" fungere, skal Nap-Compose og Nap-Lobby startes, som er de næste trin i opsætning.

Dette vil hoste lobbyen på http://localhost:8080/nap/lobby/web/, som er den url hosten kigger efter. 

Nap-Compose

Ideen med nap-compose er, at denne reverse proxy fungerer som en NSP loadbalancer med path rewriting.

For at starte denne reverse proxy køres `docker-compose up`. Dette vil åbne port 8080 på localhost.

Nap-Lobby

Nap-lobby er kataloget for de afprøvningsprojekter, der findes i nappen.

Kør `docker-compose up` fra compose/test. Med Nap-compose kørende, er denne nu tilgængelig for nap-host-java.

For at at Lobby skal vise nogen projekter skal den have forbindelse til Nap-admin.

Nap-admin

Kør `docker-compose up` fra compose/test. Med Nap-compose kørende, er denne nu tilgængelig for Lobbyen og projekter bliver vist

Ny implementering / Dit projekt

NAP projektet er ikke aktivt og NAP er derfor ikke pt. under support og vedligehold.
NAP er ikke opdateret til at understøtte MitID/NemLogin3 og det er derfor ikke længere
muligt at anvende den nuværende version på testmiljøerne.
En evt. genoptagelse af NAP projektet vil afhænge af konkret efterspørgsel.
Kontakt evt. Sundhedsdatastyrelsen ved interesse i NAP.

Introduktion

Formål

Dette dokument er en vejledning til anvendelse af den Nationale Afprøvningsplatform (NAP). 

På baggrund af dette dokument, er det muligt for leverandører af både lægepraksissystemer (LPS) og afprøvningsprojekter, at udvikle systemer som integrerer med NAP. 

Sammenhæng med øvrige dokumenter

Dette dokument er en del af den samlede dokumentation for NAP Platformen.

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 Platform - Design og Arkitektur beskrivelse.

Ønskes mere information omkring installationsvejledning til anvender kan findes på NAP Platform - Installationsvejledning.

Kom i gang med NAP som projektudvikler

For at oprette et nyt projekt i NAP er der 3 trin:

1. Hent og byg NapJavaHost
2. Udvikling af dit projekt
3. Publicering af dit projekt på test miljøerne

I følgende beskrives opsætningstrinene for at komme i gang med NAP platformen mere detaljeret.

Nap-host-java

Start med at bygge nap-host-java (NapJavaHost - kildekode) med java 13 jdk  via følgende kommando `mvn clean install`. Kør så efterfølgende applikationen med  `java -jar ./target/NapHostJava-fat.jar`.

Når nap-host-java åbnes, vil der blive præsenteret en login dialog.  

Login ved at trykke på test1 og bruge default login credentials. Dette vil trække en SAMLAssertion fra STS på test1, som kan bruges i 30 min. Når der er brugt et gyldigt login, vil man se et eksempel på et værtssystem. 

Applikationen viser 4 faner, hvor 3 af dem har screenshots som billeder (for at simulere et værtssytem), men den fanen "Afprøvningsløsning", indeholder en chromium browser som åbner nap-lobby-web.

Her fra kan brugerens tilgængelig projekter ses.

Indtast et cpr nummer på en test person (Eksempelvis "2708599967", som er et hyppigt anvendt test cpr nummer), herefter kan der browses rundt i fanerne.

Udvikling af dit projekt 

Der ligger et udviklingsprojekt som hedder "Developer", som Der ligger et Developer projekt, der hurtigt kan sætte gang i anvendelsen af NAP - platformen som udviklingsmiljø.

Hvis dette projekt trykkes på, vil nap-java-host åbne en, hvilken som helst applikation der hostes på lokalhost http://localhost:4600.

Konfigurer din løsning ind i NAP

Når en ny applikation skal ind på platformen, er der 2 steder platformen skal konfigureres før det fungerer.

Reverse proxy

Denne reverse proxy konfigureres ved at opdatere nap-httpd.conf.

<VirtualHost *:8080> ServerName nap

ProxyPass /nap/reference/web/services/main http://napreffacade:8080

ProxyPassReverse /nap/reference/web/services/main http://napreffacade:8080

ProxyPass /nap/reference/web http://naprefweb:8080

ProxyPassReverse /nap/reference/web http://naprefweb:8080

</VirtualHost>

Lav en konfiguration magen til ovenfor hvor reference og naprefweb udskiftes efter ønske.

Urlen skal dog passe med, den url der indsættes nedenfor

Database

For at dit projekt skal vises i lobbyen, skal projektet optræde i din lokale napadmindb.

Du kan gøre dette med sql inserts direkte eller opdatere compose/db/migration/V2__insert_data_localhost.sql med en kopi af nedenstående, som bare opdateres med dit nye info

...

insert into administration.Project (active, description, releaseDate, version, name, id) values (true, 'Dit udviklingsprojekt kan åbnes her.', '2018-11-30', '1.0.0', 'Nap Web Develop',  UuidToBin(UUID()));
insert into administration.Manifest (releaseDate, url, version, id) values ('2019-11-30', 'http://localhost:8080/nap/developer/web/', '1.0.0', UuidToBin(UUID()));
insert into WebApp (active, manifest_id, name, id, project_id) values (true, (select id from administration.Manifest where url LIKE 'http://localhost:8080/nap/developer/web/' ), 'Nap Web Developer version 0.0.1', UuidToBin(UUID()), (select id from administration.Project where name LIKE 'Nap Web Develop'));
insert into WebApp_cvr (WebApp_id, cvr) values ((select id from administration.WebApp where name LIKE 'Nap Web Developer version 0.0.1'), '20921897');
insert into Manifest_eventCatalogueVersions (Manifest_id, eventCatalogueVersions) values ((select id from administration.Manifest where url LIKE 'http://localhost:8080/nap/developer/web/' ), 1);

For at se eksempler på anvendelse af kontekstbroen til at kommunikere med hostsystemet henvises til NAP SDK - Guide til anvendere samt NAP Ref.Impl. - Guide til anvendere.

Publicering af dit projekt

Når dit projekt er klar til at blive testet i NSPs testmiljøer skal du have registret dit personlige / din virksomheds moces test certifikat som administrator i NAP.

Dette gøres ved at oprette en support sag på SDS´s Nationale Servicedesk.

Efterfølgende kan du bruge det certifikat til at logge ind på

NAP test1

hvorfra du kan tilføje metadata omkring dit projekt.

NapJavaHost understøtter tilføjelse af nye moces certifikater, hvis moces certifkaterne kun har 1 enkelt registreret autorisation.

Derfor kan du tilføje dit certifikat i nap-javahost-host, login på test1 i NapJavaHost, og se om projektet er tilgængeligt for dig og virker som forventet. 

Kom igang med NAP som værtssystem-/ LPS udvikler

I det følgende beskrives, hvordan man som værtssystem-/ LPS udvikler, integrerer NAP platformen i sit system. 

Integrationen med NAP

For at kommunikere med NAP'en, skal det givne værtssystem/LPS opsættes, således den kan lytte på specifikke beskeder fra SDK'et. 

I det nedenstående vil eksemplerne tage udgangspunkt i Java, og der kan derfor også tages udgangspunkt i nap-host-java, hvis der er brug for inspiration.

nap-java-host på SVN.

Opsætning af kommunikation med SDK.

For at kunne kommunikere med SDK'et, gøres brug af et Webview, som er en JavaFX komponent. Webviewet kan indlæse hjemmesider, samt der er mulighed for at indlejre javascript på den indlæste HTML side.

Det er vigtigt, at det er mulighed for at indlejre javascript i Webviewet, da det er den måde SDK'et fungere på. Endvidere skal Webviewet være kompatibel med en af de understøttede browser, som er beskrevet i NAP Platform - Yderligere dokumentation.

Læs mere om dette her NAP SDK - Guide til udviklere.

I nedenstående eksempel, tilføjes "NAPBridge" i variablen "NAP" på window, som er i global scope på den indlæste HTML side.

final JSObject window = (JSObject) webEngine.executeScript("window");
window.setMember("NAP", napBridge)

En implementering af NAP Bridge kan se således ud:

public class NAPBridge {
        private JSObject handler;

        /**
         * Transforming a JSON string into a NAPMessage and sending it to subscribers.
         * The handle to send messages to this host.
         * @param rawEventString A raw string representation of the NAP message
         */
        public void send(String rawEventString) {
            try {
                System.out.println(this.getClass().getName() + " send(): " + rawEventString);
                NAPMessage msg = objectMapper.readValue(rawEventString, NAPMessage.class);
                notifyListeners(msg);
            } catch (IOException ioException) {
                System.out.println(this.getClass().getName() + " " + ioException);
            }
        }

        /**

database og flyway skal således køres igen med `docker-compose up & docker-compose down`

Kom igang med NAP som værtssystem-/ LPS udvikler

I det følgende beskrives, hvordan man som værtssystem-/ LPS udvikler, skal integrerer NAP platformen ind i det respektive system. 

Der er ikke noget som skal opsættes ved siden af, hvis man benytter sig af produktions/test miljøet.

Integrationen med NAP

For at kommunikere med NAP'en skal det givne værtssystem/LPS opsættes, således den lytte på specifikke beskeder fra SDK'et. 

I det nedenstående vil eksemplerne tage udgangspunkt i java, og der kan derfor også tages udgangspunkt i nap-host-java, hvis der er brug for insipiration.

INDSÆT LINK 

Opsætning af kommunikation med SDK.

For at kunne kommunikere med SDK'et, gøres brug af et Webview, hvori man kan indlejre javascript på den indlæste HTML side, da det er den måde SDK'et fungere på. 

I nedenstående eksempel, tilføjes "NAPBridge" på "window" variablen, som er i global scope på den indlæste HTML side.

final JSObject window = (JSObject) webEngine.executeScript("window");
window.setMember("NAP", napBridge)

En implementering af NAP Bridge kan se således ud:

public class NAPBridge {
        private JSObject bridge;

        /**
         * Transforming a JSON string into a NAPMessage and sending it to subscribers.
         * @param rawEventString
         */
 Sets the bridge to act as a publiccallback.
 void send(String rawEventString) {
     * This handle will be used to send messages out from trythe {host.
         * @param handler JSObject representing the callback System.out.println(this.getClass().getName() + " send(): " + rawEventString);
  handle.
         */
        public      NAPMessage msg = objectMapper.readValue(rawEventString, NAPMessage.class);void setCallback(JSObject handler) {
            System.out.println(this.getClass().getName() + "  notifyListenerssetCallBack(msg);
: " +          } catch (IOException ioException) {handler);
                System.out.println(this.getClass().getName() + " " + ioException)this.handler = handler;
            }
        }

        /**
         * Sets the bridge to act as a callback.
         * @param bridge
         */
        public void setCallback(JSObject bridge) {
            System.out.println(this.getClass().getName() + " setCallBack(): " +  bridge);
}

Et JS objekt, som bridge variablen, gør at man kan eksekvere javascript metoder og undersøge javascript properties. 

Der er implementeret to metoder, som er send() og setCallback(), det er disse to metoder som SDK'et wrapper og kalder. 

Send(), er et håndtag til at sende beskeder til hosten, der gør brug af et internt subscribe pattern, som notificerer dem, som lytter. En implementering observer / listener, kunne se således ud:

private void handleBridgeCallBacks(NAPMessage napMessage) {
        switch (napMessage.getEvent().getNAPEventType()) {
            case PatientOpen:
   this.bridge = bridge;
        }
   }}

Et JS objekt, som bridge variablen er, gør at man kan eksekvere javascript metoder og undersøge javascript properties. 

Derudover er der implementeret to metoder, som er send() og setCallback(), det er disse to metoder som SDK'et kalder til. 

Send() gør brug af et internt subscribe pattern, som notificere dem som lytter og en implementering af de indkommende beskeder, kunne se således ud:

private void handleBridgeCallBacks(NAPMessage napMessage) {
sendCurrentPatient(txfCPR.getText(), napMessage.getDate(), napMessage.getId());
            System.out.println("Bridge got type NAPMessageType" + napMessage.getEvent().getNAPEventType()) break;
          switch (napMessage.getEvent().getNAPEventType()) {
  case WebAppSelected:
               case WebAppOpen: handleWebAppSelected(napMessage);
                try {break;
            case ProjectsRetrieved:
       WebApp webApp = this.getWebAppById(
      filterProjectsRetrievedAndSendMessage(napMessage);
                break;
      Configuration.getInstance().getNapAdminUrl(this.environment),
      case SessionClose:
                     FHIRResoureValueGetter.getWebAppIdhandleSessionClose(napMessage),;
                break;
            this.base64EncodedSAMLTokencase SessionError:
                    handleSessionError(napMessage);
                break;
    if (webApp != null) {
    default:
                System.err.println("Unexpected event type:  Platform.runLater(() -> this.webAppPane.openURL(webApp.getManifest" + napMessage.getEvent().getUrlgetNAPEventType()));
                    }
                } catch (ConnectException e) {
                    System.err.println("Kunne ikke oprette forbindelse til serveren");
                } catch (Exception e) {
                    e.printStackTrace();
                }
                break;
            case PatientOpen:
                sendCurrentPatient(txfCPR.getText(), napMessage.getDate(), napMessage.getId());
                break;
            case SessionOpen:
                sendToken(napMessage);
                break;
            case SessionClose:
                sendSessionClosed(napMessage);
                break;
            case SessionError:
                sendSessionError(napMessage);
        }
    }

Når der skal sendes en NAP besked, kan der så gøres brug af bridgen. Call() tager imod en string, som angiver hvilken metode man vil kalde, her "handle", da det er den variable som SDK'et lytter på.  Metoden sender en string representation af et JSON objekt, her af typen NAPMessage.

 if(napBridge.bridge != null) {
     this.napBridge.bridge.call("handle", eventRawJSONString);
 }

...

NAP Lobby Web

For at se de projekter der er tilgængelige, skal NAP Lobby Web integreres med det nuværende system. 

Start Nap lobby web på test

Start Nap admin

Derefter skal den ind i NAP'en og være som projekt. 

Inspiration kan bruges NAP Java host som simulere et LPS system. 

}
}

Når der skal sendes en NAP besked fra værts applikation, kan der så gøres brug af bridgen. Call() tager imod en string, som angiver hvilken metode man vil kalde, her "handle", da det er den variable som SDK'et lytter på. Metoden tager en string som parameter, hvori indholdet er en JSON struktur der repræsenterer en NAPMessage.

 if(napBridge.bridge != null) {
     this.napBridge.bridge.call("handle", eventRawJSONString);
 }

NAP Test Web

Projektet har til hensigt at teste værtssystemers integration af NAP. Der udstilles en test suite indeholdende en test, der sender en NAP besked for samtlige events.

Der er separate tests cases, som kan køres enkeltvis eller samlet. Den er derfor oplagt til at teste et værksystems implementering af eventkataloget.

Dette afprøvningsprojekt ligger både på test1 og test2 og kan åbnes fra lobbyen i det givne miljø.

Test1: https://test1-nap.insp.nspop.dk:8443/testweb/

Bemærk, at testene fejler, hvis ikke applikationen er indlejret i en host, som har implementeret NAP bridge.

NAP Lobby Web

Når kommunikationen er opsat med SDK'erne, er det nu klart til at vise alle de projekter der er tildelt.

De forskellige typer events kan læses på NAP SDK - Guide til anvendere.

For at se de projekter der er tilgængelige, skal NAP Lobby Web åbnes i det nuværende system.

Sikkerbrowser opstart

Sikker Browser opstart af Nap Lobby Web følger protokollen "Sikker browser opstart version 2".

Lignende implementationer kan ses i FMK-online og læses her https://wiki.fmk.netic.dk/lib/exe/fetch.php?media=fmk:fmko:guide_til_anvendere_af_sbov2_1_2.pdf og her for eGraviditet *Graviditetsmappe Web Facade - Guide til anvendere.

Anvendelse af Sikker Browseropstart i fagsystem

En forudsætning for at kunne tilgå Nap Lobby Web via Sikker Browseropstart er, at fagsystem har dannet et SOSI idkort, der repræsenterer brugerens login-session på fagsystemet. Trækning og signering af SOSI idkort er er ikke beskrevet her, men er dokumenteret i https://www.digitaliser.dk/resource/456411/artefact/SOSIprogrammersguide.doc?artefact=true&PID=456417.

Givet at fagsystemet har dannet et idkort for brugeren, er de nødvendige skridt for at tilgå Nap Lobby Web via Sikker Browseropstart i kort form:

1. Idkortet omveksles til en SAML assertion via et webservicekald til SOSI STS. 2 http://test1.ekstern-test.nspop.dk:8080/sts/services/Sosi2OIOSaml 
2. Den modtagne SAML assertion indlejres i et SAML Response.
3. Fagsystemet udstiller en webapplikation for brugeren, som brugerens browser dirigeres til.
4. Denne webapplikation sender et response til brugerens browser, som indeholder en HTML 5 FORM, som automatisk POST’es til FMK-online ved load. Denne FORM indeholder ovennævnte SAML assertion i base64 enkoded form. 
5. https://test1-nap.insp.nspop.dk:8443/lobby/saml/SAMLAssertionConsumer accepterer den POST’ede SAML assertion, og brugeren er nu logget ind.

Disse skridt er beskrevet i større detalje i det følgende.

Den relevante API er generelt beskrevet i https://www.digitaliser.dk/resource/456411/artefact/SOSIprogrammersguide.doc?artefact=true&PID=456417.

Desuden findes et implementerings eksempel i https://svn.nspop.dk/src/components/nap/nap-host-java/trunk/.

Omveksling af SOSI idkort til SAML-assertion

SOSI idkortet omveksles til en SAML-assertion via et webservice-kald til STS. Se https://www.nspop.dk/display/public/web/STS+-+Medarbejder-Billetomveksling for beskrivelse af omveksling fra SOSI idkort til SAML assertion (afsnit 7 beskriver overordnet den relevante omveksling, afsnit 8 indeholder links til eksempelkode: IDcardToOIOSAMLExample.java.

Der skal ved omveksling angives et ”audience”.

Den relevante værdi for audience er for NSPs testmiljøer en af følgende:

1. https://saml.test1-nap.insp.nspop.dk/lobby
   

2. https://saml.test2-nap.insp.nspop.dk/lobby

Indlejring af SAML-assertion i SAML-response

Den modtagne SAML assertion skal efterfølgende indsættes i en SAML Response xml-struktur. Det opbyggede SAML Response skal have følgende form.

saml:EncryptedAssertion elementet repræsenterer svaret fra omvekslingen af idkort til SAML assertion i STS, og er her vist i forkortet form.

Post af SAML-response fra webapplikation i fagsystem

For at tilgå Nap Lobby Web via Sikker Browseropstart, skal brugerens browser POST’e en HTML FORM med det opbyggede SAML Response til eGradivitet.

Dette kan fx opnås ved at fagsystemet udstiller en webapplikation, der kan returnere et response med et onload script, der POST’er formen. Dette response kan opbygges således:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="content-type" content="text/html, charset=utf-8" />
<title>SAML 2.0 POST</title>
</head>
<body onload='document.forms[0].submit()'>
<form action='https://test1-nap.insp.nspop.dk:8443/lobby/saml/SAMLAssertionConsumer' method='post'>
<input type='hidden' name='SAMLResponse' value='wrappedSamlResponse'/></form>
</body>
</html>

SAMLResponse-parameterens tilhørende value er her vist forkortet i form, men skal indeholde en base64 enkodet repræsentation af det opbyggede SAML Response.

Indholdet af action attributten afspejler hvilket miljø, der ønskes brugt (test eller produktion).

Action attributten kan starte med en af følgende url’er,

Test 1: https://test1-nap.insp.nspop.dk:8443/lobby/saml/SAMLAssertionConsumer

Test 2: https://test2-nap.insp.nspop.dk:8443/lobby/saml/SAMLAssertionConsumer

Opstart af andre projekter fra Nap Lobby Web

Samme procedure for Sikker browser opstart gør sig gældende for andre afprøvningsprojekter, fx Nap Reference Web,  hvor urlen slutter på /saml/SAMLAssertionConsumer. 

Når et projekt klikkes i Lobby sendes en besked af typen WebAppSelected se https://www.nspop.dk/display/public/web/NAP+SDK+-+Guide+til+anvendere hvor i audience og url er beskrevet.

Opstart som standalone

Lobbyen kan også åbnes om standalone på Test1: https://test1-nap.insp.nspop.dk:8443/lobby

Hvor det er muligt at logge ind med moces certifikater. Dette er egnet til projektadministratorer for at oprette et projekt ellere redigere et projektNOTE: INTRODUKTION TIL VISIONER OG HVORDAN DET SKAL BRUGES.