Article
08/21/2009

AggregateOn

Topic Last Modified: 2008-09-08

The AggregateOn element represents the property that is used to determine the order of grouped items for a grouped FindItem result set.

Schema Hierarchy

FindItem
GroupBy
AggregateOn

Syntax

<AggregateOn>
   <FieldURI/>
</AggregateOn>

<AggregateOn>
   <IndexedFieldURI/>
</AggregateOn>

<AggregateOn>
   <ExtendedFieldURI/>
</AggregateOn>

Type

AggregateOnType

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute	Description
Aggregate	Indicates the maximum or minimum value of the property identified by the FieldURI element that is used for ordering the groups of items. The following are the possible values: Minimum Maximum

Aggregate

Indicates the maximum or minimum value of the property identified by the FieldURI element that is used for ordering the groups of items. The following are the possible values:

Minimum
Maximum

Child Elements

Element	Description
FieldURI	Identifies frequently referenced properties by URI.
IndexedFieldURI	Identifies individual members of a dictionary.
ExtendedFieldURI	Identifies extended MAPI properties to get, set, or create.

Parent Elements

Element Description

Element	Description
GroupBy	Specifies arbitrary groupings for FindItem queries. The following is the XPath expression to this element: `/FindItem/GroupBy`

GroupBy

Specifies arbitrary groupings for FindItem queries.

The following is the XPath expression to this element: /FindItem/GroupBy

Remarks

The FindItem Operation can return grouped results. Within grouped results, all items that have the same value for a given grouping property are gathered together and presented as children of that group. For example, if you group by sender, all e-mails are organized into separate groups based on whether they are from sender A, sender B, and so on. These groups are children of the sender group.

Each of the groups within the sender group contains a collection of items, such as the actual e-mails that came from each sender. You can use the SortOrder element to sort the items within a group. To sort the groups based on an item's property values, however, you must use aggregation.

With aggregation, the order of groups is based on a specific property of the items within the group. When you use aggregation to sort items within a group, you must identify a representative property by which to sort the groups. You can use the AggregateOn element to specify the representative property.

When a representative property is identified, the Aggregate attribute is used to indicate whether the groups are sorted according to the maximum or the minimum value of the identified property. If the Aggregate attribute is set to Maximum, the groups are sorted beginning with the largest value for the AggregateOn property. If the Aggregate attribute is set to Minimum, the groups are sorted beginning with the smallest value for the AggregateOn property.

For example, if you want to issue a FindItem grouped query, grouping by sender, but you want to order the groups so that the group with the most recent e-mail message is on top, you can group by sender and aggregate on date/time received with an Aggregate attribute of Maximum.

The schema that describes this element is located in the EWS virtual directory of the computer that is running Microsoft Exchange Server 2007 that has the Client Access server role installed.

Example

The following example shows a grouped FindItem request and response. The example shows a request to return items grouped by the ConversationTopic property. Two groups, A and B, are returned in descending order based on the maximum value of the DateTimeReceived property.

<!-- EXAMPLE REQUEST -->

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <FindItem xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
                xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                Traversal="Shallow">
      <ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="message:ConversationTopic"/>
          <t:FieldURI FieldURI="item:DateTimeReceived"/>
        </t:AdditionalProperties>    
      </ItemShape>
      <IndexedPageItemView BasePoint="Beginning" MaxEntriesReturned="20" Offset="0"/>
      <GroupBy Order="Ascending">
        <t:FieldURI FieldURI="message:ConversationTopic"/>
        <t:AggregateOn Aggregate="Maximum">
          <t:FieldURI FieldURI="item:DateTimeReceived"/>
        </t:AggregateOn>
      </GroupBy>
      <ParentFolderIds>
        <t:DistinguishedFolderId Id="inbox"/>
      </ParentFolderIds>
    </FindItem>
  </soap:Body>
</soap:Envelope>

<!-- EXAMPLE RESPONSE -->

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="652" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                      xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                      xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:FindItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder IndexedPagingOffset="8" TotalItemsInView="8" IncludesLastItemInRange="true">
            <t:Groups>
              <t:GroupedItems>
                <t:GroupIndex>B</t:GroupIndex>
                <t:Items>
                  <t:Message>
                    <t:ItemId Id="AQAnAH=" ChangeKey="CQAAABY" />
                    <t:DateTimeReceived>2006-09-14T23:59:18Z</t:DateTimeReceived>
                    <t:ConversationTopic>B</t:ConversationTopic>
                  </t:Message>
                  <t:Message>
                    <t:ItemId Id="AQAnAHR=" ChangeKey="CQAAAw" />
                    <t:DateTimeReceived>2006-09-15T00:00:24Z</t:DateTimeReceived>
                    <t:ConversationTopic>B</t:ConversationTopic>
                  </t:Message>
                  <t:Message>
                    <t:ItemId Id="AQAnA==" ChangeKey="CQAAJXT" />
                    <t:DateTimeReceived>2006-09-15T00:22:45Z</t:DateTimeReceived>
                    <t:ConversationTopic>B</t:ConversationTopic>
                  </t:Message>
                </t:Items>
              </t:GroupedItems>
              <t:GroupedItems>
                <t:GroupIndex>A</t:GroupIndex>
                <t:Items>
                  <t:Message>
                    <t:ItemId Id="AQAnAAA==" ChangeKey="CQCJNe" />
                    <t:DateTimeReceived>2006-09-14T23:56:12Z</t:DateTimeReceived>
                    <t:ConversationTopic>A</t:ConversationTopic>
                  </t:Message>
                  <t:Message>
                    <t:ItemId Id="AQWgAA==" ChangeKey="CQAACJV6" />
                    <t:DateTimeReceived>2006-09-14T23:57:33Z</t:DateTimeReceived>
                    <t:ConversationTopic>A</t:ConversationTopic>
                  </t:Message>
                  <t:Message>
                    <t:ItemId Id="AAAA==" ChangeKey="CQA6CJXw" />
                    <t:DateTimeReceived>2006-09-15T00:23:31Z</t:DateTimeReceived>
                    <t:ConversationTopic>A</t:ConversationTopic>
                  </t:Message>
                </t:Items>
              </t:GroupedItems>
            </t:Groups>
          </m:RootFolder>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </FindItemResponse>
  </soap:Body>
</soap:Envelope>

To sort the items in a group, use the SortOrder element.

Note

The item identifiers and change keys have been shortened to preserve readability.

Element Information

Namespace	https://schemas.microsoft.com/exchange/services/2006/types
Schema Name	Types schema
Validation File	Types.xsd
Can be Empty	False

Share via