1. Introduction
1.1. Purpose
The purpose of this document is to specify the Web service interfaces that Document Sharing Service (DDS) exposes for registration of metadata.
The Document Sharing Service is based on a standard IHE Document Registry. The Web service for registration offers the IHE-standard’s interface for registration extended with security features through Den Gode WebService.
1.2. Reading Guide
In the document, the concepts of authorization and authorized are used primarily in a security context, that is, in the understanding that a person or a system is authorized to use a given resource. If the concepts are applied towards health professionals with Danish authorization listed in Danish Health Authority’s authorization register, it will be stated explicitly.
It is assumed that the reader understands the general use of SOAP-based Web services, why technical terms such as SOAP, WSDL etc. are not clarified. Knowing Den Gode Webservice (DGWS) 1.0.1 described in [DGWS 1.0] and [DGWS 1.0.1] will facilitate comprehension considerably.
It is assumed that the reader understands the use of IHE XDS.
1.3. Document History
Version | Date | Responsible | Description |
|---|---|---|---|
0.1 | 1.3.2012 | Systematic | Initial version |
0.7 | 11.1.2013 | Systematic | Draft for demonstration project |
0.9 | 27.2.2013 | Systematic | Prepared for testing in the demonstration project |
1.0 | 19.6.2013 | Systematic | Quality assured |
1.1 | 28.11.2014 | Systematic | National Patient Index (NPI) replaced with Document Sharing Service (DDS) |
1.2 | 05.05.2015 | Systematic | Code references has been updated due to name change from NPI to DDS |
1.3 | 17.12.2016 | Systematic | Updated examples to new metadata profile and hsuid version in section 7 WSDL URL updated in section 7 |
1.4 | 6.10.2017 | Systematic | Added descriptions for ITI-57 UpdateDocumentSet. |
1.5 | 13.06.2018 | Systematic | Migrated to NSPOP SVN |
1.4. Definitions and References
The purpose of this section is to provide an overview of the definitions and documents references used in this document.
Definition | Description |
|---|---|
DDS | Document Sharing Service |
IHE | Integrating the Healthcare Enterprise |
NSI | National eHealth Authority |
NSP | National Service Platform (within health care) |
SHAK | Hospital Department Classification |
SOR | Health service organization register |
STS | Security Token Service |
XDS | Cross-Enterprise Document Sharing |
2. Usage Scenarios for DDS Registry
DDS Registry performs the role of XDS Registry and stores registered document metadata. A document source can use the DDS Registry to register metadata for documents concerning citizens. The document source itself performs the role of Document Repository [ITI TF-1] for retrieval and storage of the actual documents. It is not a requirement for registering document metadata, though, that the document source supports this role.
The DDS Registry is used in an XDS community, that is, by a set of actors agreeing to certain common rules. The document metadata handled by DDS Registry must 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 in an XDS community that adheres to metadata definitions defined in [Metadata Profile].
2.1. Document Source Registers Document Metadata for one or more Stable Documents
A document source may need to perform registration of document metadata concerning stable documents, i.e. documents with static content.
The need arises when:
- The document source has produced a new, stable document
- The document source wants to correct incorrect already registered document metadata
- The document source wants to deprecate document metadata, e.g. the document has been found to be incorrect and has been removed
A document source registers document metadata for stable documents in the DDS Registry by applying the web service operation DocumentRegistry_RegisterDocumentSet-b on the service DDSRegistry.
In this way, the following can be registered:
- document metadata concerning one or more documents
- updated document metadata for one or more already registered documents
- deprecation of document metadata for one or more documents, corresponding to deregistration of the documents.
Note that deprecation does not entail that document metadata is removed from DDS Registry, but rather the metadata is omitted on lookup of valid documents in DDS Registry.
The document source’s registration of document metadata concerning stable documents corresponds to the IHE transaction ITI-42 [ITI TF-2b].
2.2. Document Source Registers Document Metadata for one or more On-Demand Documents
A document source may need to perform registration of document metadata concerning on-demand documents, i.e. documents where the contents can be created dynamically and varies depending on the time of their retrieval.
This need arises when:
- The document source has made it possible to provide a new on-demand document, e.g. concerning a citizen and/or situation that the document source has not provided on-demand documents about previously
- The document source wants to correct incorrect already registered document metadata
A document source registers document metadata for on-demand documents in the DDS Registry by applying DocumentRegistry_RegisterOnDemandDocumentEntry, which is a web service operation on the service DDSRegistry.
The following can be registered:
- document metadata concerning one or more new documents
- updated document metadata for one or more already registered documents
- deprecation of document metadata for one or more documents, corresponding to deregistering of the documents.
The document source’s registration of document metadata concerning on-demand documents corresponds to the IHE transaction ITI-61 [ITI TF-2b].
2.3. Document Source Deprecates Existing Document Metadata
A document source may need to deprecate existing, registered document metadata concerning either stable or on-demand documents.
This need arises when:
- The document source wants to indicate that a document metadata entry is no longer relevant, e.g. when a patient appointment has been cancelled.
- An on-demand document source wants to indicate that it can no longer produce an on-demand document (at time of request).
Note that deprecation does not entail that document metadata is removed from DDS Registry, but rather the metadata is changes status. When querying parameters specify approved status only, the deprecated metadata is not included in the response on querying DDS Registry.
The operation corresponds to the IHE transaction ITI-57 [ITI TF-2b].
3. DDS Registry Registering Web Service
3.1. Reading Guide
In this section, the template below is used to document the operations that are provided.
Name: <operation headline> | |
|---|---|
Description: | Description of the purpose of the function. |
Input: | Input parameters. |
Output: | Output parameters. |
Error handling: | Description of error handling. Typically, reference is made to the general description of error handling in (section 4.7). |
Roles: | Description of necessary roles. |
Prerequisite: | Description of prerequisites that must be met for the function to complete successfully. |
3.2. Web Service – DDSRegistry
Web service that provides operations for registration of document metadata information in DDS Registry.
3.2.1. Operation – DocumentRegistry_RegisterDocumentSet-b
Name: DocumentRegistry_RegisterDocumentSet-b | |
|---|---|
Description: | Registers document metadata concerning one or more stable documents that the user (a document source) can provide. |
Input: | SubmitObjectsRequest. See section 3.3 for a description of the structure. Note that input and output types are identical to input and output types for RegisterOnDemandDocumentEntry. Accordingly, a distinction is made using SOAP Action: urn:ihe:iti:2007:RegisterDocumentSet-b |
Output: | RegistryResponseType |
Error handling: | See section 4.7. |
Roles: | |
Prerequisites: | The user system must be authenticated and authorized as described in section 4.2.1. |
3.2.2. Operation – DocumentRegistry_RegisterOnDemandDocumentEntry
Name: DocumentRegistry_RegisterOnDemandDocumentEntry | |
|---|---|
Description: | Registers document metadata concerning one or more documents that the user (a document source) can create and convey on-demand. |
Input: | SubmitObjectsRequest. See section 3.3 for a description of the structure. Note that input- and output-types are identical to input- and output-types for RegisterDocumentSet-b. Accordingly, a distinction is made using SOAP Action: urn:ihe:iti:2010:RegisterOnDemandDocumentEntry |
Output: | RegistryResponseType |
Error handling: | See section 4.7. |
Roles: | |
Prerequisites: | The user system must be authenticated and authorized as described in section 4.2.1. |
3.2.3. Operation – DocumentRegistry_UpdateDocumentSet
Name: DocumentRegistry_UpdateDocumentSet | |
|---|---|
Description: | Registers a submission set and association establishing that an existing document metadata entry should be deprecated. |
Input: | SubmitObjectsRequest. See section 3.4 for a description of the structure. Note that input and output types are identical to input and output types for the other registering operations. Accordingly, a distinction is made using the SOAP Action: urn:ihe:iti:2010:UpdateDocumentSet |
Output: | RegistryResponseType |
Error handling: | See section 4.7. |
Roles: | |
Prerequisites: | The user system must be authenticated and authorized as described in section 4.2.1. |
3.3. Registration of Document Metadata
Registration of document metadata in DDS Registry is performed using the operations described in sections 3.2.1 and 3.2.2 with a SubmitObjectsRequest structure having content corresponding to an XDS Registry Submission Request structure.
An XDS Registry Submission Request structure is briefly described below with emphasis on XDSSubmissionSet, XDSDocumentEntry and associations. For a thorough description of XDS Registry Submission Request refer to [ITI TF-3] section 4.1.
The requirements for metadata (including which and how they are specified) are dictated by the affinity domain. Which metadata informations that respectively may and must occur in registration must be agreed between the document source and NSI.
An XDS Registry Submission Request contains:
- An XDSSubmissionSet that encapsulates the other elements in a package. XDSSubmissionSet can hold metadata concerning the source system, e.g. an ID for the source system
- One or more XDSDocumentEntry. Each XDSDocumentEntry holds metadata concerning a document
- One Association per XDSDocumentEntry that links the XDSDocumentEntry and the XDSSubmissionSet (the association describes that the XDSDocumentEntry is included in the specific XDSSubmissionSet)
- Possibly multiple Associations per XDSDocumentEntry, if the XDSDocumentEntry replaces or is an addendum to an already registered XDSDocumentEntry
For each new document that is requested registered, the following is added to the XDSSubmissionSet:
- XDSDocumentEntry containing metadata for the document
- availabilityStatus is set to value Approved
- An Association that links the XDSDocumentEntry and the XDSSubmissionSet
For each document metadata to be updated, the following is added to the XDSSubmissionSet:
- XDSDocumentEntry containing the updated document metadata
- availabilityStatus is set to Approved-value
- An Association that links the XDSDocumentEntry and the XDSSubmissionSet
- An Association that describes that the updated document metadata replaces the preexisting. In the Association, the updated XDSDocumentEntry and pre-existing (to be invalidated) XDSDocumentEntry are identified by their ID, and associationType "urn:ihe:iti:2007:AssociationType:RPLC" is applied.
3.4. Deprecation of Existing Document Metadata
Deprecation of existing, approved document metadata in DDS Registry is performed using the operation described in section 3.2.3 SubmitObjectsRequest structure having content corresponding to an XDS Registry Submission Request structure.
As before, the requirements for metadata added to SubmissionSet objects described in the following are dictated by the affinity domain. Which metadata informations that respectively may and must occur in registration must be agreed between the document source and NSI.
An XDS Registry Submission Request contains one or more of the following pairs:
- An XDSSubmissionSet specifying which entity is the performing the registering and details on the patient for which the existing, approved DocumentEntry is about. XDSSubmissionSet can hold metadata concerning the source system, e.g. an ID for the source system.
- An Association of type UpdateAvailabilityStatus specifying the existing status and the new deprecated status as well as identifying the SubmissionSet and existing DocumentEntry.
4. DDS Registry Registration Web Service Semantics
4.1. Message Format
The Web service expects SOAP-messages, in which the SOAP-header contains a security-header and a MEDCOM-header, as required by DGWS 1.0.1.
Figure 1 As message format, SOAP-message containing security-header and MEDCOM-header is applied, while IHE XDS request is contained in SOAP body.
The format of the security and MEDCOM-header is described in [DGWS 1.0] and [DGWS 1.0.1].
SOAP body contains SubmitObjectsRequest and RegistryResponseType in request and response, respectively. This is the case for IHE XDS RegisterDocumentSet-b (ITI-42) and RegisterOnDemandDocumentEntry (ITI-61), described in [ITI TF-2b] section 3.42 and section 3.61, respectively. It is also the case for the IHE XDS UpdateDocumentSet (ITI-57) described in [Metadata Update] section 3.57.
4.2. Web Service Security
The security of this Web service is based on the SOSI integration pattern in Den Gode Webservice (DGWS). Authentication is carried out by a trusted third-party component on NSP (Security Token Service) and based on OCES digital certificates. By default, the service requires authentication with the STS component based on company signature (VOCES).
Additional security aspects, including authorization, integrity, confidentiality, availability and privacy considerations are enforced to only some extent by the technical service. The aspects that are not currently handled by the technical service will be handled in the service agreement, as specified by the data-responsible authority (NSI), which users of the service must agree to.
4.2.1. Authentication and authorization
4.2.1.1. Authentication and authorization of the user system
When the STS’ signature of the ID card is validated successfully, the user has been authenticated.
Authorization of user system is performed using a whitelist in the Web service based on information in the system-part of the ID card.
4.2.2. Timeout on ID card
A request with ID card is rejected when it has been more than 24 hours since the beginning of the ID card validity period.
4.3. Status Code and Flow Status
As required by DGWS 1.0.1, only HTTP-status codes 200 and 500 are used.
On HTTP status code 200, FlowStatus is always flow_finalized_succesfully.
4.4. Timeout on Web Service Operation
Timeout on Web service operations is equal to the default timeout on the NSP platform.
4.5. Session
Each request is handled in its own session.
No check is performed whether MessageID in the request has been received previously and no answer is guaranteed if a request with the same MessageID is received.
This deviates from DGWS 1.0.1 with regard to handling of retransmission.
4.5.1. Assignment and reuse respectively of flow ID
If the request contains a flow ID, it is reused in the reply and calls to other services that obey DGWS. If no flow id is provided, a unique flow ID will be created.
Handling of flow ID thus complies with DGWS 1.0.1.
4.6. Processing of Request for Non-Repudiation
Digital signing of replies is not supported. On request for non-repudiation, a fault-error message is returned as described in [DGWS 1.0].
4.7. Error Handling
Errors are handled in two ways, depending on their relation to the IHE XDS standard. For errors related to XDS metadata lookup, errors are embedded in the response as described in section 4.7.2. For errors in general, such as errors related to security, SOAP errors are returned as described in section 4.7.1.
4.7.1. SOAP errors
SOAP errors are returned with the components as described hereinafter. A structure has been chosen wherein both standard error codes as described in [DGWS 1.0] and Web service specific error codes can be returned.
<soap:Body> <soap:Fault> <soap:Code> <soap:Value>soap:Sender</soap:Value> </soap:Code> <soap:Reason> <soap:Text xml:lang="en">SAML Assertion has expired</soap:Text> </soap:Reason> <soap:Detail> <FaultCode xmlns="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">expired_idcard</FaultCode> </soap:Detail> </soap:Fault> </soap:Body>
Code listing 1 Structure of SOAP faults returned from the Web service operation. The example shows FaultCode used when the ID card has expired.
4.7.1.1. SOAP Fault Status Codes
For all Web service operations described in section 3 will be used SOAP Fault with FaultCode-values as listed in Table 1, originating in DGWS 1.0.1.
FaultCode | Description |
|---|---|
missing_required_header | One or more mandatory DGWS headers are missing in the enclosed message, e.g. ID cards, which always must be present. |
security_level_failed | Authentication or authorization error. Invalid choice of security level. |
invalid_idcard | Authentication or authorization error. Error in SOSI ID card. |
invalid_certificate | Authentication or authorization error. Certificate is not OCES or expired. |
expired_idcard | Authentication or authorization error. SOSI-id expired or too old for this Web service provider. |
not_authorized | User has insufficient rights to perform the Web service operation call. |
nonrepudiation_not_supported | The Web service provider system cannot perform a digital signature on the reply. |
Table 1 Applied FaultCode-values originating in DGWS 1.0.1
Additionally, Web service-specific FaultCode-values as listed in Table 2 are used.
FaultCode | Description |
|---|---|
invalid_date_timezone | An attached date has invalid format, cf. DGWS 1.0.1. |
internal_error_documentregistry | Internal error (call on IHE register failed). |
Table 2 Applied Web service-specific FaultCode-values
In WSDL, which describes the Web service(s) described in this document, these SOAP Fault status codes are not specified for every service (or operation).
4.7.2. Error codes and warnings embedded in the reply
On registration of metadata, the format and sample space for some metadata attributes are defined in the metadata definitions used by the XDS community, cf. the introduction to section 2.
If these attributes are not set or not set correctly, the registering of metadata fails. See [ITI TF-2b] section 3.42.4.1.2 for description of behavior on success and failure.
The following subsections describe how incorrect entries are indicated in the reply.
4.7.2.1. Errors on missing or incorrectly formatted metadata
If metadata is lacking, this will be indicated in the answer by the following RegistryError element in the reply’s RegistryErrorList element:
<rs:RegistryError codeContext="<description of the error>" errorCode="XDSRegistryMetadataError" severity="urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error"/>
The namespace-prefix for “urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0”, in this case rs, may have another value.
4.8. Web Service Input Validation
It is validated that:
- ID card in security header is valid and signed by STS and meets the additional conditions described in section 4.2
- Times in headers are given in Zulu time, as required by DGWS 1.0.1
- Required metadata are supplied in the request, see section 4.8.1
There will be performed
- No XML schema validation
- No validation that provided social security numbers are valid
4.8.1. Validation of metadata in request
In addition to validation of metadata as described in [ITI TF-3], additional validation of existence and format is performed for the sake of processing during future searches by DDS Registry queries. For the following metadata attributes, it is validated in particular that the form adheres to the metadata definitions used in the XDS community cf. the introduction to section 2:
- authorInstitution
- creationTime (this does not apply to documents registered with RegisterOnDemandDocumentEntry)
- patientId
4.9. Standards
DDS Registry Web service interface is based on the following standards:
- SOAP version 1.1
- Soap Fault version 1.1
- WS-I Basic Profile 1.1
- DGWS 1.0.1, with the exception of requirements regarding retransmission and control of reuse of message-ID as described in section 4.5, in addition to exception of structure used on errors as described in section 4.7.1.
For the sake of compliance with IHE XDS standard, the following is not met:
- OIO NDR [OIO-NDR]
- OIO WSDL [OIO-WSDL]
5. DDS Registry Web Service Schemas
This section aims to provide a general description of the most important elements in those XML schemas that together with WSDL files, define the Web service operations described in section 3.
5.1. SubmitObjectsRequest
See description of contents of SubmitObjectsRequest in [ITI TF-2b].
See also [Metadata Profile].
5.2. RegistryResponseType
See description of contents of RegistryResponseType in [ITI TF-2b].
See also [Metadata Profile].
6. Governance
6.1. Documentation
In the DDS Registry-solution, the interface between the actor-systems and the DDS Registry is versioned.
The interface specification constitutes the contract that defines how the systems involved must act.
The Interface specification consists of:
- the technical specification of schemas (documented by XSD files) and
- service descriptions (documented as WSDL files) and
- documentation of the semantic and functional meaning of the exchanged data (documented in this document).
6.2. Time-based Versioning
Versioning of resources takes place where it is not already defined by DGWS, the IHE standard or another Web service standard, by stating the release date on the form year/month as part of the URL that identifies the resource:
http://host/YYYY/MM/resource
7. WSDL, Schemas and Examples
WSDL file and XSD files are available in source code structure subfolder ddsservices \ client-types \ src \ main \ resources. These can also be downloaded from the following URL:
Note that the element X509Certificate is reduced in the request examples.