Introduktion

Formål

This document describes the usage of the web services that are made available by consent services, which consists of two independent services: consent administration and consent verification.

...

Where the services overlap, common functionality is only described once.

Læsevejledning

This document is directed towards developers and architects that will be using consent service on NSP. It is assumed that the reader is familiar with Web services and the additional components on the NSP such as STS, in addition to knowing about Den Gode Web service (DGWS).

Dokument historik

Definitioner og referencer

Interface Beskrivelse

Snitfladerne for de to services er beskrevet i detaljer i dokumenterne MinSpærring - Verifikation Service Interface Beskrivelse og MinSpærring - Administration Service Interface Description.

I dette afsnit er kun de enkelte komponenter, der er nødvendige for at beskrive brugen af de to tjenester beskrevet.

Fælles

Security header

To call consent services, a user system must obtain a certificate and an ID card of level 3, issued by STS, and add these to the security header.

...

Endelig skal HSUID-headeren udfyldes med identifikation af den bruger, der udfører en given operation. Nogle af disse oplysninger genbruges muligvis i selve meddelelsen, og disse skal naturligvis være konsistente (jf. MinSpærring - Verifikation Service Interface Beskrivelse og MinSpærring - Administration Service Interface Description).

MinSpærring Verifikation

MinSpærring Verifikation har to operationer til at verificere samtykke fra en sundhedsfaglig: ConsentForUserCheck og ConsentForDataCheck.

...

Figur 2: Specikt samtykke på  ”Org” påvirker ikke overliggende organisation.

Those metadata whose IDs are returned from the service are the metadata the user has a positive consent to view.

De metadata, hvis id'er returneres fra tjenesten, er de metadata, som brugeren har et positivt De ID'er der returneres fra servicen er de data som anvenderen har samtykke til at få vist.

It is the user systems responsibility to ensure that the used IDs are unique so that they can be distinguished in the returned list. The service does not use the IDs for anything else than the return list.

Consent administration

Create- edit- and delete-methods all accept consent-objects (Consent) as parameters. The contents of a consent-object, in addition to which options are allowed, are shown in [Data Model] section 2.

All methods in the consent administration allows the citizen who creates a consent (or deletes/modifies) to be different from the citizen that the consent concerns.

This means that a citizen can create/edit/delete consents on behalf of another citizen as long as the citizen is authorized to do so.

Likewise, it is possible for a health professional to create a consent (but not edit or delete) on behalf of a citizen.

It is the user system’s responsibility that the user is authenticated and authorized to perform an action on behalf of another.

Examples of Calling Services

In this section, examples are provided on how one can use a Java-based user system to call the two services.

The code example is taken from the integration tests for the service and both method calls, variables and parameters come from this context.

The code might possibly not be able to compile or run its current form, as it is only intended as a guide on how to construct a call to the service.

Service Clients

Det er anvendersystemets ansvar at sikre, at de anvendte ID'er er unikke, så de kan skelnes på den returnerede liste. Tjenesten bruger ikke ID'erne til andet end returlisten.

MinSpærring Administration

Opret- rediger- og sletoperationer accepterer alle samtykke/spærring-objekter som parametre. Indholdet af et objektet vises i MinSpærring - Datamodel afsnit 2.

Alle metoder i administrationen af samtykke og spærringer tillader den borger, der opretter en registrering (eller sletter / ændrer), at være forskellig fra den borger, som registreringen vedrører.

Dette betyder, at en borger kan oprette / redigere / slette registretring på vegne af en anden borger, så længe borgeren har tilladelse til det.

Ligeledes er det muligt for en sundhedsfaglig at oprette et samtykke eller spærring (men ikke redigere eller slette) på vegne af en borger.

Det er brugersystemets ansvar, at brugeren er godkendt og autoriseret til at udføre en handling på vegne af en anden.

Eksempler

I dette afsnit gives eksempler på, hvordan man kan bruge et Java-baseret systemet til at kalde de to services.

Kodeeksemplet er taget fra integrationstestene for servicen, og begge metodekald, variabler og parametre kommer fra integrationstesten.

Koden kan muligvis ikke være i stand til at kompilere eller køre i sin nuværende form, da den kun er beregnet som en guide til, hvordan man opretter et kald til tjenesten.

Service Klienter

Der er udviklet en service klient til hver service. Klienterne kan findes som maven moduler.A service client has been developed for each service which can be found as Maven-components:

<dependency> 
	<groupId>dk.nsi.consentservices.verification</groupId> 
	<artifactId>consent-verification-client</artifactId> 
	<version><desired client version></version>
</dependency>

andog:

<dependency> 
	<groupId>dk.nsi.consentservices.administration</groupId> 
	<artifactId>consent-administration-client</artifactId> 
	<version><desired client version></version>
</dependency>

...

Oprettelse af service client

...

Disse serviceklienter konfigureres ved hjælp af en property fil, og klienten sørger for at få et gyldigt STS-token,

...

indsætte korrekte headers

...

osv.

Konfiguration af klienten sker via ClientConfig. ClientConfig's argument er navnet på den property fil der skal anvendes. Filen skal findes på classpath.

Koden nedenfor opretter en web service port til MinSpærring Verifikation

...

Properties for the client are set up through the ClientConfig-class that accepts the name of the properties file in which the configuration is found. The properties-file must be found on classpath.

...

:

Config config = new ClientConfig("VerificationClient").
     addRequiredKeys(ConsentVerificationService.CONFIG_KEY, ConsentVerificationService.CONFIG_ENDPOINT);
