Refinements configuration format

Use the RefinementGroupConfig and RefinementConfig elements of the Conversation Web service request to expose refinement values for attributes. These elements allow you to perform operations on many attributes at once without enumerating all of them.

By default, attributes in groups and refinements are collapsed. If you would like to expose attributes that have refinements, either use RefinementConfig on each attribute whose refinements you want to expose, or use ExposeAllPropertyRefinements and expose refinements for all attributes at once.

RefinementGroupConfig format

The RefinementGroupConfig element returns a list of refinements from those attributes that are included in groups. It contains the RefinementConfig element.

RefinementGroupConfig contains the following parameters:
Attribute Description
Expose Required. Indicates whether to evaluate attributes in the group as potential refinements at all.

Using the Expose attribute is important when you have groups of attributes and would like to be able to "expand" and "collapse" them in the user interface of the front-end application. For example, if you wanted country name refinements, then in order to obtain them, you use Expose in the initial request which enables the expand/collapse options in the UI. Next, you request these refinements in a separate Conversation Web Service request.

ExposeAllPropertyRefinements Optional. Indicates whether to expose refinements (that is, whether to compute refinement values) for all attributes in the group.
Name Required. The name of the group.
The RefinementConfig element is used in a NavigationMenuConfig element, as in this example. Notice two Expose attributes, used for two different levels of exposure — first, the attributes in the group are exposed and next, the refinements under those attributes are exposed. In other words, this request exposes the attributes in the group, and then the refinement values for the OrderQuantity attribute that is part of the group Sales-Transaction:
<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
   <State/>
   <ContentElementConfig xsi:type="NavigationMenuConfig"
     Id="NavigationMenu"
     HandlerFunction="NavigationMenuHandler" 
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <RefinementGroupConfig Name="Sales-Transaction" Expose="true">
       <RefinementConfig Name="OrderQuantity" Expose="true" MaximumCount="100" /> 
     </RefinementGroupConfig> 
   </ContentElementConfig>
</Request>

To perform operations on individual attributes in a group, instead of performing operations on all of them (for example, to override settings for an individual attribute), you can use multiple RefinementConfig elements in a RefinementGroupConfig.

RefinementConfig format

The RefinementConfig element controls the behavior of an individual attribute in a NavigationMenu. It specifies which attributes, out of all valid refinements returned with a navigation query, should return actual refinement values, and includes specifications about the order and number of refinement values. You can omit RefinementConfig in your request if you do not need any of its optional items.

Note: For hierarchical refinements that are derived from managed attributes, you can additionally retrieve their full path. For information, see Retrieving the full path of hierarchical refinements.
The basic RefinementConfig format is shown in this example:
<RefinementConfig 
   Name="OrderQuantity" 
   Spec="/"
   Expose="false" 
   OrderByRecordCount="false" 
   MaximumCount="100">
</RefinementConfig>

For a given attribute, you can use only one RefinementConfig element.

The descriptions of the attributes are:
Attribute Description
Name Required. The name of the attribute.
Spec Optional. Used for walking down a hierarchy, without following the refinements as you navigate down the refinement tree. The Spec identifies the refinement parent for the query.

For example, in an empty state, a NavMenu for the initial navigation state shows managed attribute ProductCategory to be available. The user expands ProductCategory; this puts a RefinementConfig Name="ProductCategory" into the RefinementConfig and sends it in to the Endeca Server. The NavMenu shows ProductCategory refinements, including Electronics, which is expandable. The user expands Electronics; this puts a RefinementConfig Name="ProductCategory" Spec="Electronics" into the RefinementConfig and sends it to the Endeca Server.

Next, the response received from the Endeca Server contains NavMenu with the ProductCategory refinement starting at Electronics.

For a refinement with hierarchy (which is based on values from a managed attribute), refinement values will be returned for any child managed attribute values of this spec. For example, Spec="/" refers to a root managed value (such as for WineType), while Spec="Merlot" refers to a child managed value.

