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