Conversation Web Service operations

The Conversation Web Service interface provides an operation that queries the Oracle Endeca Server.

This topic provides an overview of the operations in the Conversation Web Service.

Operation description

At a high level, the Conversation Web Service facilitates a dialog with users about data. It manages the filter state, content element configurations, and operators:
  • The filter state reflects the currently selected records and the selections that were used to reach them.
  • Content element configurations provide information about the currently selected records.
  • The operators represent requests to change the filter state or reconfigure content elements, typically as a result of user actions. Operators can be specified for refinements, record and range filters, breadcrumbs, and other aspects of the front-end application available for navigation.
The sequence of actions in the Conversation Web Service "dialog" is as follows:
  1. A user issues a query using the front-end application.

    In the Conversation Web Service, the request is reflected in the Request complex type (in the WSDL, all complex types are listed asComplexType).

    This query is used to construct an initial filter state (typically, empty, or containing a simple record filter), and a number of content element configurations. These filter state and content element configurations are sent in a Conversation Web Service request.

  2. The response to this initial request returns the filter state in a State element, describing the records selected, and the resulting content elements.

    The content elements contain a number of operators, represented by the various types of operators available through the Operator complex type, each describing a user action that might occur from this state. For instance, a record list content element contains operators to re-sort the records, or to view different pages; a navigation menu content element contains an operator for each refinement.

    Operators describe how a request to the Oracle Endeca Server differs from the previous request. Typically, a Request is constructed from the Results returned by the previous invocation of the Conversation Web Service request.

  3. When the user chooses a particular action, the front-end application submits a new request through the Conversation Web Service, passing in the filter State returned by the previous response and passing in the operators corresponding to the user actions.

    The requester may also attach arbitrary XML to the request via the PassThrough element, to be returned unchanged in the response.

  4. The response returns a transformed query along with new filter State and new content element contents (response data).

To summarize, the "conversation" underlying this web service consists of the following stages: The Conversation Web Service offers a list of content elements and a number of operators, the front-end application selects some operators, and the Conversation Web Service offers new content elements and new operators.

Request

The Request operation looks like the following:
<operation name="Request">
  <input name="request" message="cs:Request"/>
		<output name="response" message="cs:Results"/>
		<fault name="fault" message="cs:Fault"/>
</operation>
The Request operation takes a Request complex type as its input. The schema for the Request complex type is:
<complexType name="Request">
	<sequence>
	<element name="OuterTransactionId" minOccurs="0" type="cs_v1_0:NonEmptyString"/>
	<element name="State" type="cs_v1_0:State"/>
	<element name="Operator" type="cs_v1_0:Operator" minOccurs="0" maxOccurs="unbounded"/>
	<element name="ContentElementConfig" type="cs_v1_0:ContentElementConfig"
   minOccurs="0" maxOccurs="unbounded"/>
	<element name="PassThrough" type="cs_v1_0:CatchAll" minOccurs="0"/>
	</sequence>
</complexType>
A request consists of a filter state, and a list of content element configurations and operators to compute. Each request specifies:
Element Description
OuterTransactionId Has to be the first element in the request, and is optional. It must be specified only if the request runs within an outer transaction.
State Contains inputs that affect the set of records to operate on. A filter state may contain, for example, selected refinements, search terms, and record filters.
Operator Transform the filter state and configuration. Each request may contain a sequence of operators.
ContentElementConfig Represents a message to the Oracle Endeca Server, asking it to provide certain information relative to a certain filter state.

For example, these elements can describe a summarization of a filter state or the data therein, such as a set of breadcrumbs, a navigation menu, or the data for a grid or chart.

PassThrough A placeholder element for adding arbitrary XML to the request; it is returned unchanged in the response.

Response

The Request operation outputs a Results response. The response contains the Request element that generated it, as well as any components that were requested. Each component is returned only if its corresponding configuration was supplied in the request.

In other words, a response from the Conversation Web Service contains operators for refinements, breadcrumbs, and other aspects of the front-end application available for navigation.

The schema for the Results complex type response is:
<complexType name="Results">
	<sequence>
	<element name="Request" type="cs_v1_0:Request"/>
	<element name="ContentElement" type="cs_v1_0:ContentElement" 
   minOccurs="0" maxOccurs="unbounded"/>
	<element name="PassThrough" type="cs_v1_0:CatchAll" minOccurs="0"/>
 </sequence>
</complexType>

Error example

On failure, the SOAP fault is thrown. Its faultstring element contains information about the request that caused the error, and the detail element includes pointers to the location of errors in the request.