Retrieving applied refinements per attribute

You can issue a Conversation Web Service request that retrieves, for a refinement of your choice, not only suggested refinements, but also applied refinements (both explicitly-selected and implicit).

By default, Endeca Server does not return explicitly-selected or implicit refinements once end-users make a query and select some refinements as part of the Guided Navigation experience. In other words, by default, all refinements that are returned are guaranteed to narrow the result set in the future, if end users select any of them. However, you can specify in the Conversation Web Service requests to retrieve the full set of refinements (suggested and applied). You can do so globally for all refinements, or for a specific refinement.

The following two attributes in the RefinementConfig element, (this is a sub-element of the NavigationMenuConfig), control whether to retrieve explicitly-selected and implicit refinements, per each specified attribute:

IncludeExplicitSelections specifies whether Endeca Server should retrieve explicitly-selected refinements, for this attribute. The default is false.
IncludeImplicitSelections specifies whether Endeca Server should retrieve implicit refinements, for this attribute. The default is false.

You can use any combination of true and false values.

Once the refinements are retrieved, Expose="true" is the setting that controls whether they are also returned in the web service response.

The settings made per attribute (in the RefinementConfig for each attribute) override the analogous settings made for all attributes (in the NavigationMenuConfig).

Example: retrieving a full list of applied refinements for a specific attribute

In these examples, the namespaces are omitted and they are: xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.endeca.com/MDEX/conversation/3/0" xmlns:typ="http://www.endeca.com/MDEX/eql_parser/types"

The following example of a request assumes that a query is made in a particular navigation state. In this state, end users have already made a selection for the winery "L.A.Lenoble". This request performs two tasks — it retrieves the next list of suggested refinements still available to users, and also, for each of the three specified attributes, asks to retrieve those refinements that have been already applied (explicitly-selected and implicit):

<ns:Request>
 <ns:State><ns:Name>ref_state</ns:Name>
  <ns:SelectedRefinementFilter Name="Winery" Spec="A.R. Lenoble"/>
 </ns:State>
 <ns:NavigationMenuConfig Id="NavigationMenu" ExposeAllRefinements="true" ReturnFullPath="true" 
  IncludeAllExplicitSelections="false" IncludeAllImplicitSelections="false">
 <ns:StateName>ref_state</ns:StateName>
  <ns:RefinementConfig Name="WineType" Expose="true" IncludeExplicitSelections="true" IncludeImplicitSelections="true"/>
  <ns:RefinementConfig Name="Region" Expose="true" IncludeExplicitSelections="true" IncludeImplicitSelections="true"/>
  <ns:RefinementConfig Name="Winery" Expose="true" IncludeExplicitSelections="true" IncludeImplicitSelections="true"/>
 </ns:NavigationMenuConfig>
</ns:Request>

In this request:

In NavigationMenuConfig, the global settings for returning explicitly-selected and implicit refinements are set to "false":
```
IncludeAllExplicitSelections="false" IncludeAllImplicitSelections="false"
```
In each RefinementConfig, the request specifies true for both implicit and explicitly-selected refinements for these attributes: "WineType", "Region" and "Winery". This means, that if the navigation state for this refinement includes any such refinements, the response will include them:
```
<ns:RefinementConfig Name="Region" Expose="true" 
IncludeExplicitSelections="true" 
IncludeImplicitSelections="true"/>
```
The settings on RefinementConfig override those on NavigationMenuConfig, which means that if applied refinements are present for these attributes, they will be retrieved. Note also the setting Expose="true". This setting controls whether the retrieved refinements are actually returned to you in the web service response.

Here is an abbreviated response to this request (with namespaces omitted):

