Alle services der udbydes på NSP overholder den XML-baserede standard ”Den Gode WebService (DGWS)”. At designe og implementere en service der overholder denne profil, er ikke nødvendigvis en let opgave. Derfor er Seal.Net’s formål at indpakke DGWS specifikke detaljer, og abstrahere alle typer fra XML til objektform, for på den måde, at gøre det lettere for udvikleren at overholde standarden.

1.1. Support

Hvis du har brug for support, kan du lave en indberetning til Service desk. Her kan du også indrapportere fejl og oprette testdata.

1.2. Digitaliser.dk User Group

På digitaliser.dk er der oprettet en gruppe for Seal.Net. Der opfordres til at benytte forum funktionaliteten i denne gruppe som User Group, til at diskutere, informere om, og stille spørgsmål til Seal.Net. Gruppen vil desuden være opdateret med kode repository og andre relevante ressourcer. Gruppen findes her.

2. Relaterede komponenter

Seal.Net samspiller med en række NSP komponenter. Det kan være en god idé at sætte sig ind i disse, før man går i gang med at udvikle systemer, der benytter sig af Seal.Net. Disse komponenter er listet nedenfor, med links til deres egen ”Kom Godt i Gang Guide”.

2.1. STS (Security Token Service)

Det kræver autentificering at få adgang til NSP-komponenter. STS fungerer som en fælles komponent, som kan udstede adgangsgivende billetter til andre komponenter, så disse kun kræver simpel verifikation. STS – Signering og STS – Billetomveksling ”Kom Godt i Gang Guide”’erne forklarer yderligere.

2.2. NTS (NSP Test Service)

NTS er et værktøj til verificering af korrektheden af et DGWS SOAP-request. Hvis der opleves problemer med en service, kan et request i stedet blive sendt til NTS, som vil levere et uddybende svar, om hvad der måtte være galt med det pågældende request. NTS tjekker en række egenskaber ved requests, som f.eks. UTF-8 encoding og eksistensen af de obligatoriske DGWS header-elementer. Yderligere information kan findes her.

2.3. NGW (NSP GateWay)

NGW er en særlig udgave af den såkaldte SOSI-GW, som har til formål at sørge for at brugeren kun bliver afkrævet koden til sit medarbejdercertifikat én gang, på tværs af systemer. SOSI-GW og NGW – NSP Gateway ”Kom Godt i Gang Guide”’erne forklarer yderligere.

2.4. DCC (DeCoupling Component)

DCC’en fungerer som en WebService Gateway hvilket begrænser kravet til klienten, om kendskab til lokationen af den specifikke service. DCC -Afkoblingskomponenten ”Kom Godt i Gang Guide”’en forklarer yderligere.

3. Kode repository

Seal.Net koden kan hentes med Subversion, på følgende adresser:

...

Sourcekoden er offentligt tilgængelig på https://svn.nspop.dk/public/components/seal.NET/

4. Eksempler og demoer

Til at hjælpe med at komme i gang, er her en liste over relevante kode eksempler og demoer, som kan give en idé om hvordan man kan bruge Seal.Net.

4.1. MinLog Demo

Benytter MinLog registreringsservicen. Demoen opretter et id-kort, og logger ind via STS’en. Herefter registrerer den en log-besked i MinLog registreringsservicen. Koden kan downloades her.

4.2. FMK Demo

Benytter FMK servicen Medicinecard til at hente et medicinkort både vha. et SOSI ID-kort og NemId. Koden kan downloades her.

4.3. FMK 1.4.6 C# .NET Client

Et lille projekt, der viser et simpelt eksempel på kald af hent medicinkort fra FMK 1.4.6. Det kan køre ud af boksen, men følgende ting bør gøres:

...

Koden kan downloades her.

4.4. Trin-for-trin guide eksempel kode

Her (link mangler) finder du koden brugt til trin-for-trin guiden for Seal.Net.

5. Trin-for-trin opstarts-guide

Her er en trin-for-trin guide til hvordan man kommer i gang med Seal.Net. Guiden vil forklare hvordan man installerer Seal.Net via NuGet, hvordan man importerer en WSDL fil for FMK (Fælles Medicin Kort) servicen, hvordan man benytter WCF EndpointBehaviors til at validere beskeder, hvordan man laver et ID-kort, samt hvordan man laver et kald til servicen (FMK).

(Note: Denne guide vil benytte et ’Console Project’ i Visual Studio 2015, for at simplificere processen. Det er selvfølgelig muligt at lave en hvilken som helst anden type projekt, men ’Console Project’ anbefales. Koden der er brugt i guiden, findes under "Eksempler og Demoer")

5.1. Installer Seal.Net til projektet

Før vi kommer i gang, skal der installeres de nødvendige Seal.Net assemblies. Dette gøres via NuGet, enten via Package Browseren, eller ved at skrive følgende kommando i Package Manager Console:

...

Når installationen er fuldført, skulle der gerne være følgende assemblies i projektet:

5.2. Importér WSDL-filen for FMK (Fælles Medicin Kort) servicen

Vi vil nu importere WSDL-filen for den service der benyttes i resten af guiden. Denne guide benytter FMK version 1.4.6, som kan findes her.

Vælg ”WSDL med skemaer inline, version 1.4.6”. Udpak filen, og tilføj den til projektet via References > Add Service Reference. Skriv addressen til den udpakkede WSDL, og tryk Go. Giv servicen et navn (f.eks. MedicineCard) og tryk OK.

