Retrieving applied refinements for all attributes

By default, Endeca Server does not return applied (explicitly-selected or implicit) refinements once the end-user makes a query and selects 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 issue a Conversation Web Service request for the navigation menu that should retrieve not only suggested refinements, but also applied (explicitly-selected and implicit) refinements, for all attributes used as refinements.

The following two settings in the NavigationMenuConfig element of the Conversation Web Service control whether to return explicitly-selected and implicit refinements for all attributes:

IncludeAllExplicitSelections specifies whether Endeca Server should retrieve explicitly-selected refinements. The default is false.
IncludeAllImplicitSelections specifies whether Endeca Server should retrieve implicit refinements. The default is false.

You can use any combination of true and false values.

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

A NavigationMenuConfig has the following structure:

<ns:NavigationMenuConfig Id="?" 
ExposeAllRefinements="?" 
ReturnFullPath="false" 
MaximumRefinementCount="?" 
IncludeAllExplicitSelections="false"
IncludeAllImplicitSelections="false">
  </ns:StateName>
   <ns:RefinementConfig Name="?" 
    Spec="?" Expose="false" OrderByRecordCount="false" MaximumCount="?" 
    IncludeExplicitSelections="false" IncludeImplicitSelections="false"/>
</ns:NavigationMenuConfig>

Example: retrieving a full list of applied refinements for all attributes

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"

In the following example request, a query is made in a particular navigation state (assuming that the users have navigated to this state). It includes a refinement filter inside the state, and thus narrows the results to a specific Winery, named "A.R.Lenoble". The request retrieves the list of suggested refinements that are still available, and also retrieves, for all refinements, 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="true" 
 IncludeAllImplicitSelections="true">
   <ns:StateName>ref_state</ns:StateName>
   <ns:RefinementConfig Name="WineType" Expose="true"/>
   <ns:RefinementConfig Name="Region" Expose="true"/>
   <ns:RefinementConfig Name="Winery" Expose="true"/>
  </ns:NavigationMenuConfig>
</ns:Request>

This request specifies true for both types of applied refinements—implicit and explicitly-selected—at the navigation level. This means, that if the current navigation state for the Winery ""A.R.Lenoble" includes any such refinement, the response will include retrieve it, along with the list of suggested refinements. Note that the full list of applied refinements is returned in the request only if ExposeAllRefinements="true". In addition, this request also asks to expose all refinement values for three attributes: "WineType", "Region", and "Winery".

The response to this request is (namespaces are omitted):

<cs:Result>
 <State>
   <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>

In this response, the State is returned first, reflecting the selected filter for the winery "L.A.Lenoble". It is followed by a NavigationMenu, which includes three NavigationMenuItem elements, for each of the attributes—"Region", "Winery", and "WineType".

For the attribute "Region", the response includes the implicitly-selected refinement value "Champagne":

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

For the attribute "WineType", the response includes another implicit refinement, "Sparkling":

<cs:NavigationMenuItem Name="WineType" ...>
    ...
    <cs:ImplicitRefinement Name="WineType" Spec="Sparkling" Label="Sparkling"/>
  </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 "A.R. 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".

Notice also that for the attribute "Wine", the refinement "A.R. Lenoble" is returned as a SelectedRefinement for Winery, since it is selected in the query state of the request:

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

The user interface can use this information to display these already-applied refinements as un-selectable (because they have already been selected). It can also optionally indicate to the users which of these refinements have been selected implicitly.

Additionally, this response includes a list of suggested refinements that are still available in this navigation state. These are present only for the refinement "WineType":

<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"/>

Finally, since all three requested refinements in the request are on managed attributes, (which have hierarchy), additional information about hierarchy is returned for each refinement, inside RootDimensionValue, and FullPath elements.

To summarize, this method lets you control, for all your attributes, whether applied refinements are retrieved. In addition to this global control, you can specify per each attribute, whether you would like to retrieve explicitly-selected refinements, implicit refinements, or both of them. Retrieving a full list of applied refinements per each attribute overrides the retrieving them for all attributes. For information see Retrieving applied refinements per attribute.