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.

3.37.1 Scope

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/

3.37.4 Messages

3.37.4.1 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.

3.37.4.1.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.

3.37.4.1.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.

Parameter Name	Optionality	Description	Value
clarificationData	R	The xml representation of clarification specific values.	This value is a well-formed xml document.as defined below.
orgID	R		A string identifying the organization
encodedResponse	R	Tells the Form Manager whether or not to return an encoded response	{true,false}
archiveURL	R	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
context	R	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:

<clarificationData>

  <orgID>a String identifying the form</orgID>

  <encodedResponse>false</encodedResponse>

  <archiveURL />

  <context/>

</clarificationData>

3.37.4.1.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 3.37.4.1.3-1 when appropriate. Form Fillers shall be capable of accepting other values beyond the ones specified here.

Table 3.37.4.1.3-1: SOAP Faults

Description of error	Code	Reason Text
There is missing information, such as no orgID	Sender	Required Information Missing
No form is available	Sender	Unknown orgID

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.

3.37.4.1.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 3.34.4.1.4).

3.37.4.2 Retrieve Clarifications Response

3.37.4.2.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.

3.37.4.2.2 Message Semantics

The form or URL is returned in response to the Retrieve Clarifications.

3.37.4.2.3 Expected Actions

The Form Filler may display the form or navigate to the returned URL to retrieve the form.

3.37.4.2.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.

3.37.4.2.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

ihe	urn:ihe:iti:rfd:2007
soap12	http://schemas.xmlsoap.org/wsdl/soap12/
wsaw	http://www.w3.org/2005/08/addressing
xsd	http://www.w3.org/2001/XMLSchema

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 3.34.5.1 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 .

3.37.5.1 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.

3.37.5.1.1 Sample Retrieve Clarifications SOAP Request

3.37.5.1.2 Sample Retrieve Clarifications SOAP Response