IHE ITI Technical Framework
The Final Text ITI Technical Framework is published here in HTML format and is no longer published as PDF. Trial Implementation supplements are available from the Volume 1 Table of Contents.

3.41Provide and Register Document Set-b [ITI-41]

This section corresponds to transaction [ITI-41] of the IHE Technical Framework. Provide and Register Document Set-b is used to transmit a set of documents and associated metadata. The documents and metadata might be stored for later retrieval or processed in some other way depending on the actor and workflow using the transaction.

3.41.1 Scope

The Provide and Register Document Set-b transaction passes a Document Submission Request (see ITI TF-3: 4.2.1.5 ) from a Content Sender to a Content Receiver.

3.41.2 Actor Roles

The Roles in this transaction are defined in the following table and may be played by the actors shown here:

Table 3.41.2-1: Actor Roles

Role:

Content Sender : A system that submits documents and associated metadata to a Content Receiver.

Actor(s):

The following actors may play the role of Content Sender:

Document Source, Metadata-Limited Document Source

Role:

Content Receiver : A system that receives a set of documents and associated metadata.

Actor(s):

The following actors may play the role of Content Receiver:

Document Repository, Document Recipient

Transaction text specifies behavior for each Role. The behavior of specific actors may also be specified when it goes beyond that of the general Role.

3.41.3 Referenced Standards

ebRIM

OASIS/ebXML Registry Information Model v3.0

This model defines the types of metadata and content that can be stored in an ebXML Registry, a basis for and subset of Document Sharing metadata.

ebRS

OASIS/ebXML Registry Services Specifications v3.0

This defines the services and protocols for an ebXML Registry, used as the basis for the XDS Document Registry

MTOM

SOAP Message Transmission Optimization Mechanism http://www.w3.org/TR/soap12-mtom/

This is a method for optimizing the transmission and/or wire format of SOAP messages.

XOP

XML-binary Optimized Packaging http://www.w3.org/TR/2005/REC-xop10-20050125/

This is a means of more efficiently of converting an XML Infoset with certain types of content into a stream of bytes for transmission.

See ITI TF-2: Appendix V for other referenced standards for SOAP encoding.

See ITI TF-3: 4.2 for other referenced standards for metadata element encoding.

3.41.4 Messages

Figure 3.41.4-1: Interaction Diagram

3.41.4.1 Provide and Register Document Set-b Request

The Provide and Register Document Set-b Request message is used to send patient specific healthcare information as a set of documents and associated metadata. Metadata enables the receiver to process the content of the message programmatically, without needing to understand the format or contents of the documents. For more details about metadata in the context of Document Sharing, see ITI TF-3: 4.

A Content Sender sends documents and associated metadata to a Content Receiver.

3.41.4.1.1 Trigger Events

The Content Sender, based on a human decision or the application of a certain rule of automatic operation, wants to submit document-related information to a Content Receiver.

3.41.4.1.2 Message Semantics

The Provide and Register Document Set-b Request message shall use SOAP 1.2 and MTOM with XOP encoding (labeled MTOM/XOP in this specification). Implementors of this transaction shall comply with all requirements described in: ITI TF-2: Appendix V : Web Services for IHE Transactions.

The use of MTOM/XOP is governed by the following rules:

  • The Content Sender shall generate the Provide and Register Document Set-b Request message in MTOM/XOP format.
  • The Content Receiver shall accept documents in a Provide and Register Document Set-b Request message in MTOM/XOP format.

The Provide and Register Document Set-b request message shall contain a Submission Request, as defined in ITI TF-3: 4.1.4 , and may contain documents. See ITI TF-3: 4.2.1.4 for a description of the ebRS/ebRIM representation of a Submission Request. The metadata requirements for this Submission Request are defined in ITI TF-3: 4.3.1 . The Submission Request shall contain exactly one DocumentEntry object for each Document contained in the request message, and vice versa.

If the associationType is RPLC, XFRM_RPLC, or IsSnapshotOf, the targetObject of the Relationship Association in the Submission Request shall be a DocumentEntry already in the Document Registry. All DocumentEntry objects in this Submission Request shall be Stable DocumentEntry objects and, therefore, will not be On-Demand DocumentEntry objects. Associations included in the Submission Request may reference On-Demand DocumentEntry objects that have been registered previously.

