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.
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.
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.
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.
<operation name="Request"> <input name="request" message="cs:Request"/> <output name="response" message="cs:Results"/> <fault name="fault" message="cs:Fault"/> </operation>
<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>
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. |
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.
<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>
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.