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. A typical request consists of the filter state, content element configurations and operators:
  • The filter State reflects currently selected records and the selections that were used to reach them.
  • The Operator elements 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.
  • ContentElementConfig elements provide different types of configuration information about the records specified in State.
The Conversation Web Service, unlike other Web services of the Endeca Server, implies that you create a series of related requests, thus creating a "dialog" with your data. 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 as ComplexType).

    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.
  3. When the user chooses a particular action, the front-end application submits a new request through the Conversation Web Service. Typically, this subsequent Request is constructed from the Results returned by the previous invocation of the Conversation Web Service request. Specifically, the request sends in the filter State returned by the previous response and the operators corresponding to the user actions. In other words, in this request, the State and ContentElementConfig elements are obtained from the Request element in the prior Results.

    The contents of ContentElementConfig includes a number of Operator elements. These elements could be any of the various types of operators that describe how a request to the Oracle Endeca Server differs from the previous request. All operator types are available through the Operator complex type.

    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_v2_0:NonEmptyString"/>
    <element name="Language" minOccurs="0" type="cs_v2_0:NonEmptyString" default="en"/>
    <element name="State" type="cs_v2_0:State"/>
    <element name="Operator" type="cs_v2_0:Operator" minOccurs="0" maxOccurs="unbounded"/>
    <element name="ContentElementConfig" type="cs_v2_0:ContentElementConfig" 
       minOccurs="0" maxOccurs="unbounded"/>
    <element name="PassThrough" type="cs_v2_0:CatchAll" minOccurs="0"/>
  </sequence>
</complexType>
A request consists of a filter state, an operator, 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.
Language Specifies a language code for error messages generated during parsing of EQL statements. For details on this element and its supported language codes, see EQL filter syntax.
State Contains inputs that affect the set of records to operate on. A filter state may contain, for example, selected refinements, search terms, and EQL record filters.
Operator Transforms the filter state and configuration. Each request may contain a sequence of operators. Some of the commonly used types of operators are: ApplySpellingSuggestionOperator, RecordKindOperator RefinementOperator, SearchOperator, SelectionFilterOperator.
For example, an operator can be specified in the request as follows:
<Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="SearchOperator" Within="false">
   <SearchFilter Mode="AllPartial" RelevanceRankingStrategy="numfields"
      Key="PROD_CATEGORY" EnableSnippeting="false" Language="en">
      electronics
   </SearchFilter>
</Operator>
This operator is of type SearchOperator, and as such, it applies a SearchFilter, with specified configuration information for this filter.

To remove an operator from the filter state, you can use PopName_of_operatorOperator, where Name_of_operator is the name of the operator that you want to remove, such as SearchOperator.

ContentElementConfig Represents a message to the Oracle Endeca Server, asking it to provide certain configuration information relative to a specific filter state. Different types of ContentElementConfig exist. Types can describe, for example, 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.

A type can be any of the following: AttributeGroupConfig, AvailableSearchKeysConfig, BreadcrumbConfig, LQLConfig, NavigationMenuConfig, PropertyListConfig, RecordCountConfig, RecordDetailsConfig, RecordListConfig, SearchAdjustmentsConfig, ValueSearchConfig.

Additionally, for each type, its corresponding HandlerFunction, namespace and ID must be specified, as in this example:
<ContentElementConfig 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:type="RecordListConfig" 
Id="RecordList" HandlerNamespace="http://www.endeca.com/MDEX/conversation/handlers/2010"
HandlerFunction="RecordListHandler">
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_v2_0:Request"/>
    <element name="ContentElement" type="cs_v2_0:ContentElement" 
      minOccurs="0" maxOccurs="unbounded"/>
    <element name="PassThrough" type="cs_v2_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.