The sections in ITI TF-3: 4.1 specify the mapping of XDS concepts to ebRS and ebRIM semantics and document metadata. A full example of document metadata submission can be found online:  see ITI TF-2: Appendix W .

XML namespace prefixes used in text and examples below are for informational purposes only and are documented in ITI TF-2: Appendix V , Table V.2.4-1.

The requirements for the request message are:

  • the <wsa:Action> SOAP element shall contain the value urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b
  • the <soap12:Body> shall contain one <xds:ProvideAndRegisterDocumentSetRequest> element
  • the <xds:ProvideAndRegisterDocumentSetRequest> element shall contain:
  • one <lcm:SubmitObjectsRequest> element representing the Submission Request (see ITI TF-3: 4.2.1.4 for details of expressing a Submission Request).
  • one <xds:Document> element for each <rim:ExtrinsicObject> contained in the <lcm:SubmitObjectsRequest>
  • the <xds:Document> element shall:
  • have an @id attribute whose value matches the value of the corresponding rim:ExtrinsicObject/@id
  • contain the document using the xsi:base64Binary data type (Note: This is the logical representation of the document in the XML. The wire format may be different; see ITI TF-2: Appendix V.8)

A full XML Schema Document for the XDS types is available online: see ITI TF-2: Appendix W .

Below is an example of the SOAP Body for a Provide and Register Document Set-b Request message

     <soap12:Body>

        <xds:ProvideAndRegisterDocumentSetRequest>

            <lcm:SubmitObjectsRequest>

                <!-- Submission Request contents – See ITI TF-3: 4.2.1.4 -->

                <rim:RegistryObjectList>

                 <!-- Registry Metadata goes here -->

                </rim:RegistryObjectList>

            </lcm:SubmitObjectsRequest>

            <xds:Document id="Document01">SGVyZSBpcyBteSBkb2N1bWVudA==</xds:Document>

        </xds:ProvideAndRegisterDocumentSetRequest>

     </soap12:Body>

3.41.4.1.2.1 XDS Document Source Options

The XDS Document Source may choose to support options which are listed in ITI TF-1: Table 10.2-1b and described in the sections that follow it.

If the XDS Document Source supports the Document Replacement Option, it shall be able to generate replace semantics as defined in ITI TF-3: 4.2.2.2.3 .

If the XDS Document Source supports the Document Addendum Option, it shall be able to generate append semantics as defined in ITI TF-3: 4.2.2.2.1 .

If the XDS Document Source supports the Document Transformation Option, it shall be able to generate transformation semantics as defined in ITI TF-3: 4.2.2.2.2 .

If the XDS Document Source supports the Folder Management Option, it shall be able to generate folder semantics as defined in ITI TF-3: 4.2.1.3 and ITI TF-3: 4.2.2.1.5 .

If the XDS Document Source supports the Asynchronous Web Services Exchange Option, it shall be able to generate a WS-Addressing based Asynchronous Web Services request as defined in ITI TF-2: Appendix V.3.

Refer to ITI TF-1: 10.2.9 for support of the Basic Patient Privacy Enforcement Option.

3.41.4.1.2.2 XDR Document Source (informative)

There are multiple methods, e.g. XCPD, for an XDR Document Source to obtain a patient ID that is known by the Document Recipient. If possible, the Document Source should provide such a patient ID. In cases where it cannot, the Document Source shall submit objects using the requirements of an XDR Metadata Limited Document Source, which allows the submission to not contain a value for patientId.

3.41.4.1.3 Expected Actions

Upon receipt of a Provide and Register Document Set-b request, the Content Receiver shall process the request.

If a failure is detected during processing, the Content Receiver shall return an error response to the Content Sender, thus terminating this transaction; otherwise, the Content Receiver shall return a success response to the Content Sender. The various exception conditions and possible error or warning messages are given in the ebRS standard and in ITI TF-3: 4.2.4 Success and Error Reporting.

The Content Receiver shall be capable of accepting submissions containing multiple documents.

Note: The Content Sender may submit single documents or multiple documents depending on its needs.