<cs:Results>
 <Name>ref_state</Name>
 <SelectedRefinementFilter Name="Winery" Spec="A.R. Lenoble"/>
 </State>
 <cs:NavigationMenu Id="NavigationMenu">
  <cs:NavigationMenuItem Name="Region" DisplayName="Region" MultiSelect="None" HasMore="false">
   <cs:ExposureControl Exposed="true"/>
   <cs:RootDimensionValue DimensionName="Region" Spec="/"/>
   <cs:ImplicitRefinement Name="Region" Spec="Champagne" Label="Champagne"/>
  </cs:NavigationMenuItem>
  <cs:NavigationMenuItem Name="Winery" DisplayName="Winery" MultiSelect="None" HasMore="false">
   <cs:ExposureControl Exposed="true"/>
   <cs:RootDimensionValue DimensionName="Winery" Spec="/"/>
   <cs:SelectedRefinement Name="Winery" Spec="A.R. Lenoble" Label="A.R. Lenoble" Count="3"/>
  </cs:NavigationMenuItem>
  <cs:NavigationMenuItem Name="WineType" DisplayName="Wine Type" MultiSelect="None" HasMore="false">
   <cs:ExposureControl Exposed="true"/>
   <cs:Refinement Name="WineType" Spec="Brut Rose" Label="Brut Rose" Count="1"/>
   <cs:Refinement Name="WineType" Spec="Brut Blanc de Blancs" Label="Brut Blanc de Blancs" Count="1"/>
   <cs:Refinement Name="WineType" Spec="Brut" Label="Brut" Count="1"/>
   <cs:RootDimensionValue DimensionName="WineType" Spec="/"/>
   <cs:FullPath>
    <cs:DimensionValue DimensionName="WineType" Spec="/">WineType</cs:DimensionValue>
    <cs:DimensionValue DimensionName="WineType" Spec="Sparkling">Sparkling</cs:DimensionValue>
   </cs:FullPath>
   <cs:ImplicitRefinement Name="WineType" Spec="Sparkling" Label="Sparkling"/>
  </cs:NavigationMenuItem>
 </cs:NavigationMenu>
</cs:Results>

Let's review this response.

For the attribute "Region", no suggested refinements are available, but there is one implicit refinement "Champagne":

<cs:NavigationMenuItem Name="Region" ... >
 ...
 <cs:RootDimensionValue DimensionName="Region" Spec="/"/>
 <cs:ImplicitRefinement Name="Region" Spec="Champagne" Label="Champagne"/>
</cs:NavigationMenuItem>

This is because, in this data set, there are only three wines from the "A.R. Lenoble" winery which is located in the Champagne region and produces only Champagnes. So, by specifying winery as "L.A.Lenoble" in the state's filter: SelectedRefinementFilter Name="Winery" Spec="A.R. Lenoble", users also implicitly select two refinements: Region with value "Champagne", and WineType with value "Sparkling".

For the attribute "WineType", a list of suggested refinements is returned, followed by one implicit refinement "Sparkling":

<cs:NavigationMenuItem Name="WineType" ... >
...
 <cs:Refinement Name="WineType" Spec="Brut Rose" Label="Brut Rose" Count="1"/>
 <cs:Refinement Name="WineType" Spec="Brut Blanc de Blancs" Label="Brut Blanc de Blancs" Count="1"/>
 <cs:Refinement Name="WineType" Spec="Brut" Label="Brut" Count="1"/>
 ...
 <cs:ImplicitRefinement Name="WineType" Spec="Sparkling" Label="Sparkling"/>
</cs:NavigationMenuItem>

Finally, for the attribute "Winery", while there are no remaining suggested refinements, there is one selected refinement, "A.R. Lenoble":

<cs:NavigationMenuItem Name="Winery" ... >
...
 <cs:SelectedRefinement Name="Winery" Spec="A.R. Lenoble" Label="A.R. Lenoble" Count="3"/>
</cs:NavigationMenuItem>

To conclude, the user interface can use this information to display these refinements as un-selectable (because they have already been selected). It can also optionally indicate to the users that some of these refinements have been selected implicitly.

For each of these attributes, the request also includes information in the RootDimensionValue, and FullPath elements, because these are managed attributes with hierarchy.