Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

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
Clarifying and elaboration of web semantics (Section 4).

0.9

14.5.2012

Systematic

Clarifying and elaboration of web semantics (Section 4).
Adding example (Section 7).

1.0

29.6.2012

Systematic

Section 4.7 updated. Name of the operation updated in sections 2.1 and 3.2.1.
Warning for detained metadata with undetermined positive consent (ex. Section 4.7.2.2) removed as the situation cannot occur.
Example in Section 7 is moved to separate file.

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

...

The Web service expects SOAP messages, where the SOAP header contains security header and Medcom-header as required by DGWS 1.0.1, in addition to a Healthcare Service User Identification (HSUID) header.

SOAP Envelope

SOAP Header

Security DGWS ID-card in SAML Assertion


MEDCOM Header


HSUID Header



SOAP Body

Payload depends on so-called Web service operation




Figure 1 SOAP message containing security header, MEDCOM header and HSUID header is used as message format.

...

Gliffy Diagram
macroId6adb749e-509a-4c01-aee9-2268c8ae615d
displayNameIDWS message
nameIDWS message
pagePin2

















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]
Selected parts of AdhocQuery (Logical content)

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
_Toc516653033
_Toc516653033
AdhocQuery variant GetDocuments





















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:

...