Share via

3.1.4.31.2.1 UpdateListItems

  • Article

The UpdateListItems element specifies the request that MUST be sent for the UpdateListItems operation (section 3.1.4.31).

 <s:element name="UpdateListItems">
   <s:complexType>
     <s:sequence>
       <s:element name="listName" type="s:string" />
       <s:element name="updates">
         <s:complexType mixed="true">
           <s:sequence>
             <s:element name="Batch">
               <s:complexType>
                 <s:sequence>
                   <s:element name="Method" maxOccurs="unbounded">
                     <s:complexType mixed="true">
                       <s:sequence>
                         <s:element name="Field" maxOccurs="unbounded">
                           <s:complexType>
                             <s:simpleContent>
                               <s:extension base="s:string">
                                 <s:attribute name="Name" type="s:string"/>
                                 <s:attribute name="Property" type="s:string"/>
                               </s:extension>
                             </s:simpleContent>
                           </s:complexType>
                         </s:element>
                       </s:sequence>
                       <s:attribute name="ID" type="s:unsignedInt" use="required" />
                       <s:attribute name="Cmd" type="tns:MethodCmdEnum" 
                          use="required" />
                     </s:complexType>
                   </s:element>
                 </s:sequence>
                 <s:attribute name="ListVersion" type="s:unsignedInt" />
                 <s:attribute name="OnError" type="tns:OnErrorEnum" />
                 <s:attribute name="Version" type="s:string" />
                 <s:attribute name="ViewName" type="s:string" />
                 <s:attribute name="PreCalc" 
                              type="core:TRUE_Case_Sensitive_Else_Anything"  />
                 <s:attribute name="DateInUtc" 
                              type="core:TRUE_Case_Sensitive_Else_Anything"  />
                 <s:attribute name="Properties" 
                              type="core:TRUE_Case_Sensitive_Else_Anything" />
                 <s:attribute name="LockSchema" 
                              type="core:TRUE_Case_Sensitive_Else_Anything" />
                 <s:attribute name="RootFolder" type="s:string"  />
               </s:complexType>
             </s:element>
           </s:sequence>
         </s:complexType>
       </s:element>
     </s:sequence>
   </s:complexType>
 </s:element>

listName: See the description of the listName parameter in section 3.1.4.24.2.1.

updates: Specifies the operations to perform on a list item.

Batch: There are several attributes supported by this element, as specified in the following table.

Attribute

Description

ListVersion

Specifies the version number of the list. MUST only change protocol server behavior when used in conjunction with LockSchema="TRUE". The ListVersion is set to the value of Version retrieved from a previous GetListItemChangesSinceToken call (section 3.1.4.22) with no changeToken parameter included, or a GetListItemChangesWithKnowledge call (section 3.1.4.23) with no knowledge parameter included, or where the schema on the protocol server changed, or from a call to the GetList (section 3.1.4.15) or GetListAndView (section 3.1.4.16) operations.

OnError

Specifies whether encountering an error SHOULD result in the entire operation being aborted, or whether subsequent methods in the batch SHOULD be executed. The default is to continue executing subsequent items.

Version

Specifies the version number of the service that is running on the protocol server. A version number consists of four integers in the format N.N.N.NNNN, which represent the major, minor, phase, and incremental versions of the product. This MUST be ignored by the protocol server.

ViewName

Specifies the GUID for the view to update.

PreCalc

Can be sent by the protocol client. MUST be ignored by the protocol server.

DateInUtc

Specifies whether dates passed up and returned are in UTC format. This defaults to FALSE.

Properties

Specifies whether the properties in the list item property collection are to be returned as separate fields.

LockSchema

If TRUE and ListVersion is specified with a number, the protocol server MUST return a SOAP fault with error code 0x80070666 if the schema version passed in by the protocol client does not match the list schema version on the protocol server. This defaults to FALSE.

RootFolder

Specifies the URL of the folder where list items or list folders SHOULD be inserted, updated, or deleted. This can be a fully qualified URL or a site-relative URL.

In the following examples, the list is called TestListItem, which contains a folder TestNewFolder.

Fully qualified URL example:

 http://siteservice/Lists/TestListItem/TestNewFolder

Site-relative URL:

 /Lists/TestListItem/TestNewFolder

