...

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 Description

The web service interfaces for the two services are described in details in the associated interface descriptions [Consent Administration Interface Description] and [Consent Verification Interface Description].

In this section, only the individual components that are necessary to describe the usage of the two services are clarified.

...

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.

For at kalde de to MinSpærring services  skal der anvendes et niveau 3 ID-kort udstedt af STS'en.

It should furthermore be ensured that one has a stated company registration number and that it is on the whitelist of authorized system. The two services use different whitelists, so the company registration number must be added to one or both, depending on which service one wants to call.

Det skal desuden sikres, at man har et angivet CVR-nummer og at dette er whitelisted i servicen. De to services bruger forskellige whitelisting tabeller, så CVR-nummer skal føjes til den ene eller begge, afhængigt af hvilken tjeneste man vil tilgå.

Medcom header

In the Medcom header it must be ensured that the flowID is set correctly. If consent services are called from another Web service with a Medcom header, the flowID must be retained from this call.

The Medcom header is returned from all method calls as it is set as an In/Out parameter with flowstatus updated to ’finalized successfully’.

HSUID header

Finally, the HSUID header must be filled in with identification of the user that performs a given operation. Some of this information is possibly reused in the body of the message and these must of course be consistent (cf. [Consent Administration Interface Description] and [Consent Verification Interface Description]).

...

I Medcom-headeren skal det sikres, at Flow-ID er sat korrekt. Hvis servicene kaldes fra et andet system der også anvender DGWS skal Flow-ID bevares fra dette opkald.

Medcom-headeren returneres fra alle operationer da den er indstillet som en ind / ud-parameter med flowstatus opdateret til 'afsluttet med succes'.

HSUID 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.

Formålet med ConsentForUserCheck-operationen er, at gøre det muligt for et brugersystem hurtigt at kontrollere, om en bruger har generelt samtykke eller generel spærring.

Hvis operationen vender tilbage positiv eller negativ, er det ikke nødvendigt at kalde yderlige for at afgøre om en sundhedsfaglig har lov til at tilgå data.

På et positivt svar antager brugersystemet, at brugeren har samtykke til at se sundhedsdata vedrørende den borger, som MinSpærring databasen er ansvarlig for. Omvendt antages det på et negativt svar, at borgeren har oprettet en spærring vedrørende adgang til data.

Operationen ConsentForDataCheck accepterer en liste over metadataelementer og filtrerer dem baseret på borgerens samtykke eller spærring.

------------------Hvis ID'erne er SHAK- eller DEA-koder, forsøger godkendelsesbekræftelse at slå de relaterede SOR-koder op, som vil blive sammenlignet med brugernes samtykke.

Derudover, hvis der er angivet et negativt dataspecifikt samtykke til en organisation, inkluderes de hierarkiske forældre til den organisation i dette samtykke. Medmindre der gives et specifikt positivt samtykke.

Dette illustreres i de følgende eksempler. Figur 1 viser borger, der har et generelt positivt samtykke, men som har givet et dataspecifikt negativt samtykke til organisationen "Org". Hvis identifikatorer fra alle fire organisationer sendes til bekræftelse af samtykke, viser diagrammet svaret, hvor rødt er et negativt samtykke, og grønt er et positivt samtykke.

The verification service has two methods to verify consent of a health professional: ConsentForUserCheck and ConsentForDataCheck.

...

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.

...

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 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

A service client has been developed for each service which can be found as Maven-components:

...

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

Creation of service client

These service clients are configured using a property file, and the client takes care of obtaining a valid STS-token, creating proper headers etc.

...

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):

...

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.

...

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.

...

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):

...

PORT.ConsentAdd(Arrays.<Consent>asList(consentItem), medcomHeader,
signedHeaders.getSecurityHeader(), hsuidHeader);

Client Generation from WSDL

It is of course also possible to use runtime WSDL-generation against a deployed service as a starting point.