1       Introduction

1.1          Purpose

This document describes the use of the web service that is provided by DDS Repository.

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

1.2          Reading Guide

The present document is directed towards developers and architects that will be using DDS Repository on NSP. It is assumed that the reader is familiar with Web services in addition to use of Den Gode Web Service (DGWS) and Security Token Service (STS).

1.3          Document History

1.4          Definitions and References

2       Usage of DDS Repository

DDS Repository provides an operation for extraction of document on the basis of document metadata. This document metadata is returned from the document sharing service when queried through use of the web service interface described in [DDS Registry Querying], as described in [DDS Registry Querying User’s Guide].

...

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

2.1          Preparation for Invocation of the DDS Repository

Before call to DDS Repository, it is the user system’s responsibility:

...

Note that the company registration number of the user system must be recorded in DDS Repository’s whitelist. Registration in the whitelist must be contracted with the DDS Repository system owner.

2.1.1      Obtaining document metadata-information for extraction

Before extraction of documents, metadata must be obtained for the documents to extract. For this purpose DDS Registry is used, described in [DDS Registry Querying] and [DDS Registry Querying User’s Guide].

...

For each document, that is desired extracted, a DocumentRequest structure is created which is added to the request. See additional details in section 3.3.

2.2          Invoking the DDS Repository

On call of the operations DocumentRepository_RetrieveDocumentSet on DDS Repository, the following must be completed:

1. A RetrieveDocumentSetRequestType is created (i.e. payload of DocumentRepository_RetrieveDocumentSet) which must be populated
2. Security-header is populated with ID card from STS
3. Medcom-header is created, including:
   1. A unique message ID must be assigned
   2. The medcom header’s flowID element must be assigned a unique session ID
   3. HSUID-header must be created and assigned values that respectively describe the person making the call and the patient

3       Examples of Call to DDS Repository

This section provides an example on how this service can be called.

At present, no .NET-example code for call to DDS Registry exists, but WSDL’s are available from which a Web service consumer can be created using Visual Studio’s Web service wizard combined with Seal.NET (see below).

3.1     Source System Obtains DGWS ID Card from STS

Below is outlined how a Java-based source system can use Seal.Java to obtain a STS-signed ID card.

...

DGWSHeaderWrapper signedHeaders = getValidDGWSHeaders(flowId);

3.2          User System Creates HSUID-header

// Create HSUID header
dk.nsi.hsuid._2013._01.hsuid_1_1.ObjectFactory objectFactory = new
  dk.nsi.hsuid._2013._01.hsuid_1_1.ObjectFactory();
HsuidHeader hsuidHeader = objectFactory.createHeader();


// Create assertion
AssertionType assertion = objectFactory.createAssertionType();
Date now = new Date();
Calendar calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"));
calendar.setTimeInMillis(now.getTime());
assertion.setIssueInstant(calendar);
assertion.setIssuer("  …  "); // Replace with name of my organization
assertion.setVersion(BigDecimal.valueOf(2.0));
assertion.setId(AssertionTypeId.HSUID);
hsuidHeader.setAssertion(assertion);


// Create attribute statement
AttributeStatement attributeStatement = objectFactory.createAttributeStatement();
attributeStatement.setId(AttributeStatementId.HSUIDdata);


// Create attribute for acting user (Danish: bruger)
dk.nsi.hsuid._2013._01.hsuid_1_1.Attribute actingUserAttribute = objectFactory.createAttribute();
actingUserAttribute.setName("nsi:ActingUserCivilRegistrationNumber");
actingUserAttribute.setAttributeValue(" … "); // Insert social security number without                                                                                                            //  hyphen for user
attributeStatement.getAttribute().add(actingUserAttribute);


// Create attribute for acting user’s organization
dk.nsi.hsuid._2013._01.hsuid_1_1.Attribute orgUsingAttribute = objectFactory.createAttribute();
orgUsingAttribute.setName("nsi:OrgUsingID");
// Here, the acting user’s organization is set to 12345678 in the SOR classification.
// Use name format "nsi:ynumber" and "nsi:skskode", respectively, for organization stated
// in classifications for general practitioner and hospital departments (respectively)
orgUsingAttribute.setNameFormat(SubjectIdentifierType.valueOf("nsi:sor"));
orgUsingAttribute.setAttributeValue("12345678");
attributeStatement.getAttribute().add(orgUsingAttribute);

… // The additional attributes in the HSUID-header are set with similar code

assertion.setAttributeStatement(attributeStatement);

The created hsuidHeader is now ready for use.

3.3     The User System Creates RetrieveDocumentSetRequestType

For the request is created a RetrieveDocumentSetRequestType structure containing identification of one or more documents.

// For each desired document, values are retrieved as described above
String homeCommunityId = " … ";
String repositoryUniqueId = " … ";
String documentUniqueId = " … ";


ihe.iti.xds_b._2007.ObjectFactory objFactory = new ihe.iti.xds_b._2007.ObjectFactory();
RetrieveDocumentSetRequestType request = objFactory.createRetrieveDocumentSetRequestType();
DocumentRequest documentRequest = objFactory.createRetrieveDocumentSetRequestTypeDocumentRequest();
documentRequest.setHomeCommunityId(homeCommunityId);
documentRequest.setRepositoryUniqueId(repositoryUniqueId);
documentRequest.setDocumentUniqueId(documentUniqueId);
request.getDocumentRequest().add(documentRequest);

3.4          User System Calls RetrieveDocumentSet

Creation of service and port:

...

if ("urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success".equals(
          response.getRegistryResponse().getStatus()) {
  for (RetrieveDocumentSetResponseType.DocumentResponse documentEntry:
          response.getDocumentResponse()) {
    if ("text/xml".equals(documentEntry.getMimeType()) { // handle text/xml
      byte[] documentBytes = documentEntry.getDocument();
      … // handle the bytes
    }
    else if (…) { … } // handle other MIME types
  }
}

3.5          Client Generation from WSDL

A Web service client can be generated based on the DDS Repository WSDL-file, see [DDS Repository Interface Description]. It is not given that the Web service client’s proxy classes can be generated based on a deployed service (using ?wsdl-extension on the service), as such calls are not necessarily supported.