A Content Receiver shall verify the received metadata as follows. For each DocumentEntry, the Content Receiver shall:

  • Verify the hash attribute, if present. If a received hash value differs from the calculated hash of the received document, the Content Receiver shall reject the submission and return an XDSRepositoryMetadataError error.
  • Verify the size attribute, if present. If a received size value differs from the octet count of the received document, the Content Receiver shall reject the submission and return an XDSRepositoryMetadataError error.

Also, for the SubmissionSet, the Content Receiver may:

  • Validate the sourceId. If the submission is not from a permitted Content Sender, the submission may be rejected and an error returned.
3.41.4.1.3.1 Document Recipient Expected Actions

In addition to the Expected Actions of all Content Receivers (described in the beginning of Section 3.41.4.1.3), a Document Recipient shall meet the following requirements.

A Document Recipient shall be able to interpret a submission without any context, such as knowledge of a prior submission.

The Document Recipient may validate the presence of metadata attributes. If the Document Recipient declares the Accepts Limited Metadata Option and the limitedMetadata attribute is present, such validation shall not exceed the requirements in the column labeled “XDR MS” (XDR Metadata-Limited Document Source) of ITI TF-3: Table 4.3.1-3. Otherwise, such validation shall not exceed the requirements in the column labeled “XDR DS” (XDR Document Source) of ITI TF-3: Table 4.3.1-3.

The Document Recipient may validate the patientId attribute in DocumentEntry, SubmissionSet, or Folder, if it is included. The Document Recipient may attempt to determine the the identity of the patient through other means. The Document Recipient may return an XDSUnknownPatientId error when it cannot identify the patient.

The following shall not cause rejection of a submission:

  • The submitted metadata includes Folders, and the Document Recipient cannot process the Folder-specific content. The response shall contain a PartialFolderContentNotProcessed warning and a textual description that Folder Content was not processed.
  • The submitted metadata includes document relationships, and the Document Recipient cannot process the relationship-specific content. For each unsupported association, the response shall contain a warning and textual description that the relationship semantics were not processed. The specific warning depends on the relationship: PartialAppendContentNotProcessed, PartialReplaceContentNotProcessed, PartialTransformContentNotProcessed, PartialTransformReplaceContentNotProcessed, or for the associationTypes, PartialRelationshipContentNotProcessed.

The received documents may be processed further according to the capabilities of the system. These capabilities are not specified by IHE.

3.41.4.1.3.2 Document Repository Expected Actions

In addition to the Expected Actions of all Content Receivers (described at the beginning of Section 3.41.4.1.3), a Document Repository shall meet the following requirements.

On receipt of a Provide and Register Document Set-b [ITI-41] request, the Document Repository shall, in order:

  • Validate and update select received metadata, as detailed below.

Make any received documents available for retrieval via the Retrieve Document Set [ITI-43] transaction.

Convey the updated metadata to the Document Registry via a Register Document Set-b [ITI-42] request.

Issue a Provide and Register Document Set-b [ITI-41] response.

If any error is encountered during processing of this request, either at the Document Repository or reported by the Document Registry, the Document Repository may revert any changes to the Document Repository data store. The Document Repository shall then terminate processing the transaction, and return an error response.

Before issuing the Register Document Set-b [ITI-42] transaction, the Document Repository shall update the received metadata as follows. For each received DocumentEntry, the Document Repository shall:

  • Add or replace the repositoryUniqueId attribute. The emitted value shall identify the Document Repository for retrieval of the received document.
  • Add a hash attribute if not present. The emitted value shall be the SHA1 hash of the received document.
  • Add a size attribute if not present. The emitted value shall be the octet count of the received document.

The Document Repository may add additional fields.

For each received DocumentEntry, the Document Repository may validate the uniqueId attribute. The submission may be rejected and an error returned if the uniqueId attribute matches a document within the Document Repository and the sizes or hashes of the two documents differ. The specific error returned depends on which attribute differed (XDSNonIdenticalSize or XDSNonIdenticalHash). The Document Repository shall not generate an error related to duplication if the uniqueId attribute matches a document within the Document Repository and the sizes and hashes of the two documents are the same. (The document may still be rejected by the Document Registry; see Section 3.42.4.1.4.)

