Page History
...
The purpose of this document is to specify the web service interfaces provided by the national Document Sharing Service (DDS) for querying for document metadata.
Reading Guide
Wiki Markup |
---|
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 concern health professionals with Danish authorization listed in Danish Health Authority's authorization's register, it will be stated explicitly.
A system, that uses the web service(s) described in this document, is referred to as a {_}user system.{_} Note that there are particular responsibilities that the user system must fulfil, as described in section 1.5.
It is assumed that the reader understands the general use of SOAP-based web services, why technical terms such as SOAP, WSDL etc. is 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 also assumed that the reader understands the use of IHE XDS. |
Document History
Version | Date | Responsible | Description |
---|---|---|---|
0.1 | 24.2.2012 | Systematic | Initial version |
0.2 | 24.4.2012 | Systematic | Clarification of operations and their input/output |
0.9 | 14.5.2012 | Systematic | Clarifying and elaboration of web semantics (Section 4). |
1.0 | 29.6.2012 | Systematic | Section 4.7 updated. Name of the operation updated in sections 2.1 and 3.2.1. |
1.1 | 14.11.2012 | Systematic | Section 4.9 changed to SOAP v.1.1 |
1.2 | 27.2.2013 | Systematic | SOAP faults added to Table 4 in Section 4.7.1.1; Warning is changed to Error in section 4.7.2.1; Examples of request / response added in section 7. |
1.3 | 18.4.2013 | Systematic | SystemOwnerName corrected in section 4.1.1 |
1.4 | 19.06.2013 | Systematic | Register request/response deleted |
1.5 | 28.11.2014 | Systematic | National Patient Index (NPI) replaced with Document Sharing Service (DDS) |
1.6 | 05.05.2015 | Systematic | Code references has been updated due to name change from NPI to DDS. |
1.7 | 09.09.2016 | Systematic | Changed nsi:skscode to nsi:skskode and nsi:sorcode to nsi:sor to fit XML schema |
1.8 | 21.09.2016 | Systematic | Added details for user relation in HSUID |
1.9 | 10.11.2016 | Systematic | Added description of level 4 authentication required for healthcare professional user type, added missing error internal_error_treatmentrelation. |
1.10 | 25.11.2016 | Systematic | Added legal values for CitizenUserRelation in section 4.1.1. |
1.11 | 17.12.2016 | Systematic | Updated with information about GetDocument variant of Registry Stored Query. Added new WSDL URL in section 7. Added new examples in section 7. |
1.12 | 8.02.2017 | Systematic | Enforcement of level 4 authentication modified to level 3 for healthcare professional user type. |
1.13 | 13.06.2018 | Systematic | Migrated to NSPOP SVN |
...
Usage Scenarios for DDS Registry
Wiki Markup |
---|
DDS Registry performs the role of Document Registry \[ITI TF-1\] where document metadata registered about documents are stored in an XDS Registry associated with DDS Registry. DDS Registry does not perform the role of a Document Repository \[ITI TF-1\]. This role is performed by the source systems that register documents in DDS Registry.
A user system appears in the role of Document Consumer Actor \[ITI TF-1\] and can perform queries in the DDS Registry and find metadata registered for patients. This scenario is corresponds to ITI-18 \[ITI TF-2a\].
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\].
For the usage scenarios described in the following, it is the responsibility of the user system to verify the information given as input. This includes information on the user context, and, for instance, any relation between a citizen user and the patient. |
User System Queries for Document Metadata about a Citizen
...
User System Queries for Document Metadata for given Document Id
Wiki Markup |
---|
A user system may have retrieved one or more documents, for instance through the web service described in \[DDS Repository\]. In a retrieved document — depending on its type — there can be references to other documents. In cases where the reference contains the referenced document's document id and when the referenced document is (or may be) registered in the registry, the user system can query for document metadata given the document id.
A user system performs querying for metadata in DDS Registry for a given document id by using the GetDocuments variant of the Web service {_}DDSRegistry{_} and the operation {_}DocumentRegistry_RegistryStoredQuery_ of the web service {_}DDSRegistry{_}.
If the user is a health professional, consent checking influences what is returned as follows: when identified as a health professional for which patient consent blocks access, document metadata covered by the consent, are filtered out of the reply and a mark is added indicating that filtering has occurred due to consent-related restrictions. This marking can be interpreted as an indication that further document metadata than returned exists.
In addition, verification of the current treatment relationship between the health professional and citizen is initiated.
If the user is the citizen him or herself, all metadata is returned. A citizen user is also able to query another citizen's metadata if the user has a relation to the citizen in question.
It is the responsibility of the user system to provide the id of the patient for which the document id pertains. |
User System Queries for Document Metadata for given Document Id whilst Overriding Consents
...
Figure 1 SOAP message containing security header, MEDCOM header and HSUID header is used as message format.
Wiki Markup |
---|
The format of Security and Medcom-header are described in \[DGWS 1.0\] and \[DGWS 1.0.1\], while the format of the HSUID-header is described in \[HSUID-header\].
SOAP body contains IHE XDS Registry Stored Query AdhocQueryRequest and AdhocQueryResponse in request and response respectively. IHE XDS Registry Stored Query is described in \[ITI TF-2a\] section 3.18. |
Attributes in HSUID header applied for user who is a citizen
...
Processing of Request for Non-repudiation
Wiki Markup |
---|
Digital signing of replies is not supported. On request for non-repudiation, a fault-error message is returned as described in \[DGWS 1.0\]. |
Error Handling
Errors are handled in two ways, depending on their relation to the IHE XDS standard. For errors related to metadata querying, 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. Excluded from this distinction is, however, the warnings that are embedded in the response due to the withheld information due to consent. These are described in section 4.7.2.
...
Error codes and warnings embedded in the reply
Wiki Markup |
---|
See \[ITI TF-3\] section 4.2.4 for a description of how errors are embedded in a query response.
The following subsections describe the error codes and warnings embedded in the reply that are not defined in the IHE. |
Warning on withheld metadata
...
AdhocQuery variant FindDocuments
Wiki Markup |
---|
See description of content in AdhocQuery \[ITI TF-2a\].
The table below contains selected parts of AdhocQuery shown with emphasis on conceptual content. See \[ITI TF-2a\] section 3.18 for additional content, format etc. |
Element Slot, attribute-name [cardinality] | Description |
PatientId [1] | Unique identification of the person who is subject of the lookup. |
ClassCode [0..1] | E.g. prescription, discharge summaries, report. |
TypeCode [0..1] | E.g. discharge summaries, ultrasound report. |
PracticeSettingCode [0..1] | E.g. physician, laboratory. |
CreationTimeFrom [0..1] | If specified, the date from which the metadata must be created |
CreationTimeTo [0..1] | If listed, the lookup's upper limit on the time of metadata creation |
ServiceStartTimeFrom [0..1] | Period starting point from |
ServiceStartTimeTo [0..1] | Period starting date to must be greater than "Period starting point from" |
HealthcareFacilityTypeCode [0..1] | E.g. private clinic. |
EventCodeList [0..1] | E.g. colonoscopy, appendectomy. |
AvailabilityStatus [1] | Approved, Deprecated |
...
Anchor | ||||
---|---|---|---|---|
|
Wiki Markup |
---|
See description of content in AdhocQuery \[ITI TF-2a\].
The table below contains selected parts of AdhocQuery shown with emphasis on conceptual content. See \[ITI TF-2a\] section 3.18 for additional content, format etc.
Either $XDSDocumentEntryEntryUUID or $XDSDocumentEntryUniqueId shall be specified. This transaction shall return an error if both parameters are specified. |
Element Slot, attribute-name [cardinality] Selected parts of AdhocQuery (Logical content) | Description |
DocumentEntryEntryUUID[0..1] | Unique identification of the document entry in an XDS Registry. |
DocumentEntryUniqueId [0..1] | Unique, external identification of the document. |
Wiki Markup |
---|
See also \[Metadata\]. |
AdhocQueryResponse
Wiki Markup |
---|
See description of content in AdhocQueryResponse \[ITI TF-2a\].
AdhocQueryResponse is a collection of metadata that for each contains conceptual content as described below. |
Element-name [cardinality] | Description |
Author [1] | Author name |
AuthorInstitution [0..1] | Author affiliation |
AuthorPerson [0..1] | Healthcare person's authorization ID. |
AuthorRole [0..1] | The author's role. |
AuthorSpeciality [0..1] | Author's specialty. |
AvailabilityStatus [1] | Approved, Deprecated |
ClassCode [1] | Document class. |
Comments [0..1] | Commentary field (not free text) |
ConfidentialityCode [1..n] | Normal, Private marking of document. |
CreationTime [1] | Creation time |
EntryUUIdentifier [1] | - |
EventCodeList [0..n] | E.g. colonoscopy, appendix operation |
FormatCode [0..1] | - |
Hash [0..1] | - |
HealthcareFacilityTypeCode [1] | E.g. private clinic. |
HomeCommunityIdentifier [0] | Municipality not indicated |
LanguageCode [1] | da-dk |
LegalAuthenticator [0..1] | Authentication not used |
MimeType [1] | - |
PatientIdentifier [1] | Identical to PersonCivilRegistrationIdentifier. |
PracticeSettingCode [1] | E.g. physician, laboratory. |
RepositoryUniqueIdentifier [0..1] | Unique id for data source |
ServiceStartTime [1] | The period starting point |
ServiceStopTime [0..1] | Period end date |
Size [0] | Not used |
SourcePatientIdentifier [1] | Identical to PatientIdentifier |
SourcePatientInformation [0..1] | - |
Title [0..1] | Text field with title information. |
TypeCode [1] | Document type within the class. |
UniqueIdentifier [1] | ID on the document |
URIdentifier [1] | Unique link to the document in the source system. |
Wiki Markup |
---|
See also \[Metadata Profile\]. |
Governance
Documentation
In the DDS Registry-solution the interface between the actor-system 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:
...