There MUST be one Method element per operation on a list item. The Method.ID attribute SHOULD be set to a value that is unique among the other Method elements used (for example, <Method ID="1"> and <Method ID="2">). It is important to note that this identification is not related to the list item identifier that is specified in the Field element. If the Method ID attribute is unique, the protocol server MUST use the method identification to match up the request made to the protocol server with the protocol server response, so the protocol client can determine whether a particular operation failed or succeeded.

The Method operation supports several values for the Cmd attribute, as specified in the following table.

Value

Description

New

Adds a new list item to the specified list. If specified, <Field Name="ID"> MUST be ignored, because the identification is a unique number generated and set only by the protocol server. Additional field references MUST set those columns to the value specified or an error will be returned.

Update

Updates fields for a specific list item. <Field Name="ID"> MUST be specified with the value equal to the value of the identification column for the list item that SHOULD be updated by the protocol server. Additional field references MUST set those columns to the value specified or an error will be returned.

Delete

Deletes a specific list item. <Field Name="ID"> MUST be specified with the value being the value of the identification column for the list item that SHOULD be deleted by the protocol server.

Moderate

Allows the protocol client to change the moderation status field for a specific list item. <Field Name="ID"> MUST be included to specify which item. The moderation status field MUST only be updated when the list has EnableModeration set to True. The protocol client MAY update the moderation status field to any 32-bit integer value, but SHOULD interpret the following integers in a specific way:

  • 0 – The list item contains data that has been approved through the content approval process.

  • 1 – The list item contains data that has been rejected through the content approval process.

  • 2 – The list item contains data that is pending content approval.

  • 3 – The list item contains data that is in an incomplete or draft state.

  • 4 – The list item is currently scheduled in the content approval process.

Move<92>

Allows the protocol client to move a document in a document library to a new destination inside the same document library. <Field Name="ID"> MUST be specified with the value equal to the value of the identification column for the list item that SHOULD be moved by the protocol server. <Field Name="MoveNewUrl"> MUST be specified to be the new destination of the document inside the same document library.

The protocol client MUST set the Name attribute of the Field element equal to the Name attribute of the Field returned by GetList operation (section 3.1.4.15.2.1) to specify which field to modify (or add). The protocol server MUST set the field's value equal to the value of the Field element in the protocol client request or return an error indicating why the update failed, unless the field is a special field. The identification field is a special field that indicates to the protocol server which list item SHOULD be updated. The owshiddenversion field is a special field that is used for conflict detection. The protocol server MUST NOT update these special fields with the values that the protocol client includes in the request. To operate on a document in a document library, the protocol client MUST set the FileRef field to be the URL of the document.

Additionally, the property collection for a list item is added or updated on the protocol server by including one of the following field references:

Value

Description

 
 <Field   Name="MetaInfo">Value</Field>

Adds or updates the entire property collection with specified name/value pairs.

 
 <Field   Name="MetaInfo" Property="Name">Value</Field>

Adds or updates a specific name/value pair in the property collection. Name is replaced by the property name to be set and Value is replaced by the value to store.

The owshiddenversion field is for conflict detection. The protocol client and protocol server use this field to detect and manage conflicts as follows:

  • If the protocol client does not specify the owshiddenversion field reference in the UpdateListItems request, the protocol server MUST overwrite any changes in the list item or return an error.

  • If the protocol client specifies the owshiddenversion field reference in the UpdateListItems request to ensure conflict detection, the protocol client SHOULD send the value of the owshiddenversion field that it has kept from its most recent GetListItems (section 3.1.4.24), GetListItemChanges (section 3.1.4.21), or GetListItemChangesSinceToken (section 3.1.4.22), or GetListItemChangesWithKnowledge (section 3.1.4.23) request.

  • If the owshiddenversion value specified by the protocol client is equal to the owshiddenversion field's value for the list item on the protocol server, the protocol server MUST update the list item or return an error indicating why the update failed.

  • If the owshiddenversion specified by the protocol client is different than the current value of the owshiddenversion field's value for the list item on the protocol server, the protocol server MUST return error code 0x81020015, and the protocol client MUST decide how to deal with the conflict.

  • The protocol client MAY discard the changes and revert the list item values that it has stored to the values on the protocol server.

    • The protocol client MAY choose to incorporate changes on the protocol server that are returned by the UpdateListItems response and send back an UpdateListItems request containing the updates to be made to the list item with the owshiddenversion value set to the value returned by the failed UpdateListItems request.

    • The protocol client MAY choose to overwrite the list item values on the protocol server by passing back the same UpdateListItems request to the protocol server, except with the owshiddenversion value set to the value returned by the failed UpdateListItems request.

