3.61 Register On-Demand Document Entry [ITI-61]
This section corresponds to transaction [ITI-61] of the IHE ITI Technical Framework. Transaction [ITI-61] is used by the On-Demand Document Source and Document Registry Actors.
3.61.1 Scope
The Register On-Demand Document Entry transaction passes a Document Submission Request (see ITI TF-3: 4.2.1.5 ) from an On-Demand Document Source to a Document Registry. The Document Submission Request for this transaction contains metadata describing one or more On-Demand DocumentEntry objects and, optionally, Folders and Associations.
3.61.2 Use Case Roles
Actor: On-Demand Document Source
Role: A Provider of On-Demand Documents that registers a patient-specific on-demand document to the Document Registry.
Actor: Document Registry
Role: A document indexing system that receives and stores metadata about available on-demand documents.
3.61.3 Referenced Standard
| 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 XDS 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 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.61.4 Messages
Figure 3.61.4-1: Interaction Diagram
3.61.4.1 Register On-Demand Document Entry Request
The Register On-Demand Document Entry Request message is used to register metadata that can be used to request an on-demand document. An on-demand document is one which collects the latest, most recent available information at the time of retrieval. For more information about the On-Demand DocumentEntry specified in the request message see ITI TF-3: 4.1.1 .
The On-Demand Document Source sends metadata to the Document Registry. The metadata contains one or more patient-specific On-Demand DocumentEntry objects and, optionally, Folders and Associations.
3.61.4.1.1 Trigger Events
The Register On-Demand Document Entry Request message is triggered when the On-Demand Document Source chooses to make available an on-demand document for a particular patient.
3.61.4.1.2 Message Semantics
The Register On-Demand Document Entry 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.3.
The Register On-Demand Document Entry Request message shall contain a Submission Request, as defined in ITI TF-3: 4.1.4 except that it shall include at least one On-Demand DocumentEntry. All DocumentEntry objects in this Submission Request shall be On-Demand DocumentEntry objects and, therefore, will not be Stable DocumentEntry objects.
This transaction imposes no restrictions on the use of Folders or Associations. In particular, workflows which replace a Stable DocumentEntry with an On-Demand DocumentEntry, add an On-Demand DocumentEntry to a Folder, or replace an On-Demand DocumentEntry with a new On-Demand DocumentEntry are all valid.
Note: Because a Stable DocumentEntry cannot be submitted in this transaction, Associations which require the simultaneous submission of a Stable DocumentEntry cannot be included in this transaction. For example, workflows which replace an On-Demand DocumentEntry with a Stable DocumentEntry are not allowed.
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 . In its use of metadata, the On-Demand DocumentEntry has the same requirements as a Stable DocumentEntry, except for the following:
- creationTime – Not Applicable; shall not be specified in a Register On-Demand Document Entry Request.
- hash – Not Applicable; shall not be specified in a Register On-Demand Document Entry Request.
- legalAuthenticator – Recommend this not be specified as having no clear meaning in the context of an On-Demand DocumentEntry.
- repositoryUniqueId – The globally unique immutable identifier of the On-Demand Document Source which provides an On-Demand Document corresponding to this On-Demand DocumentEntry. This unique identifier for the On-Demand Document Source may be used to identify and connect to the specific On-Demand Document Source where a current instance of the on-demand document may be retrieved.
- size – Not Applicable; shall not be specified in a Register On-Demand Document Entry Request.
- uniqueId – The globally unique identifier assigned by the On-Demand Document Source to this On-Demand DocumentEntry. It is used in the Retrieve Document Set [ITI-43] transaction to identify the correct On-Demand Document to access. The use of uniqueId in On-Demand DocumentEntry objects is different from Stable DocumentEntry objects as this value will never represent an actual document. See ITI TF-3: 4.1.1 for more details regarding use of uniqueId by On-Demand DocumentEntry objects.
A full example of document metadata submission is available 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 2.4-1.
The requirements for the request message with the Synchronous and the WS-Addressing based Asynchronous Web Services stack are:
- the <wsa:Action> SOAP element shall contain the value urn:ihe:iti:2010:RegisterOnDemandDocumentEntry
- 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 On-Demand Document Entry 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 On-Demand 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.
If the On-Demand Document Source supports the Basic Patient Privacy Enforcement Option, it shall comply with the requirements as described in ITI TF-1: 10.2.9 .
3.61.4.1.3 Expected Actions
Upon receipt of a Register On-Demand Document Entry Request message, the Document Registry shall:
- Perform metadata validations
- Store all IHE-defined metadata attributes received so that they are 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.
The Document Registry shall comply with all of the requirements specified in Sections 3.42.4.1.3.1 through 3.42.4.1.3.7 except for Section 3.42.4.1.3.3.1 which describes the validation of DocumentEntry.uniqueId. In terms of this metadata attribute, the Document Registry shall reject the message and return an error if the uniqueId attribute matches the uniqueId attribute of a Stable DocumentEntry currently within the Document Registry. If the uniqueId attribute matches the uniqueId attribute of an On-Demand DocumentEntry currently within the Document Registry the Document Registry shall accept the transaction and thereby create a new On-Demand DocumentEntry with the same uniqueId.
3.61.4.2 Register On-Demand Document Entry Response
The Document Registry sends the result of processing the On-Demand DocumentEntry metadata to the On-Demand Document Source.
3.61.4.2.1 Trigger Events
The Document Registry finishes processing a Register On-Demand Document Entry Request message and shall return a Register On-Demand Document Entry Response message.
3.61.4.2.2 Message Semantics
The Register On-Demand Document Entry 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.3.
The Register On-Demand Document Entry 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.
If creationTime, hash or size metadata attributes are received in a Register On-Demand Document Entry Request message, the Document Registry shall return an XDSRegistryMetadataError.
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 with the Synchronous and the WS-Addressing based Asynchronous Web Services stack are:
- the <wsa:Action> soap header shall contain the value urn:ihe:iti:2010:Register OnDemandDocumentResponse
- 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.61.4.2.3 Expected Actions
The On-Demand Document Source 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.61.5 Security Considerations
Relevant XDS Affinity Domain Security background is discussed in the XDS Security Considerations Section (see ITI TF-1: 10.7 ).
3.61.5.1 Audit Record Considerations
The Register On-Demand Document Entry transaction is PHI-Export event, as defined in ITI TF-2: Table 3.20.4.1.1.1-1 with the following exceptions.
3.61.5.1.1 On-Demand Document Source 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-61”, “IHE Transactions”, “Register On-Demand Document Entry”) | |
| Source (On-Demand Document Source) (1) | |||
| Human Requestor (0..1) | |||
| Destination (Document Registry) (1) | |||
| Audit Source (On-Demand Document Source) (1) | |||
| Patient (1) | |||
| SubmissionSet (1) | |||
Where:
|
Source
AuditMessage/
|
UserID | M | If WS-Addressing based 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 | M | “true” | |
| 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
(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.61.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-61”, “IHE Transactions”, “Register On-Demand Document Entry”) | |
| Source (On-Demand Document Source) (1) | |||
| Human Requestor (0..1) | |||
| Destination (Document Registry ) (1) | |||
| Audit Source (Document Registry) (1) | |||
| Patient (1) | |||
| SubmissionSet (1) | |||
Where:
|
Source
AuditMessage/
|
UserID | M | If WS-Addressing based 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. |
|
Human Requestor (if known)
AuditMessage/
|
UserID | M | Identity of the human that initiated the transaction. |
| AlternativeUserID | U | not specialized | |
| UserName | U | not specialized | |
| UserIsRequestor | M | “true” | |
| 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 | 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
(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 |