Retrieving refinements with the API

Displaying standard and managed attribute refinement values is the core concept behind Guided Navigation.

The complex type PropertyListConfig returns a list of all available attributes in the system. It contains an element Property, which includes pertinent information about an attribute including its key, display name, and other options. The PDR (and DDR, if present) is included for those clients of the Conversation Web Service that prefer to read descriptor records directly.

The following example request illustrates how to obtain a list of attributes:
<ns:Request>
  <ns:ContentElementConfig 
    Id="AttributeList" xsi:type="ns:PropertyListConfig" 
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0" 
    HandlerFunction="PropertyListHandler" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  </ns:ContentElementConfig>
</ns:Request>

Such a request returns information that describes all attributes, and includes all characteristics of the attributes.

The following example shows the characteristics of the managed attribute ProductCategory. Using this output, you can view the values of PDRs and DDRs for the attribute ProductCategory, indicating whether the attribute is searchable, and specifying other characteristics contained in the PDR and DDR for this managed attribute:
<cs:Property Key="ProductCategory" Type="mdex:string" Dimension="true" 
     DisplayName="Product Category" Refinable="true">
   <cs:PropertyRecord>
     <mdex-property_DisplayName type="mdex:string">Product Category</mdex-property_DisplayName>
     <mdex-property_IsPropertyValueSearchable type="mdex:boolean">false</mdex-property_IsPropertyValueSearchable>
     <mdex-property_IsSingleAssign type="mdex:boolean">false</mdex-property_IsSingleAssign>
     <mdex-property_IsTextSearchable type="mdex:boolean">false</mdex-property_IsTextSearchable>
     <mdex-property_IsUnique type="mdex:boolean">false</mdex-property_IsUnique>
     <mdex-property_Key type="mdex:string">ProductCategory</mdex-property_Key>
     <mdex-property_TextSearchAllowsWildcards type="mdex:boolean">false</mdex-property_TextSearchAllowsWildcards>
     <mdex-property_Type type="mdex:string">mdex:string</mdex-property_Type>
     <system-navigation_Select type="mdex:string">single</system-navigation_Select>
     <system-navigation_ShowRecordCounts type="mdex:boolean">true</system-navigation_ShowRecordCounts>
     <system-navigation_Sorting type="mdex:string">lexical</system-navigation_Sorting>
   </cs:PropertyRecord>
   <cs:DimensionRecord>
     <mdex-dimension_EnableRefinements type="mdex:boolean">true</mdex-dimension_EnableRefinements>
     <mdex-dimension_IsDimensionSearchHierarchical type="mdex:boolean">false</mdex-dimension_IsDimensionSearchHierarchical>
     <mdex-dimension_IsRecordSearchHierarchical type="mdex:boolean">false</mdex-dimension_IsRecordSearchHierarchical>
     <mdex-dimension_Key type="mdex:string">ProductCategory</mdex-dimension_Key>
   </cs:DimensionRecord>
</cs:Property>

In addition, after a user creates a query using record and/or value search, only valid remaining refinement values are provided to the user to refine that query. This allows the user to reduce the number of matching records without creating an invalid query.

To display refinements (standard and managed attributes), they need to be requested, that is, included in the Conversation Web service request that describes the navigation menu. If the refinements belong to a group, this group needs to be requested.

The following example shows the request in which a group of refinements is requested. This example assumes that the group Sales-Transaction exists and includes the refinements (attributes) CustomerPONumber, OrderQuantity, and UnitPrice:
<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"/>
  </ContentElementConfig>
</Request>
These refinements will be returned along with the group Sales Transaction in which they are included.

If you would like to retrieve refinements that are not explicitly included in any user-configured groups, you can request a group system-navigation_InternalGroup. This group exists in the Oracle Endeca Server and includes all refinements that are not members of any other groups.