Introduktion

Formål

Denne guide har til formål at give anvendere af NAP SDKer et overblik over disse.

Anvendere er primært projektudviklere, derfor er denne guide målrettet disse.

På baggrund af følgende guides, er det muligt at komme hurtigt i gang anvendelsen af SDKerne. 

Nap-typescript-sdk

Nap-typescript-sdk er det basale SDK. Den udstiller en række metoder og interfaces som vil blive beskrevet i følgende:

NAP interface

En wrapper af kontekstbroen.

export interface NAP {
	fromHost$: Observable<NAPMessage>;
	toHost$: Subject<NAPMessage>;
	errors$: Observable<NAPError>;
	subscribe: (subscriber: NAPHostSubscriber) => void; 
	unsubscribe: (subscriber: NAPHostSubscriber) => void; 
	send: (message: NAPMessage) => void;
}

fromHost$: Beskeder af NAPMessages fra værtssystemet. Udstillet som en Observable.

toHost$: Send en NAPMessage til hosten. Denne er udstillet som et subject, som man kan skubbe beskeder til med next().

errors$: SDK fejl, udstillet som en Observable.

subscribe: Subscriber til NAPMessages fra værtsystemet. Det fungere på samme måde som med `fromHost$`, bare uden brug af observables.

unsubscribe: Unsubscribe af NAPMessages fra værtssystemet.

send: Send en NAPMessage - Det fungere på samme måde som to `toHost$`, bare uden brug af observables.

NAPMessage