The following is an example of handling conflicts.

The first request is made to update Item 1 with a new title as follows:

 Content-Type: text/xml; charset=utf-8
 SOAPAction: "http://schemas.microsoft.com/sharepoint/soap/UpdateListItems"
  
 <?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/">
   <soap:Body>
     <UpdateListItems xmlns="http://schemas.microsoft.com/sharepoint/soap/">
     <listName>TestListItem</listName>
     <updates>
         <Batch OnError="Return">
            <Method ID="1" Cmd="Update">
                   <Field Name="ID">1</Field>
                   <Field Name="Title">Test new title</Field>
                   <Field Name="owshiddenversion">1</Field>
             </Method>
          </Batch>
       </updates>
     </UpdateListItems>
   </soap:Body>
 </soap:Envelope>
 

The protocol server gives a response that indicates a conflict:

 <?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:Body><UpdateListItemsResponse xmlns="http://schemas.microsoft.com/sharepoint/soap/"><UpdateListItemsResult><Results><Result ID="1,Update" List="{E074E60A-0126-4446-A751-A5BE7A55ED81}" Version="2"><ErrorCode>0x81020015</ErrorCode><ErrorText>Save Conflict\n\nYour changes conflict with those made concurrently by another user. To apply changes, click Back in your Web browser, refresh the page, and resubmit your changes.</ErrorText><z:row ows_ContentTypeId="0x010047334455D6BA5346AC55E03BB37AD578" ows_Title="Test new entry" ows_Num="20.0000000000000" ows_Text="TestTest" ows_DateTime="2008-03-03 15:20:00" ows_lookup="1;#Admin" ows_ID="1" ows_ContentType="Item" ows_Modified="2008-01-31 15:26:19" ows_Created="2008-01-28 08:06:11" ows_Author="1;#Admin" ows_Editor="1;#Admin" ows_owshiddenversion="3" ows_WorkflowVersion="1" ows__UIVersion="512" ows__UIVersionString="1.0" ows_Attachments="0" ows__ModerationStatus="0" ows_LinkTitleNoMenu="Test new entry" ows_LinkTitle="Test new entry" ows_SelectTitle="1" ows_Order="100.000000000000" ows_GUID="{2398096C-624B-4FA1-997F-36F6AC4776A2}" ows_FileRef="1;#Lists/TestListItem/1_.000" ows_FileDirRef="1;#Lists/TestListItem" ows_Last_x0020_Modified="1;#2008-01-28 08:06:11" ows_Created_x0020_Date="1;#2008-01-28 08:06:11" ows_FSObjType="1;#0" ows_PermMask="0x7fffffffffffffff" ows_FileLeafRef="1;#1_.000" ows_UniqueId="1;#{078CAB5C-5FEA-43EA-B23A-FB93EF35397D}" ows_ProgId="1;#" ows_ScopeId="1;#{E1CCC98A-9A01-4193-8AE5-6E6765AC3054}" ows__EditMenuTableStart="1_.000" ows__EditMenuTableEnd="1" ows_LinkFilenameNoMenu="1_.000" ows_LinkFilename="1_.000" ows_ServiceUrl="/Lists/TestListItem/1_.000" ows_EncodedAbsUrl="http://siteaddress/Lists/TestListItem/1_.000" ows_BaseName="1_" ows_MetaInfo="1;#" ows__Level="1" ows__IsCurrentVersion="1" xmlns:z="#RowsetSchema" /></Result></Results></UpdateListItemsResult></UpdateListItemsResponse></soap:Body></soap:Envelope>

The protocol client makes a second request to the protocol server that includes the updated owshiddenversion value from the protocol server's response:

 Content-Type: text/xml; charset=utf-8
 SOAPAction: "http://schemas.microsoft.com/sharepoint/soap/UpdateListItems"
  
 <?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/">
   <soap:Body>
     <UpdateListItems xmlns="http://schemas.microsoft.com/sharepoint/soap/">
     <listName>TestListItem</listName>
     <updates>
         <Batch OnError="Return">
            <Method ID="1" Cmd="Update">
                   <Field Name="ID">1</Field>
                   <Field Name="Title">Test new title</Field>
                   <Field Name="owshiddenversion">3</Field>
             </Method>
          </Batch>
       </updates>
 

