Retrieving groups with the Conversation Web Service

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

In other words, the Conversation Web Service returns groups for those types of queries that return refinements. Any attributes returned from the Conversation Web Service as refinements are returned as part of their respective 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_v3_0:RefinementConfig"/>
   </sequence>
   <attribute name="Name" type="cs_v3_0:NonEmptyString" use="required"/>
   <attribute name="Expose" type="boolean" use="required"/>
   <attribute name="ExposeAllPropertyRefinements" type="boolean"/>
 </complexType>
Note: The type "cs_v2_0:RefinementConfig" indicates the version of the web service. In this example, the version is 2.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.

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_v3_0:NavigationMenuItem"/>
  </sequence>
  <attribute name="HasRefineableProperties" type="boolean"/>
  <attribute name="Name" type="string" use="required"/>
</complexType>

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, WineGroup and ProvenanceGroup, but exposing top-level properties is requested for WineGroup only: 
<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  <State/>
  <NavigationMenuConfig MaximumRefinementCount="10" ReturnFullPath="true" 
    ExposeAllRefinements="false" Id="Navigation">
    <RefinementGroupConfig Name="WineGroup" Expose="true">
       <RefinementConfig Name="Flavors" Expose="true" MaximumCount="2"/>
    </RefinementGroupConfig>
    <RefinementGroupConfig Name="ProvenanceGroup" Expose="false"/>
  </NavigationMenuConfig>
</Request>

The Conversation Web Service result includes results for one group, WineGroup, for which refinements were requested to be exposed.

Note: When a group is retrieved with the Conversation Web Service, the attribute ordering is determined by the order in which attributes were listed when the group was initially defined (either in Studio, or using the Configuration Web Service). 
<cs:NavigationMenu Id="Navigation">
   <cs:NavigationMenuItemGroup Name="WineGroup" HasRefineableProperties="true">
      <cs:NavigationMenuItem Name="WineType" DisplayName="Wine Type" MultiSelect="None" HasMore="true">
         <cs:ExposureControl Exposed="false"/>
         <cs:RootDimensionValue DimensionName="WineType" Spec="/"/>
         <cs:FullPath>
            <cs:DimensionValue DimensionName="WineType" Spec="/">WineType</cs:DimensionValue>
         </cs:FullPath>
      </cs:NavigationMenuItem>
      <cs:NavigationMenuItem Name="Wine" DisplayName="Wine Name" MultiSelect="None" HasMore="true">
         <cs:ExposureControl Exposed="false"/>
      </cs:NavigationMenuItem>
      <cs:NavigationMenuItem Name="Region" DisplayName="Region Grown" MultiSelect="None" HasMore="true">
         <cs:ExposureControl Exposed="false"/>
      </cs:NavigationMenuItem>
      <cs:NavigationMenuItem Name="Flavors" DisplayName="Flavors" MultiSelect="None" HasMore="true">
         <cs:ExposureControl Exposed="true"/>
         <cs:Refinement Name="Flavors" Spec="Almond" Label="Almond" Count="1312"/>
         <cs:Refinement Name="Flavors" Spec="Anise" Label="Anise" Count="1626"/>
      </cs:NavigationMenuItem>
   </cs:NavigationMenuItemGroup>
</cs:NavigationMenu>