URL wsdl =
   new URL(config.getProperty(ConsentVerificationService.CONFIG_KEY));
String wsendpoint = config.getProperty(ConsentVerificationService.CONFIG_ENDPOINT);
ConsentVerificationServiceservice =
   new ConsentVerificationService (config, wsdl);
service.initialise();
ConsentVerification port = service.getConsentVerificationPort(wsendpoint);

...

Dette forudsætter, at en VerificationClient.properties-

...

fil kan findes på classpath

Lignende kode skaber en klient til MinSpærring Administration, klienten er bare klassen ConsentAdministrationService i stedet, og kaldet returnerer en web service port der er defineret i klassen ConsentAdministration.

Konfiguration

Den konfigurationsfil der gives til service klient skal definere en række properties som klienten anvender til at kommunikere med servicen.

...

Similar code create a client for the administration service, the client is just the class ConsentAdministrationService instead and the call results in a port defined in the class ConsentAdministration.

Properties

The properties file provided for the service client, must define a number of properties that the client uses to communicate with the service (the values must be adjusted so that they are relevant to the user system):

administration.wsdl.location = http://localhost:8080/consent-administration/service?wsdl
administration.service.url = http://localhost:8080/consent-administration/service
verification.wsdl.location = http://localhost:8080/consent-verification/service?wsdl
verification.service.url = http://localhost:9090/consent-verification/service
idcard.level = 3
idcard.system.name = TESTSTS
idcard.subject.id.type = medcom:cvrnumber
idcard.subject.id = 19343634
idcard.subject.name = JERNALDERBYENS VENNER
sts.test.mode = false
sts.endpoint = http://test1.ekstern-test.nspop.dk:8080/sts/services/NewSecurityTokenService
sts.token.expiry.threshold = 60
sts.keystore = jks/validVocesVault.jks
sts.keystore.password = !234Qwer
cert.expires.in.warning = 30

(the values are taken from the integration tests and must possibly be changed to function in another context).

The values for the security certificate must be corrected to the certificate one is using.

It is only necessary to provide one wsdl-location for each service.

Headers

Subsequently, service and port can be used to create the necessary headers, so the service can be called.

Værdierne er taget fra integrationstesten og skal tilpasses til det anvende systemet Det vil sige sti til certifikat, systemnavn osv.

Headers

Derefter kan service og port bruges til at oprette de nødvendige headers så det er muligt at kalde servicen.

Et flowID er angivet i headerenA flowID is provided with the headers, see section 2.1.

DGWSHeaderWrapper signedHeaders = service.getSignedHeaders(flowID);
Holder<Header> medcomHeader =
   new Holder<Header>(signedHeaders.getMedcomHeader());
HsuidHeader hsuidHeader = createHsuidHeader();

The values in the HSUID-header must be set manually by calling a method that creates the object (see [HSUID-header] for a description of the header contents).

The Medcom header is wrapped in a holder-object as it is an In/Out parameter.

Example of Call to Consent Verification

An example of call to ConsentForDataCheck on the verification service is shown here.

List<ConsentDataRegistration> consentData; // the list must be populated elsewhere

ConsentForDataCheck consentForDataCheck =
new ConsentForDataCheck(citizen, healthcareProfessional, onBehalfOf,
organization, consentData);

...

Værdierne i HSUID-headeren skal sættes manuelt ved at kalde en metode, der opretter objektet (se MinSpærring Healthcare Service User Identification Header Interface Description for en beskrivelse af headerindholdet).

Medcom-headeren er pakket ind i et holderobjekt, da det er en request/response-parameter.

Eksempel på kald af MinSpærring Verifikation

Et eksempel på kald af  ConsentForDataCheck er vist her.

List<ConsentDataRegistration> consentData; // the list must be populated elsewhere

ConsentForDataCheck consentForDataCheck =
new ConsentForDataCheck(citizen, healthcareProfessional, onBehalfOf,
organization, consentData);

ConsentForDataResponse consentForDataCheckResponse =
PORT.ConsentForDataCheck(consentForDataCheck, medcomHeader,

...

signedHeaders.getSecurityHeader(), hsuidHeader);

The element consentData has to be a list of ConsentDataRegistration-objects, see [Consent Administration Interface Description] and [Consent Verification Interface Description]:

The return value contains the IDs of the data elements that the user healthcareProfessional has consent from the citizen citizen to view.

Example of Call to Consent Administration

Shown here is an example of a call to ConsentAdd on the administration service (the contents of the actual consent-object is not shown here):

...

Elementet consentData skal være en liste over ConsentDataRegistration-objekter, se MinSpærring - Administration Service Interface Beskrivelse.

Servicen returnerer en liste af ID'er som den sundhedsfaglige har samtukke til at få vist.

Eksempal på kald af MinSpærring Administration

Her vises et eksempel på et kald til ConsentAdd i administrationsservicen. Indholdet af det faktiske samtykkeobjekt vises ikke her:

Consent consentItem = new Consent();
consentItem.setCitizenCPR(citizen);

...

consentItem.setPositiveConsent(positive);

...

consentItem.setValidFromDate(validFrom);

...

consentItem.setValidToDate(validTo);

...

consentItem.setWho(who);

...

consentItem.setWhat(what);

...

PORT.ConsentAdd(Arrays.

...

<Consent>asList(consentItem), medcomHeader,

...

signedHeaders.getSecurityHeader(), hsuidHeader);

Client Generation from WSDL

Klient generering fra WSDL

Det er også muligt selv at generere en klient baseret på en WSDLIt is of course also possible to use runtime WSDL-generation against a deployed service as a starting point.