3.37 Retrieve Clarifications [ITI-37]
This section corresponds to transaction [ITI-37] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-37] is used by the Form Filler and Form Manager or Form Processor Actors.
This transaction involves a Form Filler requesting a set of clarifications from a Form Manager or Form Processor. A Form Filler supporting the Retrieve Clarifications Option shall perform this request periodically, based upon a duration defined by or agreed upon with the Form Manager / Form Receiver or Form Processor. Note that not all use cases will need to support this option.
The Form Filler has an orgID, obtained by a means that is outside the scope of this transaction, and the Form Manager or Form Processor will either return a form that contains either the data to be clarified or a set of links to other forms that can be retrieved using the Retrieve Form transaction. All updates / clarifications / new data are submitted to the Form Receiver using the Submit Form transaction.
3.37.2 Use Case Roles
Actor: Form Filler
Role: A forms display and editing system capable of allowing form fields to be completed.
Actor: Form Manager
Role: A system that provides clarification information based upon requests that provide specific orgIDs.
Actor : Form Processor
Role : A system that provides clarification information based upon requests that provide specific orgIDs.
3.37.3 Referenced Standards
RFC1738, Uniform Resource Locators (URL), December 1994, http://www.faqs.org/rfcs/rfc1738.html
RFC2616 HyperText Transfer Protocol HTTP/1.1
Extensible Markup Language (XML) 1.0 (Second Edition). W3C Recommendation 6 October 2000. http://www.w3.org/TR/REC-xml.
ITI TF-2: Appendix V Web Services for IHE Transactions
XForms 1.1, W3C Working Draft. http://www.w3.org/TR/2004/WD-xforms11-20041115/
Figure 3.37.4-1: Interaction Diagram
18.104.22.168 Retrieve Clarifications Request
This transaction is initiated whenever a Form Filler which supports the Retrieve Clarifications Option needs to obtain clarification information relevant to the organization or site.
22.214.171.124.1 Trigger Events
The Retrieve Clarification event is triggered by the need for information on current clarifications to be made available within an EHR system. The transaction does not specify when the Retrieve Clarification happens, only that this transaction is available when information regarding clarifications is needed from a Form Manager or Form Processor. It is the responsibility of the Form Filler that supports this option to periodically execute this transaction.
126.96.36.199.2 Message Semantics
Implementors of this transaction shall comply with all requirements described in ITI TF-2: Appendix V : Web Services for IHE Transactions.
The following parameters are specified for this transaction.
|The xml representation of clarification specific values.
|This value is a well-formed xml document.as defined below.
|A string identifying the organization
|Tells the Form Manager whether or not to return an encoded response
|Tells the Form Manager whether or not the Form Filler is exercising the Archive Option
|the URL of any Form Filler identified Form Archiver; may be nil
|The xml specifics of workflow context
|Defined by content profiles; may be nil
The clarificationData may be extended by IHE content profiles with further definition of the <context> element.
The content of clarificationData shall minimally be:
<orgID>a String identifying the form</orgID>
188.8.131.52.3 Expected Actions
Upon receipt of the Retrieve Clarifications request, the Form Manager or Form Processor shall parse the request and shall return the requested response in the RetrieveClarificationsResponse element, or errors with SOAP Faults.
The Form Manager or Form Processor shall return the form or URL based on the values of: a) the encodedResponse; b) the orgID; c) any additional clarificationData.
If no clarification information is available, this is shall be indicated by a form indicating that no clarification information is available.
If encodedResponse is ‘true’, then the response from the Form Manager or Form Processor shall be either a Structured (XML) or Unstructured (non-XML) element. When the encodedResponse parameter is 'true' all anchor addresses that are not fragment identifiers shall be composed of absolute URIs.
If encodedResponse is ‘false’, then the response from the Form Manager or Form Processor shall be a URL element that can be used directly by a web browser for retrieval and operation of the form.
The value of the orgID has been previously assigned by the Form Manager or Form Processor and identifies use one of the named format options. A Form Manager may support multiple named options, but for each orgID there is only one named option that is supported.
The Form Manager shall use the SOAP Faults defined in Table 184.108.40.206.3-1 when appropriate. Form Fillers shall be capable of accepting other values beyond the ones specified here.
Table 220.127.116.11.3-1: SOAP Faults
|Description of error
|There is missing information, such as no orgID
|Required Information Missing
|No form is available
An example of a SOAP Fault is:
The orgID has been assigned by the Form Manager or Form Processor use one of the named format options. A Form Manager or Form Processor may support multiple named options, but for each orgID there is only one named option that is supported.
18.104.22.168.4 Security Considerations
The security considerations for the Retrieve Clarifications request message are no different than those of the Retrieve Form request message (see Section 22.214.171.124.4).
126.96.36.199 Retrieve Clarifications Response
188.8.131.52.1 Trigger Events
The Delivery of a Form is triggered by a Form Manager or Form Processor providing a form based upon the orgID supplied with the Retrieve Clarifications transaction.
184.108.40.206.2 Message Semantics
The form or URL is returned in response to the Retrieve Clarifications.
220.127.116.11.3 Expected Actions
The Form Filler may display the form or navigate to the returned URL to retrieve the form.
18.104.22.168.3.1 XHTML Handling
A Form Manager or Form Processor shall return a form, whether returned as the response or referenced by a returned URL, formatted as XHTML using XHTML Basic and W3C HTML Compatibility Guidelines provided in the Appendix C of the W3C XHTML 1.0 Recommendation. The returned form shall support the Submit and all required Archive transactions.
22.214.171.124.3.2 XForm Option
A Form Manager or Form Processor that supports the XForms Option shall additionally be capable of returning a form, whether returned as the response or referenced by a returned URL, that conforms to XForms 1.1. The host language for the XForm shall be XHTML Basic according to the W3C HTML Compatibility Guidelines provided in the Appendix C of the W3C XHTML 1.0 Recommendation. The returned form shall support the Submit and all required Archive transactions.
3.37.5 Protocol Requirements
The Retrieve Clarifications request and response shall be transmitted using Synchronous Web Services Exchange, according to the requirements specified in ITI TF-2: Appendix V .
The Retrieve Clarifications transaction shall use SOAP 1.2.
WSDL Namespace Definitions
These are the requirements for the Retrieve Clarifications transaction presented in the order in which they would appear in the WSDL definition:
- The following types shall be imported (xds:import) in the /definitions/types section:
- Namespace=” urn:ihe:iti:rfd:2007”, schema=”RFD.xsd”
- The /definitions/message/part/@element attribute of the Retrieve Clarifications Request message shall be defined as: “ihe:RetrieveClarificationsRequest”
- The /definitions/message/part/@element attribute of the Retrieve Clarifications Response message shall be defined as: “ihe:RetrieveClarificationsResponse”
- The /definitions/portType/operation/input/@wsaw:Action attribute for the Retrieve Clarifications Request message shall be defined as “urn:ihe:iti:2007:RetrieveClarifications”
- The /definitions/portType/operation/output/@wsaw:Action attribute for the Retrieve Clarifications Response message shall be defined as: “urn:ihe:iti:2007:RetrieveClarificationsResponse”
- The /definitions/binding/operation/soap12:operation/@soapActionRequired attribute shall be defined as “false”
These are the requirements that affect the wire format of the SOAP message. The other WSDL properties are only used within the WSDL definition and do not affect interoperability. Full sample request and response messages are in Section 126.96.36.199 Sample SOAP Messages.
An informative WSDL for the Form Manager and a full XML Schema Document for the RFD types are available online. See ITI TF-2: Appendix W .
188.8.131.52 Sample SOAP Messages
The samples in the following two sections show a typical SOAP request and its relative SOAP response. The sample messages also show the WS-Addressing headers <Action/>,
<MessageID/>, …; these WS-Addressing headers are populated according to
ITI TF-2: Appendix V : Web Services for IHE Transactions.