The protocol server responds, indicating a successful update:

 <?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:Body><UpdateListItemsResponse xmlns="http://schemas.microsoft.com/sharepoint/soap/"><UpdateListItemsResult><Results><Result ID="1,Update" List="{E074E60A-0126-4446-A751-A5BE7A55ED81}" Version="4"><ErrorCode>0x00000000</ErrorCode><z:row ows_ContentTypeId="0x010047334455D6BA5346AC55E03BB37AD578" ows_Title="Test new title" ows_Num="20.0000000000000" ows_Text="TestTest" ows_DateTime="2008-03-03 15:20:00" ows_lookup="1;#Admin" ows_ID="1" ows_ContentType="Item" ows_Modified="2008-02-05 10:49:48" ows_Created="2008-01-28 08:06:11" ows_Author="1;#Admin" ows_Editor="1;#Admin" ows_owshiddenversion="4" ows_WorkflowVersion="1" ows__UIVersion="512" ows__UIVersionString="1.0" ows_Attachments="0" ows__ModerationStatus="0" ows_LinkTitleNoMenu="Test new title" ows_LinkTitle="Test new title" ows_SelectTitle="1" ows_Order="100.000000000000" ows_GUID="{2398096C-624B-4FA1-997F-36F6AC4776A2}" ows_FileRef="1;#Lists/TestListItem/1_.000" ows_FileDirRef="1;#Lists/TestListItem" ows_Last_x0020_Modified="1;#2008-01-28 08:06:11" ows_Created_x0020_Date="1;#2008-01-28 08:06:11" ows_FSObjType="1;#0" ows_PermMask="0x7fffffffffffffff" ows_FileLeafRef="1;#1_.000" ows_UniqueId="1;#{078CAB5C-5FEA-43EA-B23A-FB93EF35397D}" ows_ProgId="1;#" ows_ScopeId="1;#{E1CCC98A-9A01-4193-8AE5-6E6765AC3054}" ows__EditMenuTableStart="1_.000" ows__EditMenuTableEnd="1" ows_LinkFilenameNoMenu="1_.000" ows_LinkFilename="1_.000" ows_ServerUrl="/Lists/TestListItem/1_.000" ows_EncodedAbsUrl="http://siteaddress/Lists/TestListItem/1_.000" ows_BaseName="1_" ows_MetaInfo="1;#" ows__Level="1" ows__IsCurrentVersion="1" xmlns:z="#RowsetSchema" /></Result></Results></UpdateListItemsResult></UpdateListItemsResponse></soap:Body></soap:Envelope>

The following is an example of adding a new folder. Folders are a specific type of list item. To signify that the new item SHOULD be a folder, set the FSObjType field to 1 and the BaseName field to the name of the folder. These two fields are defined in [MS-WSSTS] section 2.4.2.

 Content-Type: text/xml; charset=utf-8
 SOAPAction: "http://schemas.microsoft.com/sharepoint/soap/UpdateListItems"
  
 <?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/">
   <soap:Body>
     <UpdateListItems xmlns="http://schemas.microsoft.com/sharepoint/soap/">
     <listName>TestListItem</listName>
     <updates>
         <Batch OnError="Continue">
            <Method ID="1" Cmd="New">
                   <Field Name="FSObjType">1</Field>
                   <Field Name="BaseName">TestCreateNewFolder</Field>
             </Method>
          </Batch>
       </updates>
     </UpdateListItems>
   </soap:Body>
 </soap:Envelope>

The following is an example of updating an existing item. The example updates the Title and Number fields for the list item whose ID is "1", and adds a new list item:

 Content-Type: text/xml; charset=utf-8
 SOAPAction: "http://schemas.microsoft.com/sharepoint/soap/UpdateListItems"
  
 <?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/">
   <soap:Body>
     <UpdateListItems xmlns="http://schemas.microsoft.com/sharepoint/soap/">
     <listName>TestListItem</listName>
     <updates>
         <Batch OnError="Continue">
            <Method ID="1" Cmd="Update">
                   <Field Name="ID">1</Field>
                   <Field Name="Title">ChangeThisItem</Field>
                   <Field Name="Number">3</Field>
             </Method>
            <Method ID="2" Cmd="New">
                   <Field Name="Title">MakeANewItem</Field>
                   <Field Name="Number">12</Field>
             </Method>
          </Batch>
       </updates>
     </UpdateListItems>
   </soap:Body>
 </soap:Envelope>