• Article

UpdateFolder Operation

Topic Last Modified: 2008-09-05

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]

<?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]

<?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]

<?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: