UpdateFolder Operation
Last modified: May 15, 2009
Applies to: Exchange Server 2007 | Exchange Server 2010
In this article
UpdateFolder Request Example
UpdateFolder Response Example
UpdateFolder Error Response Example
The UpdateFolder operation is used to modify properties of an existing item in the Exchange store. Each UpdateFolder operation consists of the following:
A FolderId element that specifies a folder to update.
An internal path of an element in the folder, as specified by the folder shape, which specifies the data to update.
A folder that contains the new value of the updated field, if the update is not a deletion.
Remarks
Three basic update actions can be performed on an item. These actions are listed in the following table.
Action |
Description |
|---|---|
Append |
The append action adds data to an existing property. It preserves the data that is currently there. Append is not applicable to all properties. |
Set |
The set action replaces data for a property if it contains data, or creates the property and sets its value if it does not exist. The set action is only applicable to writable properties. |
Delete |
The delete action removes a property from a folder. This is different than setting it to an empty value. When complete, the property does not exist for the folder. Delete is only applicable to writable properties. |
UpdateFolder Request Example
Description
The following example of an UpdateFolder request shows how to update a folder display name.
Code
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<UpdateFolder xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<FolderChanges>
<t:FolderChange>
<t:FolderId Id="AScA" ChangeKey="GO3u/"/>
<t:Updates>
<t:SetFolderField>
<t:FieldURI FieldURI="folder:DisplayName"/>
<t:Folder>
<t:DisplayName>NewFolderName</t:DisplayName>
</t:Folder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</FolderChanges>
</UpdateFolder>
</soap:Body>
</soap:Envelope>
Comments
This example changes the display name of the folder to NewFolderName.
Note
The values of the Id and ChangeKey attributes of the FolderId element have been shortened for readability.
Request Elements
The following elements are used in the request:
See the schema for additional elements that you can use to form an UpdateFolder request.
Note
The default location of the schema is in the EWS virtual directory on the computer that has the Client Access server role installed.
UpdateFolder Response Example
Description
The following example shows a successful response to the UpdateFolder request. In this example, the new change key is returned to reflect the updated status of the folder.
Code
<?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="685" MinorBuildNumber="8"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<UpdateFolderResponse 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:UpdateFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:Folder>
<t:FolderId Id="AAAlAFVz" ChangeKey="AQAAAB" />
</t:Folder>
</m:Folders>
</m:UpdateFolderResponseMessage>
</m:ResponseMessages>
</UpdateFolderResponse>
</soap:Body>
</soap:Envelope>
Comments
Note
The folder ID and the change key have been shortened to preserve readability.
The folder ID that is returned in the response represents the updated folder.
Successful Response Elements
The following elements are used in the response:
UpdateFolder Error Response Example
Description
The following example shows an error response to an UpdateFolder request.
Code
<?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="685" MinorBuildNumber="8"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<UpdateFolderResponse 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:UpdateFolderResponseMessage ResponseClass="Error">
<m:MessageText>The change key is invalid.</m:MessageText>
<m:ResponseCode>ErrorInvalidChangeKey</m:ResponseCode>
<m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
<m:Folders />
</m:UpdateFolderResponseMessage>
</m:ResponseMessages>
</UpdateFolderResponse>
</soap:Body>
</soap:Envelope>
Comments
This example shows an error response that is caused by an invalid ChangeKey attribute in the request.
Error Response Elements
The following elements are used in the error response: