Conversation Web Service operations

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 and one of the content element configurations. Here is an abbreviated example:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  ..
   <State>
   ...
   </State>
    <RecordListConfig>
    ...
   </RecordCountConfig>
</Request>

The state is represented by a State element in the request. It describes the records to be selected by the request. The state may be empty or may contain components that change the filter state or reconfigure content elements, typically as a result of user actions. A request must contain at least one state. If the request contains multiple states, then each state must have a name.
A summarization information about the records, included in one of the elements that are types of the ContentElementConfig element from the Conversation Web Service. Note that in any request, the ContentElementConfig base type itself is not included. Instead, its sub-type is included, such as RecordListConfig type in the example. From now on, the Endeca Server documentation refers to ContentElementConfig as "content element config". Any content element config provides summarization information about the records or other information specified in the state. The request may contain multiple ContentElementConfig elements.

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:

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 (which may be empty or may contain one or more filters, as well as a collection name), and one or more content element configs. These filter state and content element configurations are sent in a Conversation Web Service request.
The response to this initial request returns a Results type, which contains the original state and the records (or other information) in one or more content element config elements.
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 state returned by the previous response and any new filters or content element configs that correspond to the user actions.
The response returns a transformed query along with new state and the new content element configs.

Note that during this conversation, the user may request a completely different type of action, which will then require a new and different request.

Request

The Request operation is a complex type with the following schema:

<complexType name="Request">
  <sequence>
    <element  minOccurs="0"  name="OuterTransactionId"  type="cs_v2_0:NonEmptyString" />
    <element  default="en"  minOccurs="0" name="Language"  type="cs_v2_0:NonEmptyString" />
    <element  maxOccurs="unbounded"  minOccurs="0"  name="State"  type="cs_v2_0:State" />
    <group    maxOccurs="unbounded"  minOccurs="0"  ref="cs_v2_0:ContentElementConfig" />
    <element  minOccurs="0" name="PinDataVersion"  type="cs_v2_0:NonEmptyString" />
    <element  minOccurs="0" name="DataVersionRequested"  type="cs_v2_0:NonEmptyString" />
  </sequence>
</complexType>

Each request may specify:

Element	Description
`OuterTransactionId`	Optional. If used, must be the first element in the request. It must be specified only if the request runs within an outer transaction. For details on outer transactions, see Transaction Web Service Interface.
`Language`	Optional. Specifies a language code for error messages generated during parsing of EQL statements. For details on this element and its supported language codes, see Language codes for EQL error messages.
`State`	Required. Contains inputs that affect the set of records to operate on. For example, a state may contain record filters (such as a record search filter, a selected refinement filter, and EQL record filters) and the name of a collection to search. A request can have multiple states (in which case, each state must be named). An unnamed state can exist only if it is the only state in the request.
`ContentElementConfig`	Optional. Represents summarization configuration information relative to the records returned from a specific 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. The types are: `AttributeGroupConfig` `AvailableSearchKeysConfig` `BreadcrumbConfig` `EQLConfig` `NavigationMenuConfig` `PropertyListConfig` `RecordCountConfig` `RecordDetailsConfig` `RecordListConfig` `SearchAdjustmentsConfig` `ValueSearchConfig`
`PinDataVersion`	Optional. Specifies a timeout value during which the Endeca Server should hold on to the current data version. This data version becomes pinned and is maintained in memory for the duration of the timeout. The timeout value specified with this element must fall within minimum and maximum values listed in the EndecaServer.properties file. The pinned version number is returned in the `X-Endeca-Served-Data-Version` header of the response to a request that uses `PinDataVersion`.
`DataVersionRequested`	Optional. Specifies the number of the pinned version. The request that includes `DataVersionRequested` must be issued within the timeout period specified when the version was pinned. This resets the timeout. If the request is issued after this timeout period, the pinned version may have expired.

Response

The Request operation outputs a Results response, which includes the State and, optionally, one or more of the ContentElement types that resulted from the request's ContentElement (for example, a RecordList is returned from a RecordListConfig).

Each response from the Conversation Web Service includes in its header two version numbers — the served version number and the latest version number:

X-Endeca-Served-Data-Version 
X-Endeca-Data-Version

The X-Endeca-Served-Data-Version also represents the number of the pinned data version (if you pin it).

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.