UpdateItem operation
The UpdateItem operation is used to modify the properties of an existing item in the Exchange store.
Remarks
You can perform three basic update actions on an item. The following table lists the actions that you can perform.
| Action | Description |
|---|---|
| Append |
Adds data to an existing property. This action preserves the current data. Append does not apply to all properties. |
| Set |
Replaces data for a property if the property contains data, or creates the property and sets its value if the property does not exist. The set action is only applicable to writable properties. |
| Delete |
Removes a property from an item. This differs from setting a property to an empty value. When this action is finished, the property does not exist for the item. Delete is only applicable to writable properties. |
An UpdateItem call can be used to modify one or more items, and one or more properties on each item. The ItemChanges element contains all the modifications that are to be performed as part of this call. The ItemChange element, a child of the ItemChanges element, represents the modifications to be performed on a single item. The ItemChange element contains a set of update actions that can be performed on a single item. These changes are contained in the Updates (Item) element. The ItemId element identifies the item to update. To update more than one property on an item, a SetItemField, AppendToItemField, or DeleteItemField must be provided for each property that requires the update.
Note
Update actions are applied in the order in which they are specified.
For each change, you have to specify the path of the property to change and a representation of that item with its new value. The delete action is slightly different in that only the path of the property that should be deleted is required. For set and append actions, the path that is specified must refer to the same property that is being set in the item representation. If these differ, an error will be returned.
The UpdateItem operation can set the Start and End time of an Exchange store item. In an UpdateItem request, the Start time can be set without also setting the End time. This can cause an error if the Start time is later than the End time. Be aware that client applications must adjust the End time when the Start time is changed in order to preserve the duration.
When a single calendar item is updated to become a recurring master calendar item, the MeetingTimeZone property must be set by the UpdateItem operation in order to preserve the calendar item's original time zone.
SetItemField request example
Description
The following example of an UpdateItem request shows how to set the sensitivity property on an item.
Code
<?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="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AutoResolve"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<ItemChanges>
<t:ItemChange>
<t:ItemId Id="AAAtAEFkb..." ChangeKey="CQAAABYAAAB..."/>
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="item:Sensitivity"/>
<t:Message>
<t:Sensitivity>Normal</t:Sensitivity>
</t:Message>
</t:SetItemField>
</t:Updates>
</t:ItemChange>
</ItemChanges>
</UpdateItem>
</soap:Body>
</soap:Envelope>
Comments
The item identifier and change key have been shortened to preserve readability.
SetItemField Request Elements
The following elements are used in the request:
AppendToItemField request example
Description
The following example of an UpdateItem request shows how to append text to the body property on an item.
Code
<?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="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AutoResolve"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<ItemChanges>
<t:ItemChange>
<t:ItemId Id="AAAtAEFkbW..." ChangeKey="CQAAABYA..."/>
<t:Updates>
<t:AppendToItemField>
<t:FieldURI FieldURI="item:Body"/>
<t:Message>
<t:Body BodyType="Text">Some additional text to append</t:Body>
</t:Message>
</t:AppendToItemField>
</t:Updates>
</t:ItemChange>
</ItemChanges>
</UpdateItem>
</soap:Body>
</soap:Envelope>
Comments
The following properties support the append action:
message:ReplyTo
item:Body
All the recipient and attendee collection properties
The item identifier and change key have been shortened to preserve readability.
AppendToItemField Request Elements
The following elements are used in the request:
DeleteItemField request example
Description
The following example of an UpdateItem request shows how to delete a property on an item.
Code
<?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="http://schemas.xmlsoap.org/soap/envelope/" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AutoResolve"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<ItemChanges>
<t:ItemChange>
<t:ItemId Id="AAAtAEFkbWluaXN0cm..." ChangeKey="CQAAABYAA..."/>
<t:Updates>
<t:DeleteItemField>
<t:FieldURI FieldURI="item:Body"/>
</t:DeleteItemField>
</t:Updates>
</t:ItemChange>
</ItemChanges>
</UpdateItem>
</soap:Body>
</soap:Envelope>
Comments
The item identifier and change key have been shortened to preserve readability.
DeleteItemField Request Elements
The following elements are used in the request:
Successful response example
Description
The following example shows a successful response to an UpdateItem request.
Code
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://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="664" MinorBuildNumber="0"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"/>
</soap:Header>
<soap:Body>
<UpdateItemResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:UpdateItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Items>
<t:Message>
<t:ItemId Id="AAAtAEFkbW..." ChangeKey="CQAAABYAAA..."/>
</t:Message>
</m:Items>
</m:UpdateItemResponseMessage>
</m:ResponseMessages>
</UpdateItemResponse>
</soap:Body>
</soap:Envelope>
Comments
The item identifier and change key have been shortened to preserve readability.
Successful response elements
The following elements are used in the response: