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 Name="OrderQuantity" Spec="/" Expose="false" OrderByRecordCount="false" MaximumCount="100"> </RefinementConfig>
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. |
<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.
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.
<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.
<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.
<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.
<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.