1       Introduction

1.1          Purpose

This document describes the use of the web service that is provided by DDS Registry for querying for document metadata.

The document provides an introduction to the general web service interface and an example of how it can be used in a specific consumer system.

The document metadata returned upon queries will adhere to a certain metadata definition, that is, be based on defined value sets, formats, encoding systems and so forth. The DDS Registry may be used with one of many metadata definitions, but currently, it is used with the one defined in [Metadata Profile].

1.2          Reading Guide

The present document is intended for developers and architects who want to use the DDS Registry for querying for document metadata available for a patient. Having such document metadata, the consumer system can then retrieve the documents described by the document metadata, as described in [DDS Repository Users’s Guide].

It is assumed that the reader is familiar with web services and the use of Den Gode Webservice (DGWS) and Security Token Service (STS).

1.3          Document History

1.4          Definitions and References

2       Use of DDS Registry

DDS Registry exposes an operation for querying for document metadata through a web service interface described in [DDS Registry Querying]. Querying is performed by using the standard IHE Cross-Enterprise Document Sharing (XDS), based on ebXML Registry Services (RS) and ebXML Registry Information Model (RIM). DDS Registry supports the querying variant FindDocument, which is one of several variants defined in IHE Technical Framework’s transaction 18, Registry Stored Query.

As described in [DDS Registry Querying], DDS Registry expects that the Registry Stored Query request contains additional headers consisting of:

• A Security-header
• A Medcom-header
• A Healthcare Service User Identification (HSUID) header.

The first two headers originate from Den Gode Webservice described in [DGWS 1.0] and [DGWS 1.0.1], while the third header is described in [HSUID-header].

The headers are added as implicit headers, i.e. by being described in the WSDL’s bindings without being added to the Registry Stored Query SOAP body-structure.

Changes to the IHE XDS standard WSDL are kept to a minimal to promote usage of Registry Stored Query to the greatest extent possible. Thus the operation payload is unchanged.

2.1          Preparing for Invoking DDS Registry

Before invoking the DDS Registry, it is the consumer system’s responsibility:

• to ensure that the prerequisites for use as described in [DDS Registry Querying] are met, e.g. that consent overriding[1] is performed only by health professionals authorized to do so.
• to obtain an ID-card of at least security level 3 issued by STS

Note that the consumer system’s company registration number which is embedded in the ID-card must be available on a DDS Registry whitelist. Addition to the whitelist must be arranged with DDS Registry system owner.

2.2          Invoking DDS Registry

When invoking the DDSRegistry’s DocumentRegistry_RegistryStoredQuery operation, the following must be implemented:

1. An AdhocQueryRequest structure must be populated, that is, the payload of DocumentRegistry_RegistryStoredQuery
2. Security-header is populated with the ID-card from STS
3. Medcom-header is created, including:
   1. Assignment of unique message-id
   2. Assignment of unique session id to the Medcom-header’s flowID-element
   3. HSUID-header is created, and assigned values that describe the person performing the call.

3       Examples of DDS Registry Invocations

This section provides an example of how this service can be invoked.

3.1          SEAL

Seal is an open source framework to support "Den Gode Webservice", including integration with a central identity service (IdP / STS), handling of federation certificates etc. Versions exists for Java and .Net.

3.1.1       Java framework

http://digitaliser.dk/group/374971

3.1.2       .NET framework

http://digitaliser.dk/group/375117

Currently, sample code has not been written to call DDS Registry from a .NET project, but there are WSDLs available such that one can generate a Web service consumer using Visual Studio's Web service wizard combined with Seal.NET.

3.2          Sample Code in Java from Integration Test

For automated testing of DDS Registry, a consumer using Seal.Java with the JAXWS-stack has been created. When writing code to call the service, the test code can be used as a starting point.

In the DDS Registry-codebase, the test code is located in the folder ddsservices/ddsregistry/integrationtest.

Calling the DDS Registry is initiated from the class DDSRegistryIT, while the call is implemented in the class DDSRegistryTestHelper.

The code example below comes the integration tests of the service and method calls, variables and parameters are taken from this context. The code may not compile or run in its present form. It is only intended as a guide to how to structure a call to the service.

Establishing service and port:

ClientConfig config = new ClientConfig("DDSClient").;
DGWSConsumer consumer = new DGWSConsumer(config);
URL wsdl = new URL(config.getProperty("ddsregistry.wsdl.location"));
DocumentRegistryService service = new DocumentRegistryService(wsdl, 
          new QName("urn:ihe:iti:xds-b:2007", "DocumentRegistry_Service"));
DocumentRegistryPortType port = service.getDocumentRegistryPortSoap12();

This presupposes that a DDSClient.properties file is found in classpath. In this file, the following properties must be defined:

ddsregistry.wsdl.location = http://localhost:8080/ddsregistry
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://pan.certifikat.dk/sts/services/SecurityTokenService
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 test and may have to be changed to function in another context!).

The values for the security certificate must be changed to the certificate you are using.

The method on the port can subsequently be called:

AdhocQueryRequest adhocQueryRequest = createAdhocQueryRequest();
 
DGWSHeaderWrapper validDGWSHeaders =   
   consumer.getValidDGWSHeaders(invocationValues.getFlowId());
Holder<Header> medcomHeader = new 
   Holder<Header>(validDGWSHeaders.getMedcomHeader());
AdhocQueryResponse response = port.documentRegistryRegistryStoredQuery(
                   adhocQueryRequest,
                   validDGWSHeaders.getSecurityHeader(),
                   medcomHeader,
                   invocationValues.getHsuidHeader());

3.3          Client Generation from WSDL

A web service client can be generated, based on the DDS Registry WSDL-file, see [DDS Registry Querying]. It is of course also possible to use runtime WSDL-generation against a deployed service.

[1] In Danish, overriding consents owned by the patient that would otherwise prevent access to the information is known as værdispring.