Refinements configuration format

Use the RefinementConfig element of the Conversation Web service request to expose refinement values for standard and managed attributes.

The RefinementConfig element of the Conversation Web service request specifies which managed or standard attribute, out of all valid attributes returned with a navigation query, should return actual refinement values. Note that only the top-level refinement values are returned.

For managed attributes, if a managed attribute value is a parent, you can also use the RefinementConfig element with that managed attribute value and return its child attribute values (again, only the top-level child attribute values are returned).

The RefinementConfig element is included in the RefinementGroupConfig. This parent element returns refinements for groups.

RefinementConfig format

The basic RefinementConfig format is shown in this example:
<RefinementConfig 
   Name="OrderQuantity" 
   Spec="/"
   Expose="false" 
   OrderByRecordCount="false" 
   MaximumCount="100">
</RefinementConfig>
The descriptions of the attributes are:
Attribute Description
Name Required. The name of the standard or managed attribute value. Specifying a root value name of the managed attribute is the same as specifying a name of the managed attribute.
Spec Optional. The standard or managed attribute value spec. For a hierarchical managed attribute, refinements will be returned for any child managed attribute values of this spec.
Expose Optional. Specify false (the default) to just show the root refinement, or true to expose refinements.
OrderByRecordCount Optional. Specify true to use dynamic ranking to order by record count, or false (the default) to use the default order from the Oracle Endeca Server.
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 a value specified in the MaximumRefinementCount attribute in the NavigationMenuConfig element in the Conversation Web Service request. Further, if that value is not specified, the default is 10.

The RefinementConfig element is used in a NavigationMenuConfig element, as in this example. It exposes refinement values for the OrderQuantity attribute that is part of the group Sales-Transaction:
<Request xmlns="http://www.endeca.com/MDEX/conversation/1/0">
   <State/>
   <ContentElementConfig xsi:type="NavigationMenuConfig"
     Id="NavigationMenu"
     HandlerFunction="NavigationMenuHandler" 
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/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>

Note that you can use multiple RefinementConfig elements in a RefinementGroupConfig.

Notes on RefinementConfig

Keep in mind that the RefinementConfig element is an optional query parameter. However, attributes for which RefinementConfig is not included will not return refinements. 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/1/0">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig"
     Id="NavigationMenu"
     HandlerFunction="NavigationMenuHandler"
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <RefinementGroupConfig Name="Sales-Characteristics" Expose="false"/>
  </ContentElementConfig> 
  </ContentElementConfig>
</Request>
will return all attributes in the group but no refinement values. This is faster for the Oracle Endeca Server to compute, and returns only root values.
However, this query for the ProductType managed attribute:
<Request xmlns="http://www.endeca.com/MDEX/conversation/1/0">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig"
     Id="NavigationMenu"
     HandlerFunction="NavigationMenuHandler"
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <RefinementGroupConfig Name="Sales-Characteristics" Expose="true"/>
    <RefinementConfig Name="ProductType" Expose="true" />
    </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/1/0">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig"
     HandlerFunction="NavigationMenuHandler"
     HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/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/1/0">
   <State/>
   <ContentElementConfig xsi:type="NavigationMenuConfig"
      Id="NavigationMenu"
      HandlerFunction="NavigationMenuHandler" 
      HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/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.