Export (0) Print
Expand All

UpdateItem Operation

Topic Last Modified: 2009-07-17

The UpdateItem operation is used to modify the properties of an existing item in the Exchange store.

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.

Aa581084.note(en-us,EXCHG.80).gifNote:
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 value of the Start and End elements 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 element must be set by the UpdateItem operation in order to preserve the calendar item’s original time zone.

The following example of an UpdateItem request shows how to set the sensitivity property on an item.

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

The item identifier and change key have been shortened to preserve readability.

The following example of an UpdateItem request shows how to append text to the body property on an item.

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

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.

The following example of an UpdateItem request shows how to delete a property on an item.

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

The item identifier and change key have been shortened to preserve readability.

The following example shows a successful response to an UpdateItem request.

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

The item identifier and change key have been shortened to preserve readability.

Show:
© 2015 Microsoft