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

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

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.

If a DocumentEntry is included but the document content is missing (e.g. no Document element with matching id), the Content Receiver should reject the submission and return an XDSMissingDocument error.

If a Document element is included with no associated DocumentEntry, the Content Receiver may reject the submission and return an XDSMissingDocumentMetadata error.

The Content Receiver may return the DocumentQueued warning to notify the Content Sender that a specific document will be processed later.

If the SubmissionSet intendedRecipient is populated, the Content Receiver should make reasonable efforts to determine whether each recipient can be notified, but may return success before confirming full receipt and processing by the intendedRecipients. If notification of an intendedRecipient is not possible, the Content Receiver may do any of the following:

• Fail the transaction and return the code UnknownRecipient or UnavailableRecipient as an error
• Succeed and return the code UnknownRecipient or UnavailableRecipient as a warning
• Succeed silently

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 may choose to accept 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.)

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 Role ID")
	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 Role ID")
	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 Role ID")
	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 Role ID")
	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