3.42 Register Document Set-b [ITI-42]
This section corresponds to transaction [ITI-42] of the IHE IT Infrastructure Technical Framework. Register Document Set-b is used to register a set of document-associated metadata.
3.42.1 Scope
The 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.42.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.42.2-1: Actor Roles
| Role: |
Content Sender : A system that submits a document metadata to a Content Receiver. |
| Actor(s): |
The following actors may play the role of Content Sender:
|
| Role: |
Content Receiver : A system that receives document metadata. |
| Actor(s): |
The following actors may play the role of Content Receiver:
|
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.42.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 |
| HL7V2 | HL7 Version 2.5 |
|
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.42.4 Messages
Figure 3.42.4-1: Interaction Diagram
3.42.4.1 Register Document Set-b Request
The Register Document Set-b Request message is used to register patient-specific healthcare documents through the use of 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.
The Content Sender sends metadata for a set of documents to the Content Receiver.
3.42.4.1.1 Trigger Events
The Register Document Set-b Request message is triggered when a Content Sender wants to register metadata for a set of documents it holds. These documents may have been stored in the Document Repository by a Document Source (using the Provide and Register Document Set-b transaction [ITI-41]) or generated internally by an Integrated Document Source/Repository.
3.42.4.1.2 Message Semantics
The Register Document Set-b Request message shall use SOAP 1.2 and Simple SOAP. Implementors of this transaction shall comply with all requirements described in: ITI TF-2: Appendix V : Web Services for IHE Transactions.
The Register Document Set-b Request message shall contain a Submission Request, as defined in ITI TF-3: 4.1.4 .
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.
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 .
A full example of document metadata submission can be found online: see ITI TF-2: Appendix W .
XML namespace prefixes used in text and in examples below are for informative 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:RegisterDocumentSet-b
- the <soap12:Body> 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).
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 Register Document Set-b Request message
<soap12:Body>
<lcm:SubmitObjectsRequest>
<!-- Submission Request contents – See ITI TF-3: 4.2.1.4 -->
<rim:RegistryObjectList>
<!-- Registry Metadata goes here -->
</rim:RegistryObjectList>
</lcm:SubmitObjectsRequest>
</soap12:Body>
If the Content Sender 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.
3.42.4.1.2.1 Integrated Document Source / Repository Message Semantics
The Integrated Document Source / Repository 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 Integrated Document Source / Repository 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 Integrated Document Source / Repository 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 Integrated Document Source / Repository 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 Integrated Document Source / Repository 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 Integrated Document Source / Repository supports the Basic Patient Privacy Enforcement Option, it shall comply with the requirements as described in ITI TF-1: 10.2.9 .
If the Integrated Document Source/Repository supports the Delayed Document Assembly Option:
- It shall be able to register a Stable Document Entry with the following attribute values
- size =
0(zero) - hash =
da39a3ee5e6b4b0d3255bfef95601890afd80709(SHA1 hash of a zero length file). - The required creationTime attribute should be equal to the time that the information to be included in the document content was produced.
When the Integrated Document Source/Repository registers the document, it shall internally mark the document contents that will be assembled when a subsequent Retrieve Document Set [ITI-43] transaction is received containing the uniqueID of the registered Stable Document Entry.
3.42.4.1.3 Expected Actions
Upon receipt of a Register Document Set-b Request message, the Document Registry shall:
- Perform metadata validations
- Store all IHE-defined metadata attributes received so that it is available to return in responses to future queries.
- Return a response message giving the status of the operation.
If the Document Registry rejects the metadata, it shall:
- Return an error including at least one error message in the response. For a complete list of applicable codes, refer to ITI TF-3: Table 4.2.4.1-2.
- Roll back any changes made.
3.42.4.1.3.1 Atomicity of Submissions
XDS Submission requests shall be atomic operations. If any part of the Submission Request processing fails, the entire transaction shall fail and no changes result.
No result of a Submission Request shall be made available until the atomic operation has successfully completed.
3.42.4.1.3.2 Extra Metadata
The Document Registry may save extra metadata attributes.
- If the Document Registry saves the extra metadata attributes, it shall include that metadata in later query responses.
- If there are extra metadata attributes in the Submission Request and the Document Registry does not save them, the Document Registry shall include the XDSExtraMetadataNotSaved warning in its response, as described in ITI TF-3: 4.2.3.1.6
- Document Registry Actors that do not support the Reference ID Option may treat referenceIdList as a non-IHE-defined metadata attribute.
The Document Registry shall verify that extra metadata attributes conform to the requirements in ITI TF-3: 4.2.3.1.6 .
3.42.4.1.3.3 Enforcement of Attributes
The Document Registry shall validate the Submission Request objects and attributes as specified in ITI TF-3: 4.2 and 4.3.1. In addition, the following constraints apply.
3.42.4.1.3.3.1 DocumentEntry.uniqueId
The Document Registry shall reject the message and return an error if the uniqueId attribute matches the uniqueId attribute of a DocumentEntry within the Document Registry and the size attributes or hash attributes of the two DocumentEntry objects differ.
If the uniqueId, size, and hash attributes of a received DocumentEntry match those of a DocumentEntry already within the Document Registry, processing of the submission shall continue without an error. Thus, multiple registered DocumentEntry objects can have the same uniqueId attribute value (as long as all the size and hash attributes are the same).
Note: The Document Entries may reference the same instance of the document or may reference different (identical) copies of the document (for example, stored on different Document Repositories).
3.42.4.1.3.3.2 patientId Attributes
Values of DocumentEntry.patientId, Folder.patientId, and SubmissionSet.patientId shall be verified against the patient identifiers received in the Patient Identity Feed [ITI-8] indicating that they are registered with the Patient ID Domain of the Affinity Domain. This validation requirement does not apply to DocumentEntry.sourcePatentId.
All objects in the Submission Request (DocumentEntry, Folder and SubmissionSet) shall have the same patientId.
The value of the patientId attribute of a DocumentEntry object shall match the value of the patientId attribute of any Folder that it is a member of. This implies that all DocumentEntry objects in a Folder have the same patientId.
When the Submission Request includes a Document Relationship Association, both DocumentEntry objects referenced by the Association shall have the same patientId.
3.42.4.1.3.3.3 Coded Attributes
The XDS Affinity Domain may allow only a finite set of values for a given coded attribute conforming to ITI TF-3: 4.2.3.1.2 or may not restrict the values at all. If the XDS Affinity Domain allows only a finite set, the Document Registry shall constrain the value to those allowed by the XDS Affinity Domain.
The Document Registry shall not constrain the displayName.
Note: In this section, "value" refers to the combination of a codeSystem and code.
3.42.4.1.3.3.4 DocumentEntry.mimeType
The value of the DocumentEntry.mimeType shall be constrained to those allowed by the XDS Affinity Domain.
3.42.4.1.3.3.5 DocumentEntry.availabilityStatus
The Document Registry shall set the availabilityStatus of all newly added DocumentEntry objects to Approved.
3.42.4.1.3.3.6 DocumentEntry.serviceStartTime and DocumentEntry.serviceStopTime
If the serviceStartTime and serviceStopTime attributes are both populated for a Document Entry in the Submission Request, the Document Registry shall verify that the serviceStartTime is before or equal to the serviceStopTime.
3.42.4.1.3.3.7 SubmissionSet.uniqueId
The Document Registry shall verify that the SubmissionSet.uniqueId is not used as the uniqueId for any existing object in the registry (DocumentEntry, SubmissionSet, or Folder).
3.42.4.1.3.4 Folder Membership
When the Submission Request includes an FD-DE HasMember Association, which identifies a Document Entry as a member of a Folder, the Document Registry shall verify that both the Document Entry and Folder have a status of Approved.
3.42.4.1.3.5 Document Relationships
When the Submission Request includes an Association between two DocumentEntry objects, the Document Registry shall verify that:
-
Both DocumentEntry objects have the same patient identifier (XDSDocumentEntry.patientId attribute); otherwise it shall return the error
XDSPatientIdDoesNotMatch. This comparison shall take into consideration patient identity merges. Such as described in PIX - Patient Identity Feed [ITI-8] (see ITI TF-2: 3.8.4.2.4) or PIXv3 - Patient Identity Feed HL7 V3 [ITI-44] (see ITI TF-2:3.44.4.2.4). -
The sourceObject references a DocumentEntry in the submission; otherwise it shall return the error
UnresolvedReferenceException.
The Document Registry shall verify the targetObject according the following:
- If the associationType is RPLC, XFRM_RPLC, or IsSnapshotOf, that the targetObject references a DocumentEntry in the Document Registry.
- For all other associationTypes, that the targetObject references a DocumentEntry in the Document Registry or in the submission.
If this verification on targetObject fails, the Document Registry shall return the error UnresolvedReferenceException.
When the targetObject references a DocumentEntry in the Document Registry, the Document Registry shall verify that:
-
The targetObject DocumentEntry has an availabilityStatus of Approved;
otherwise, it shall return the error
XDSRegistryDeprecatedDocumentError. This ensures that only the most recent version of a document can be replaced, etc.
When the Association type is "RPLC" or "XFRM_RPLC", the Document Registry shall also:
- Change the status of the DocumentEntry that is being replaced to Deprecated.
- Change the status of all DocumentEntry objects that are transformations (XFRM) or addenda (APND) of the DocumentEntry being replaced to Deprecated.
- If the DocumentEntry being replaced is a member of one or more approved Folders, the Document Registry shall also:
1) Verify the replacement DocumentEntry and approved Folders have the same patient identifier (XDSDocumentEntry.patientId and XDSFolder.patientId attributes); otherwise it shall return the error XDSPatientIdDoesNotMatch. This comparison shall take into consideration patient identity merges. Such as described in PIX - Patient Identity Feed [ITI-8] (see ITI TF-2: 3.8.4.2.4) or PIXv3 - Patient Identity Feed HL7 V3 [ITI-44] (see ITI TF-2:3.44.4.2.4).
2) Create a new FD-DE HasMember Association connecting the replacement DocumentEntry to each approved Folder that held the original DocumentEntry as a member.
3) For each FD-DE HasMember Association created, create a new SS-HM HasMember Association connecting the new FD-DE HasMember Association to the replacement DocumentEntry's Submission Set.
Note: For "RPLC" and "XFRM_RPLC" relationships, earlier versions of the Technical Framework referenced the error XDSReplaceFailed when verification fails. That error has been deprecated.
When the Association type is "IsSnapshotOf", the Document Registry shall also:
- Verify sourceObject references a Stable DocumentEntry
- Verify targetObject references an On-Demand DocumentEntry
As per Section 3.42.4.1.4.1, no changes to the status of any object shall occur if the Submission Request is not accepted and committed.
3.42.4.1.3.6 Updates to Folder.lastUpdateTime
If the submission results in any DocumentEntry being placed into any Folder, the Document Registry shall set the lastUpdateTime attribute of those Folders to the current time. This includes Folders included in the Submission Request as well as Folders already existing in the Document Registry that are referenced by the Submission Request.
As per Section 3.42.4.1.4.1, no changes to the lastUpdateTime of any Folder shall occur if the Submission Request is not accepted and committed.
3.42.4.1.3.7 UUIDs and Symbolic Ids
Objects in the Submission Request have several UUID fields conforming to ITI TF-3: 4.2.3.1.5 .
If a field is formatted as a symbolic Id in the Submission Request, the Document Registry shall replace it with newly generated, properly formatted UUIDs upon acceptance of the submission. If the same symbolic Id appears more than once in the Submission Request, it shall be replaced with the same generated UUID.
If a field is formatted as a valid UUID in the Submission Request, the Document Registry shall not change the value.
Once a UUID-format Id value is assigned to a Registry Object, that value is permanent and shall not be changed.
3.42.4.2 Register Document Set-b Response
3.42.4.2.1 Trigger Events
The Content Receiver finishes processing a Register Document Set-b Request Message and shall respond with Register Document Set-b Response
3.42.4.2.2 Message Semantics
The Register Document Set-b Response message shall use SOAP 1.2 and Simple SOAP. Implementors of this transaction shall comply with all requirements described in: ITI TF-2: Appendix V : Web Services for IHE Transactions.
The 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 V.2.4-1.
The requirements for the response message are:
- the <wsa:Action> soap header shall contain the value urn:ihe:iti:2007:RegisterDocumentSet-bResponse
- the <soap12:Body> soap element shall contain one <rs:RegistryResponse> element
See ITI TF-3: 4.2.4 for examples of response messages.
If the Document Registry supports the Asynchronous Web Services Exchange Option and it receives a WS-Addressing based Asynchronous Web Services request, it shall respond as defined in ITI TF-2: Appendix V.3.
3.42.4.2.3 Expected Actions
The Content Sender now knows that the transaction succeeded/failed and can continue. The metadata added to the Document Registry as a result of this transaction is now available for discovery.
3.42.4.2.3.1 Document Repository Expected Actions
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.42.5 Security Considerations
Relevant XDS Affinity Domain Security background is discussed in the XDS Security Considerations Section (see ITI TF-1: 10.7 ).
3.42.5.1 Audit Record Considerations
The 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.42.5.1.1 Document Repository or Integrated Document Source/Repository audit message:
| Field Name | Opt | Value Constraints | |
|
Event
AuditMessage/
|
EventID | M | EV(110106, DCM, “Export”) |
| EventActionCode | M | “R” (Read) | |
| EventDateTime | M | not specialized | |
| EventOutcomeIndicator | M | not specialized | |
| EventTypeCode | M | EV(“ITI-42”, “IHE Transactions”, “Register Document Set-b”) | |
| Source (Document Repository or Integrated Document Source/Repository) (1) | |||
| Human Requestor (0..n) | |||
| Destination (Document Registry) (1) | |||
| Audit Source (Document Repository or Integrated Document Source/Repository) (1) | |||
| Patient (0..1) | |||
| SubmissionSet (1) | |||
Where:
|
Source
AuditMessage/
|
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/
|
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/
|
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/
|
AuditSourceID | U | not specialized |
| AuditEnterpriseSiteID | U | not specialized | |
| AuditSourceTypeCode | U | not specialized |
|
Patient (if known)
(AuditMessage/
|
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/
|
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.42.5.1.2 Document Registry audit message:
| Field Name | Opt | Value Constraints | |
|
Event
AuditMessage/
|
EventID | M | EV(110107, DCM, “Import”) |
| EventActionCode | M | “C” (Create) | |
| EventDateTime | M | not specialized | |
| EventOutcomeIndicator | M | not specialized | |
| EventTypeCode | M | EV(“ITI-42”, “IHE Transactions”, “Register Document Set-b”) | |
| Source (Document Repository or Integrated Document Source/Repository) (1) | |||
| Destination (Document Registry ) (1) | |||
| Audit Source (Document Registry) (1) | |||
| Patient (0..1) | |||
| SubmissionSet (1) | |||
Where:
|
Source
AuditMessage/
|
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/
|
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/
|
AuditSourceID | U | not specialized |
| AuditEnterpriseSiteID | U | not specialized | |
| AuditSourceTypeCode | U | not specialized |
|
Patient (if known)
(AuditMessage/
|
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/
|
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 |