Except as outlined above (and in Section 3.41.4.1.3 Content Receiver Expect Actions), the Document Repository shall not validate the presence or content of received metadata attributes.

The Document Repository shall ensure that received documents are available for retrieval via the Retrieve Document Set [ITI-43] transaction. If the document’s uniqueId is not already known to the Document Repository, the Document Repository shall:

  • Store the received document octet stream
  • Store the received DocumentEntry mimeType and uniqueId, and associate them with the received document octet stream.

Making the document retrievable before registering is necessary since a Document Registry may validate storage of a document before issuing the Register Document Set-b response; or, a Document Consumer may attempt to retrieve a document before the Register Document Set-b response is received.

The Document Repository shall issue a Register Document Set-b [ITI-42] request to the Document Registry with the (updated) received metadata. If the Register Document Set-b [ITI-42] response includes any errors or warnings, the Document Repository shall include all such errors and warnings in the Provide and Register Document Set-b [ITI-41] response.

3.41.4.2 Provide and Register Document Set-b Response

The Content Receiver shall send a Provide and Register Document Set-b Response message when the processing of a Provide and Register Document Set-b Request is complete.

3.41.4.2.1 Trigger Events

The request message has been received and processed by the Content Receiver

3.41.4.2.1.1 Document Repository Trigger Events

The Document Repository shall send the Provide and Register Document Set-b Response after receipt of the response to the corresponding Register Document Set-b [ITI-42] transaction from the Document Registry.

  • If the response to the Register Document Set-b [ITI-42] transaction indicates success, then the Document Repository shall send a successful response message.
  • If the response to the Register Document Set-b [ITI-42] transaction indicates failure, then the Document Repository shall send a failure response message.
3.41.4.2.2 Message Semantics

The Provide and Register Document Set-b Response message shall use SOAP 1.2 and MTOM with XOP encoding (labeled MTOM/XOP in this specification). Implementors of this transaction shall comply with all requirements described in: ITI TF-2: Appendix V : Web Services for IHE Transactions.

The use of MTOM/XOP is governed by the following rules:

  • The Content Receiver shall generate the Provide and Register Document Set-b Response message in MTOM/XOP format, even though there is no base64Binary content included.
  • The Content Sender shall accept the Provide and Register Document Set-b Response message in MTOM/XOP format.

The Provide and Register Document Set-b Response message shall carry the status of the requested operation. The response message may carry warning messages. If the requested operation fails, the response message shall carry at least one error message. The conditions of failure and possible warning and error messages are given in the ebRS standard and detailed in ITI TF-3: 4.2.4 Error Reporting. This transaction does not support a partial success response.

XML namespace prefixes used in text and in examples below are for informational purposes only and are documented in ITI TF-2: Appendix V , Table 2.4-1.

The requirements for the response message are:

  • the <wsa:Action> SOAP header shall contain the value urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-bResponse
  • the <soap12:Body> soap element shall contain one <rs:RegistryResponse> element

See ITI TF-3: 4.2.4.1 for examples of response messages.

3.41.4.2.2.1 XDS Document Repository Message Semantics

If the XDS Document Repository supports the Asynchronous Web Services Exchange Option (WS-Addressing based) and it receives a WS-Addressing based Asynchronous Web Services request, it shall respond as defined in ITI TF-2: Appendix V.3.

3.41.4.2.3 Expected Actions

The Content Sender should examine the status and messages returned and take appropriate action.

3.41.5 Security Considerations

Relevant XDS Affinity Domain security considerations are discussed in the XDS Security Considerations Section (see ITI TF-1: 10.7 ).

3.41.5.1 Audit Record Considerations

The Provide and Register Document Set-b transaction is either a PHI-Import event or a PHI-Export event, depending on actor, as defined in ITI TF-2: Table 3.20.4.1.1.1-1, with the following exceptions.

3.41.5.1.1 Document Source Audit Message
Field Name Opt Value Constraints

Event

AuditMessage/
EventIdentification

EventID M EV(110106, DCM, “Export”)
EventActionCode M “R” (Read)
EventDateTime M not specialized
EventOutcomeIndicator M not specialized
EventTypeCode M EV(“ITI-41”, “IHE Transactions”, “Provide and Register Document Set-b”)
Source (Document Source) (1)
Human Requestor (0..n)
Destination (Document Repository) (1)
Audit Source (Document Source) (1)
Patient (1)
SubmissionSet (1)

