AggregateOn
Last modified: March 16, 2009
Applies to: Exchange Server 2007 | Exchange Server 2010
The AggregateOn element represents the property that is used to determine the order of grouped items for a grouped FindItem result set.
<AggregateOn>
<FieldURI/>
</AggregateOn>
<AggregateOn>
<IndexedFieldURI/>
</AggregateOn>
<AggregateOn>
<ExtendedFieldURI/>
</AggregateOn>
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:
|
Child Elements
Element |
Description |
|---|---|
Identifies frequently referenced properties by URI. |
|
Identifies individual members of a dictionary. |
|
Identifies extended MAPI properties to get, set, or create. |
Parent Elements
Element |
Description |
|---|---|
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 MicrosoftExchange 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 |
See Also