Retrieving groups

Any request that asks for refinements is also requesting groups, if the attributes that are going to be returned are configured as part of groups.

The request for groups is implemented with the RefinementGroupConfig element of the Conversation Web service request. This element contains one or more RefinementConfig elements that list which attributes, out of all valid properties returned with a navigation query, should return actual refinement values. Note that only the top-level refinement values are returned.

The complex type RefinementGroupConfig has the following format:
<complexType name="RefinementGroupConfig">
 <sequence>
 <element maxOccurs="unbounded" minOccurs="0" 
   name="RefinementConfig" type="cs_v1_0:RefinementConfig"/>
 </sequence>
    <attribute name="Name" type="cs_v1_0:NonEmptyString" use="required"/>
    <attribute name="Expose" type="boolean" use="required"/>
    <attribute name="ExposeAllPropertyRefinements" type="boolean"/>
 </complexType>
Note: The type "cs_v1_0:RefinementConfig" indicates the version of the web service. In this example, the version is 1.0. It may or may not correspond to the version of the Conversation Web Service that you are using and that is currently supported.
The meanings of the attributes are:
Attribute Description
Name Required. The name of the group.
Expose Required. Specify true to expose all top-level attributes in the group, or false (the default) to just show the root of the group.
Note: If an attribute is a managed attribute, it contains a hierarchy of attributes under its root. Whether these nested attributes are exposed is controlled by the Expose attribute on the RefinementConfig element for each attribute within a managed attribute. The default for Expose is false.
ExposeAllPropertyRefinements Optional. If set to true, specifies whether to expose all attribute refinements underneath each managed attribute that has them. The default is false (if this attribute is not specified).

This setting supersedes the Expose attribute on the RefinementConfig element for each attribute refinement.

Groups are returned in a NavigationMenuItemGroup element that contains one or more NavigationMenu elements, each of which returns refinements in the NavigationMenuItem. Here is the format for the NavigationMenuItemGroup:
<complexType name="NavigationMenuItemGroup">
 <sequence>
   <element maxOccurs="unbounded" minOccurs="0" name="NavigationMenuItem" 
     type="cs_v1_0:NavigationMenuItem"/>
 </sequence>
   <attribute name="HasRefineableProperties" type="boolean"/>
   <attribute name="Name" type="string" use="required"/>
</complexType>
Note: The type "cs_v1_0:RefinementConfig" indicates the version of the web service. In this example, the version is 1.0. It may or may not correspond to the version of the Conversation Web Service that you are using and that is currently supported.

The required attribute HasRefineableProperties specifies whether a group has attributes that could be refined further.

Note: From the perspective of controlling the groups behavior in the front-end application, another attribute may be useful. It is the ExposureControl attribute of type boolean, on the NavigationMenuItem. If set to false (the default), it does not expose refinements contained within NavigationMenuItem. If set to true, it exposes the collection of refinements.

To request groups:

In the Conversation Web Service request, for each group, specify its name and whether to expose all top-level attributes in the group by specifying the value of Expose attribute on the RefinementGroupConfig element. Optionally, you can also use this attribute on the refinements within the group.
In this example, two groups are requested, FlavorGroup and ProvenanceGroup, but exposing top-level properties is requested for FlavorGroup only:
<Request xmlns="http://www.endeca.com/MDEX/conversation/1/0">
  <State/>
  <ContentElementConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="NavigationMenuConfig" 
    MaximumRefinementCount="10" 
    ReturnFullPath="true" 
    ExposeAllRefinements="false" 
    HandlerFunction="NavigationMenuHandler" 
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0" 
    Id="Navigation">
    <RefinementGroupConfig Name="FlavorGroup" Expose="true">
       <RefinementConfig Name="Flavors" Expose="true" MaximumCount="2"/>
    </RefinementGroupConfig>
    <RefinementGroupConfig Name="ProvenanceGroup" Expose="false"/>
  </ContentElementConfig>
</Request>
The Conversation Web Service result includes results for one group, FlavorGroup, for which refinements were requested to be exposed:
<cs:ContentElement xsi:type="cs:NavigationMenu" Id="Navigation">
  <cs:NavigationMenuItemGroup Name="FlavorGroup" HasRefineableProperties="true">
    <cs:NavigationMenuItem Name="Flavors" DisplayName="Flavors" MultiSelect="And" HasMore="true">
      <cs:ExposureControl Exposed="true">
        <cs:Operator OwnerId="Navigation" xsi:type="cs:RefinementHideOperator" 
           Name="Flavors" Group="FlavorGroup" Spec="/"/>
      </cs:ExposureControl>
      <cs:Refinement Name="Flavors" Spec="Currant" Label="Currant">
        <cs:Operator xsi:type="cs:RefinementOperator" Name="Flavors" Spec="Currant"/>
      </cs:Refinement>
      <cs:Refinement Name="Flavors" Spec="Oak" Label="Oak">
        <cs:Operator xsi:type="cs:RefinementOperator" Name="Flavors" Spec="Oak"/>
      </cs:Refinement>
      <cs:RootDimensionValue DimensionName="Flavors" Spec="/"/>
      <cs:FullPath><!-- path information omitted in this example--></cs:FullPath>
    </cs:NavigationMenuItem>
    <cs:NavigationMenuItem Name="Drinkability" DisplayName="Drinkability" 
        MultiSelect="None" HasMore="true">
      <cs:ExposureControl Exposed="false">
        <cs:Operator OwnerId="Navigation" xsi:type="cs:RefinementExposeOperator"
           Name="Drinkability" Group="FlavorGroup" Spec="/"/>
      </cs:ExposureControl>
      <cs:RootDimensionValue DimensionName="Drinkability" Spec="/"/>
      <cs:FullPath><!-- path information omitted in this example --></cs:FullPath>
      </cs:NavigationMenuItem>
    </cs:NavigationMenuItemGroup>
  <cs:NavigationMenuItemGroup Name="ProvenanceGroup" HasRefineableProperties="true"/>
</cs:ContentElement>