Page History
Navitabs | ||||||
---|---|---|---|---|---|---|
| ||||||
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.
Table of Contents |
---|
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
Version | Date | Responsible | Description |
0.1 | 14.01.2013 | Systematic | Initial version |
0.9 | 27.02.2013 | Systematic | Prepared for testing in the demonstration project |
0.9a | 18.04.2013 | Systematic | Section 2.1.1: homeCommunityId is read from home-attribute. Release candidate 1 |
1.0 | 19.06.2013 | Systematic | Quality assured |
1.1 | 28.11.2014 | Systematic | National Patient Index (NPI) replaced by Document Sharing Service (DDS) |
1.4 Definitions and References
Definition | Description |
DDS | Document Sharing Service |
NSI | National eHealth Authority |
NSP | National Service Platform (within health care) |
SHAK | Hospital Department Classification |
SOR | Health service organization register |
STS | Security Token Service |
Reference | Description |
DGWS 1.0 | Den Gode Webservice 1.0 |
DGWS 1.0.1 | Den Gode Webservice 1.0.1 |
HSUID-header | Healthcare Service User Identification Header (SSE/11734/IFS/0018) |
IHE2 | IHE Current Technical Framework – Revision 8.0, Vol. 2a: Transactions (ITI1-ITI28) http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Rev8-0_Vol2a_FT_2011-08-19.pdf |
IHE3 | IHE Current Technical Framework – Revision 8.0, Vol. 2b: Transactions (ITI29-ITI64) http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Rev8-0_Vol2b_FT_2011-08-19.pdf |
DDS Registry Querying User’s Guide | DDS Registry Querying User’s Guide (SSE/11734/PHB/0037) |
DDS Registry Querying | DDS Registry Querying Interface Description (SSE/11734/IFS/0016) |
DDS Repository Interface Description | DDS Repository Interface Description (SSE/11734/IFS/0017) |
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:
- A RetrieveDocumentSetRequestType is created (i.e. payload of DocumentRepository_RetrieveDocumentSet) which must be populated
- Security-header is populated with ID card from STS
- Medcom-header is created, including:
- A unique message ID must be assigned
- The medcom header’s flowID element must be assigned a unique session ID
- 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.
...
Code Block |
---|
DGWSHeaderWrapper signedHeaders = getValidDGWSHeaders(flowId); |
3.2 User System Creates HSUID-header
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
// 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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
// 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:
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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.