Servicen er nu tilføjet:

5.3. Lav et Request

For at kunne kalde denne nye FMK-service, kræver det at man medsender en Security, en Header samt en WhitelistingHeader.

...

Download her versionerne ”Test Bruger med CPR (gyldig)” og "DanID Test (gyldig)".

5.3.1. Security

En Security er det samlende element for sikkerhedsoplysninger i beskeden, som indeholder informationer om signering, token og kryptering.

For at lave en Security, kræver det at man først har et ID-kort.

5.3.1.1. IdCard

Seal.Net giver mulighed for at konstruere to forskellige SOSI IdCards (UserIdCard og SystemIdCard) til anvendelse i fagsystemer indenfor sundhedsvæesnet. Disse konstrueres vha. en SOSIFactory. I eksempel koden benyttes et UserIdCard til at hente et medicinkort, hvorefter et SystemIdCard benyttes til at sætte status af medicinkortet til "ikke ajourført".

5.3.1.1.1. UserIdCard

Først laves en SOSIfactory.

...

En Security kan ligeledes genereres ud fra DgwsTypes. Et eksempel på dette, kan findes i MinLog Demoen.

5.3.1.1.2. SystemIdCard

Genereringen af et SystemIdCard forgår stort set analogt til UserIdCard. I stedet benyttes dog nu et VOCES-certifikat i konstruktionen af SOSIFactory. Desuden kræver denne type IdCard færre informationer, og man er derfor også begrænset i hvilke actions der kan foretages med denne. Konstruktionen foregår som følger:

...

Guiden vil fokusere på brugen af UserIdCard'et, men eksempel koden indeholder et eksempel på kald med SystemIdCard.

5.3.1.1.3. IdCard fra OIOSaml assertion

Hvis man har en Saml2Assertion fra en Identity Provider (IdP), er det ligeledes muligt at konvertere denne til et IdCard via STS'en. Dette gøres vha. den såkaldte OioSamlAssertionToIdCardRequestDomBuilder, som genererer et request, som efterfølgende kan sendes til STS'en. Denne opbygges som følger:

...

Bemærk at der i forbindelse med SignIn til STS'en benyttes en anden URL end tidligere. Herefter er flowet fuldstændigt som med UserIdCard.

Vi ønsker nu at lave vores Header. Headeren indeholder tekniske og logistiske data, der vedrører forsendelse af hele meddelelsen. Til dette formål laves metoden MakeHeader()

...

MessageID er et unikt ID for denne ene besked, og bruges til at identificere dubletter ved gensendelse. Begge disse ID'er bør altså gemmes.

5.3.3. WhiteListingHeader

FMK foretager autorisation af klient systemer. Denne er whitelist-baseret, og skal sikre at kun software, der er godkendt til at benytte medicinkortet, kan kalde dets services. Denne Whitelisting er kun i FMK-regi, og er ikke generelt nødvendig for de fleste andre NSP komponenter. WhitelistingHeaderen skal indeholde følgende elementer:

...

                SystemVersion = WhitelistSystemVersion,

};

5.4. Lav et kald til FMK

Vi har nu alle de nødvendige dele til at kunne lave et request til FMK. Lav en metode GetMedCardRequest, hvor der laves en security, header og whitelistingheader. Lav herefter en client, og kald GetMedicineCardRequest_2015_06_01() som vist nedenfor:

...

GetMedicineCardResponse_2015_06_01 response = new GetMedicineCardResponse_2015_06_01(timingList, prescriptionReplicationStatus, responses);

5.5. Brug WCF EndpointBehaviors til at validere beskeder

I denne sidste del af guiden, vil det blive forklaret, hvordan man kan bruge WCF EndpointsBehaviors til at validere endpoints, validere beskeder (både indhold og headers), logging/tracing, eller modificere beskeder før de sendes videre.

5.5.1. Validering af Endpoints

Først laves en ny klasse, der implementerer interfacet IEndpointBehavior. I eksemplet er denne kaldt FmkMonitoringEndpointBehavior. Fra dette interface får man bl.a. en metode kaldet Validate, som tager et Endpoint. Denne metode vil blive kaldt lige før første kald til det givne endpoint. Her kan man så validere, at endpointet møder bestemte kriterier. I eksemplet, bliver det blot verificeret, at man ikke kalder andre hosts end de to FMK test miljøer.

...

client.Endpoint.Behaviors.Add(new FMKMonitoringEndpointBehavior());

5.5.2. Validering af beskeder

Vi vil nu kigge på hvordan man kan validere, logge, trace eller modificere beskeder, både før og efter de sendes videre fra systemet. Til dette, oprettes en ny klasse, som implementerer interfacet IClientMessageInspector. I eksemplet er denne kaldt FmkClientMessageInspector. Her får man adgang til to metoder; BeforeSendRequest, som vil kaldes inden et givent request sendes videre fra systemet. Og AfterReceiveReply, som vil kaldes som det første, når man modtager et svar.

...

WCF EndpointBehaviors er nu helt klar til brug.

5.5.3. SealMessageInspect & SealEndpointBehavior

Der er udviklet en ClientMessageInspector og EndPointBehavior specifikt til Seal.Net. Disse kan validere de mest basale DGWS-krav på udkomne og indgående beskeder. De er endvidere i stand til at udpakke fejl fra en service og lave dem til exceptions. De kan findes på Triforks SVN (som kræver speciel adgang):

...

Content

Space Tools

Versions Compared

Old Version 4

New Version 5

Key

1. Introduktion