Består af følgende felter, som er meget inspireret af FHIR / FHIRcast (https://fhircast.org/specification/Feb2020Ballot/),


export interface NAPMessage {
  date: string;
  id: string;
  event: NAPEvent;
}
export interface NAPEvent {
  type: NAPEventType;
  context?: FHIR.Context[];
}

Eventkatalog

Eventkataloget definerer de eventtyper, der kan sendes over NAP i en given version.

Dette eventkatalog lægger sig også op af FHIR / FHIRcast, hvilket betyder at eventet har følgende struktur:

Eventkatalog version 1

NAPEventTypeFunktionelle beskrivelse
SessionOpenStart en trusted session hvor brugerens SAMLassertion overføres
SessionCloseHvis en bruger ønskes lukkes ud. Alt state skal slettes på web-applikationen
PatientOpenDen brugervalgte patient journal.
PatientCloseDen brugervalgte patient journal lukkes.
SessionErrorHvis der sker en uventet fejl i gæstesystemet skal dette sendes til værtssystemet og vice versa.


Eksempel på at anvendelse af eventkatalog version 1: 

import { NAPEventCatalogue } from 'nap-typescript-sdk';
const sessionCloseEvent = NAPEventCatalogue.v1.SessionClose;


Utility funktioner

Nap-typescript-sdk indeholder derudover en række utility funktioner, som kan være brugbare til at hente værdier eller undgå stavefejl, når der skal laves NAPMessages.


Fhir-Value-getter

Funktioner, som gør det lettere at hente FHIR specifikke værdier ud af en NAPMessage. Disse kan bruges ved at importere namespacet FHIRValueGetter.

Eksempel på anvendelse Fhir-value-getter (mapping funktion)

Følgende eksempel mapper en napMessage til en SAMLassertion og PatientInfo.

import { FHIRValueGetter, NAPMessage, NAPPatientInfo } from 'nap-typescript-sdk';
const sessionToken = FHIRValueGetter.getSessionValue(napMessage);
const patientData: NAPPatientInfo = FHIRValueGetter.getSessionValue(napMessage);


Fhir-Value-Setter

Enums som gør det nemmere at lave NAPMessages indholdende data.

Eksempel på Fhir-Value-Setter

Følgende er et eksempel hvordan der sendes en fejlbesked.

import {NAPMessage, NAPEventCatalogue, FHIRValueSetter} from 'nap-typescript-sdk';
import { v4 as UUID } from 'uuid';

const napMessageSessionError: NAPMessage = {
  date: new Date().toISOString(),
  id: UUID(),
  event: {
    type: NAPEventCatalogue.v1.SessionError,
    context: [
      {
        resource: {
          resourceType: FHIRValueSetter.FHIRResourceType.Basic,
          code: {
            coding: [
              {
                code: NAPEventCatalogue.v1.SessionError,
                system: FHIRValueSetter.FHIRSystem.NAP,
              },
            ],
          },
          identifier: [
            {
              system: FHIRValueSetter.FHIRIdentifierSystem.NAPErrorMessage,
              value: 'This is my error message',
            },
            {
              system: FHIRValueSetter.FHIRIdentifierSystem.NAPErrorDescription,
              value: 'This is a longere description of the error message',
            },
          ],
        },
      },
    ],
  },
};

NapTypescriptSdk.send(napMessageSessionError)

Nap-angular-sdk

Hvis du ønsker bruge Angular som udviklingsværktøj, er dette SDK smartere at bruge, da det sørger for håndtering Angulars change detection zone for dig.

Da nap-angular-sdk er en angular specifik wrapper af nap-typescript-sdk, har den en peer dependency til hertil. 

Eksempel på implementing af nap-angular-sdk

Følgende eksempel sender en Session-Open besked og får en SAMLassertion tilbage:

import { NapAngularService } from 'nap-angular-sdk';
import { filterEvents, NAPEventCatalogue, NAPMessage } from 'nap-typescript-sdk';
import { v4 as UUID } from 'uuid';
import { NapAngularService } from 'nap-angular-sdk';
import { filterEvents, NAPEventCatalogue, NAPMessage } from 'nap-typescript-sdk';
import { shareReplay } from 'rxjs/operators';
import { v4 as UUID } from 'uuid';

export class MyComponent {
	
	// proxy for SAMLAssertion
	public session$: Observable<NAPMessage | undefined> = 
		this.napSDK.incomming$.pipe(
		filterEvents([NAPEventCatalogue.v1.SessionOpen, NAPEventCatalogue.v1.SessionClose]),
	);

	constructor(private napSK: NapAngularService) {

		//Construct an SessionOpen NAPMessage
		const napMsg: NAPMessage = {
		date: new Date().toISOString(),
		id: UUID(),
		event: { type: NAPEventCatalogue.v1.SessionOpen },
	};

		// Ask for the SAMLassertion in host
		this.napSDK.sendMessage(napMsg);
	}
}


Fuld implementation af eventkataloget ses i nap-reference-web her https://svn.nspop.dk/svn/components/nap/nap-reference-web/trunk/.

Nap-react-sdk

Hvis du ønsker at bruge React som udviklingsværktøj, er dette SDK smartere at bruge, da det sørger for håndtering af state for dig.

Da nap-react-sdk er en react specifik wrapper af nap-typescript-sdk, har den en peer dependency hertil. 

Eksempel på implementing af nap-react-sdk

Følgende eksempel viser hvordan man kan anvende nap-react-sdk til at vise og sende beskeder kunne se således ud:

import { NapContextProvider, NAPEventType, useNap } from 'nap-react-sdk';
import React from 'react';
import { v4 as UUID } from 'uuid';

const IncommingMessageComponent: React.FC = () => {
  const napContext = useNap()

  return <div> {JSON.stringify(napContext.latestIncomming)}</div>
}

const IncommingErrorsComponent: React.FC = () => {
  const napContext = useNap()
  return (
    <div >
      <p> Error received: {JSON.stringify(napContext.latestError)}</p>
    </div>
  )
}


const PostMessageComponent: React.FC = () => {
  const napContext = useNap()
  return (
    <button
      onClick={() => {
        napContext.postMessage({
          date: new Date().toString(),
          id: '123',
          event: { type: NAPEventType.SessionOpen }
        })
      }}
    >
      Send message
    </button>
  )
}

const App = () => {

  return (
    <>
      <NapContextProvider>
        <IncommingMessageComponent></IncommingMessageComponent>
		<IncommingErrorsComponent></IncommingErrorsComponent>
        <PostMessageComponent></PostMessageComponent>
      </NapContextProvider>
    </>
  )
}

export default Appp