Where:

Source

AuditMessage/
ActiveParticipant

UserID M If Asynchronous Web Services Exchange is being used, the content of the <wsa:ReplyTo/> element. Otherwise, not specialized.
AlternativeUserID M the process ID as used within the local operating system in the local system logs.
UserName U not specialized
UserIsRequestor U not specialized
RoleIDCode M EV(110153, DCM, “Source”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Human Requestor (if known)

AuditMessage/
ActiveParticipant

UserID M Identity of the human that initiated the transaction.
AlternativeUserID U not specialized
UserName U not specialized
UserIsRequestor U not specialized
RoleIDCode U Access Control role(s) the user holds that allows this transaction.
NetworkAccessPointTypeCode U not specialized
NetworkAccessPointID U not specialized

Destination

AuditMessage/
ActiveParticipant

UserID M SOAP endpoint URI.
AlternativeUserID U not specialized
UserName U not specialized
UserIsRequestor M “false”
RoleIDCode M EV(110152, DCM, “Destination”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Audit Source

AuditMessage

AuditSourceIdentification

AuditSourceID U not specialized
AuditEnterpriseSiteID U not specialized
AuditSourceTypeCode U not specialized

Patient

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “1” (Person)
ParticipantObjectTypeCodeRole M “1” (Patient)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M not specialized
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The patient ID in HL7 CX format.
ParticipantObjectName U not specialized
ParticipantObjectQuery U not specialized
ParticipantObjectDetail U not specialized

Submission Set

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “2” (System)
ParticipantObjectTypeCodeRole M “20” (job)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M EV(“urn:uuid:a54d6aa5-d40d-43f9-88c5-b4633d873bdd”, “IHE XDS Metadata”, “submission set classificationNode”)
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The submissionSet unique ID
ParticipantObjectName U not specialized
ParticipantObjectQuery U not specialized
ParticipantObjectDetail U not specialized
3.41.5.1.2 Document Repository or Document Recipient audit message:
Field Name Opt Value Constraints

Event

AuditMessage/
EventIdentification

EventID M EV(110107, DCM, “Import”)
EventActionCode M “C” (Create)
EventDateTime M not specialized
EventOutcomeIndicator M not specialized
EventTypeCode M EV(“ITI-41”, “IHE Transactions”, “Provide and Register Document Set-b”)
Source (Document Source) (1)
Destination (Document Repository or Document Recipient) (1)
Audit Source (Document Repository or Document Recipient) (1)
Patient (1)
SubmissionSet (1)

Where:

Source

AuditMessage/
ActiveParticipant

UserID M If Asynchronous Web Services Exchange is being used, the content of the <wsa:ReplyTo/> element. Otherwise, not specialized.
AlternativeUserID U not specialized
UserName U not specialized
UserIsRequestor U not specialized
RoleIDCode M EV(110153, DCM, “Source”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Destination

AuditMessage/
ActiveParticipant

UserID M SOAP endpoint URI
AlternativeUserID M the process ID as used within the local operating system in the local system logs.
UserName U not specialized
UserIsRequestor M “false”
RoleIDCode M EV(110152, DCM, “Destination”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Audit Source

AuditMessage/
AuditSourceIdentification

AuditSourceID U not specialized
AuditEnterpriseSiteID U not specialized
AuditSourceTypeCode U not specialized

Patient

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “1” (Person)
ParticipantObjectTypeCodeRole M “1” (Patient)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M not specialized
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The patient ID in HL7 CX format.
ParticipantObjectName U not specialized
ParticipantObjectQuery U not specialized
ParticipantObjectDetail U not specialized

Submission Set

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “2” (System)
ParticipantObjectTypeCodeRole M “20” (job)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M EV(“urn:uuid:a54d6aa5-d40d-43f9-88c5-b4633d873bdd”, “IHE XDS Metadata”, “submission set classificationNode”)
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The submissionSet unique ID
ParticipantObjectName U not specialized
ParticipantObjectQuery U not specialized
ParticipantObjectDetail U not specialized