Expose Optional. Specify false (the default) to compute whether this attribute is a refinement at all, or true to compute whether it is a refinement and also to retrieve and expose individual refinements (if any are present).
OrderByRecordCount Optional. Specify true to order by record count based on the individual query (dynamic ordering), or false (the default) to use the default order from the Oracle Endeca Server, specified by the system-navigation_Sorting attribute in the PDR.
MaximumCount Optional. An integer that specifies a maximum limit on the number of refinements returned per standard or managed attribute.

If this setting is not specified, the number of refinements returned per attribute in the Conversation Web Service response is dictated by the value of the MaximumRefinementCount attribute in the NavigationMenuConfig element in the Conversation Web Service request. If that value is not specified, the default is 10.

Notes on RefinementConfig

Note: Keep in mind that the RefinementConfig element is an optional query parameter. However, attributes for which RefinementConfig is not included will not return refinements (unless ExposeAllPropertyRefinements is used in the group). In other words, by default, attributes in groups and refinements are collapsed. If you would like to expose attributes that have refinements, either use RefinementConfig on each attribute whose refinements you want to expose, or use ExposeAllPropertyRefinements and expose refinements for all attributes at once. The following examples illustrate these use cases.

The Expose attribute is also optional and defaults to false. Expose="false" helps improve performance.

For example, in a simple data set with three attributes in a user-defined group "Sales-Characteristics", the query:
<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig"
     Id="NavigationMenu"
     HandlerFunction="NavigationMenuHandler"
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <RefinementGroupConfig Name="Sales-Characteristics" Expose="false"/>
  </ContentElementConfig> 
 </Request>

will return information in HasRefineableProperties, but will not return refinements themselves. This is faster for the Oracle Endeca Server to compute. (To retrieve all attributes in the group, Expose should be set to true).

However, this query for the ProductType managed attribute:
<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig" Id="NavigationMenu" 
     HandlerFunction="NavigationMenuHandler"
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <RefinementGroupConfig Name="Sales-Characteristics" Expose="true"> 
       <RefinementConfig Name="ProductType" Expose="true" />
     </RefinementGroupConfig>
   </ContentElementConfig>
</Request>

will return all three managed attributes (since they are included in the Sales-Characteristics group), as well as the top-level refinement attribute values for the ProductType managed attribute. This is slightly more expensive for the Oracle Endeca Server to compute, and returns the three root managed attribute values as well as the top-level managed attribute values for ProductType, but is necessary for selecting a valid refinement.

A more advanced query option returns all the top-level managed attribute value refinements for all attributes requested (instead of a single attribute). This option involves setting the ExposeAllRefinements attribute to true. If an application sets this attribute to true, the query:
<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig"
     HandlerFunction="NavigationMenuHandler"
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0"
     Id="NavigationMenu"
     ExposeAllRefinements="true"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <RefinementGroupConfig Name="Sales-Characteristics" Expose="true"/>
  </ContentElementConfig>
</Request>

will return three managed attributes, as well as all valid top-level managed attribute values for each of these attributes.

This is the equivalent of the query:
<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
   <State/>
   <ContentElementConfig xsi:type="NavigationMenuConfig"
      Id="NavigationMenu"
      HandlerFunction="NavigationMenuHandler" 
      HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <RefinementGroupConfig Name="Sales-Characteristics" Expose="true">
       <RefinementConfig Name="UnitPrice" Expose="true" /> 
       <RefinementConfig Name="OrderQuantity" Expose="true" /> 
       <RefinementConfig Name="CustomerPONumber" Expose="true" />
      </RefinementGroupConfig>
   </ContentElementConfig>
</Request>

This is the most expensive type of query for the Oracle Endeca Server to compute, and returns three root managed attribute values as well as all the top-level managed attribute values, creating a larger network and page size strain. This method, however, is effective for creating custom navigation solutions that require all possible refinement values to be displayed at all times.