UpdateListItems Method

  • Article

The UpdateListItems method of the Lists service adds, deletes, or updates the specified items in a list on the current site.

Parameters

listName   A string that contains the internal name of the list.

updates   A Batch element that contains one or more methods for updating items and that can be assigned to a System.Xml.XmlNode object, as in the following example:

<Batch OnError="Continue" ListVersion="1" ViewName="270C0508-A54F-4387-8AD0-49686D685EB2">
   <Method ID="1" Cmd="Update">
      <Field Name="ID">4<Field>
      <Field Name="Field_Name">Value</Field>
   </Method>
   <Method ID="2" Cmd="Update">
      <Field Name="ID" >6</Field>
      <Field Name="Field_Name">Value</Field>
   </Method>
   .
   .
   .
</Batch>

The ID attribute in each Method element uniquely identifies the specific update so that errors and return values can be properly identified. Each method that is posted contains Field elements that specify the ID of the item and the new field value for the item. The field ID does not correspond to the index of the item in the collection of items for the list.

The following example shows the formats for adding a new item that contains both a Date value and a DateTime value:

<Batch OnError="Continue" ListVersion="1" ViewName="270C0508-A54F-4387-8AD0-49686D685EB2">
   <Method ID="1" Cmd="New">
      <Field Name='ID'>New</Field>
      <Field Name="Title">Value</Field>
      <Field Name="Date_Column">2007-3-25</Field>
      <Field Name="Date_Time_Column">2006-1-11T09:15:30Z</Field>
   </Method>
</Batch>

For descriptions of the various formats used for field types that can be passed in this parameter see SPListItem.

The following examples show the methods that can be posted for operations related to document libraries:

  • Create a folder

    <Batch OnError="Continue" PreCalc="TRUE" ListVersion="0" ViewName="{EF2F5A21-0FD0-4654-84ED-112B4F5A48F8}">
   <Method ID="1" Cmd="New">
      <Field Name="ID">New</Field>
      <Field Name="FSObjType">1</Field>
      <Field Name="BaseName">Name</Field>
   </Method>
</Batch>

  • Update a folder

    <Batch OnError="Continue" PreCalc="TRUE" ListVersion="0" ViewName="{EF2F5A21-0FD0-4654-84ED-112B4F5A48F8}">
   <Method ID="1" Cmd="Update">
      <Field Name="ID">3</Field>
      <Field Name="owshiddenversion">1</Field>
      <Field Name="FileRef">http://Server/[sites/][Site/]Shared Documents/Folder</Field>
      <Field Name="FSObjType">1</Field>
      <Field Name="BaseName">Name</Field>
   </Method>
</Batch>

  • Delete a folder

    <Batch OnError="Continue" PreCalc="TRUE" ListVersion="0" ViewName="{EF2F5A21-0FD0-4654-84ED-112B4F5A48F8}">
   <Method ID="1" Cmd="Delete">
      <Field Name="ID">4</Field>
      <Field Name="FileRef">http://Server/[sites/][Site/]Shared Documents/Folder</Field>
   </Method>
</Batch>

  • Update documents

    <Batch OnError="Continue" PreCalc="TRUE" ListVersion="0" ViewName="{EF2F5A21-0FD0-4654-84ED-112B4F5A48F8}">
   <Method ID="1" Cmd="Update">
      <Field Name="ID">2</Field>
      <Field Name="owshiddenversion">1</Field>
      <Field Name="FileRef">http://Server/[sites/][Site/]Shared Documents/File</Field>
      <Field Name="BaseName">Name</Field>
   </Method>
</Batch>

  • Delete documents

    <Batch OnError="Continue" PreCalc="TRUE" ListVersion="0" ViewName="{EF2F5A21-0FD0-4654-84ED-112B4F5A48F8}">
   <Method ID="1" Cmd="Delete">
      <Field Name="ID">3</Field>
      <Field Name="FileRef">http://Server/[sites/][Site/]Shared Documents/File</Field>
   </Method>
</Batch>

Return Value

An XMLDATA fragment in the following form that shows the status of each method block posted through the updates parameter and that can be assigned to a System.Xml.XmlNode object. For items successfully updated, a row fragment is returned with the updated row values.

<Results xmlns="http://schemas.microsoft.com/sharepoint/soap/">
   <Result ID="1,Update">
      <ErrorCode>0x00000000</ErrorCode>
      <z:row ows_ID="4" ows_Title="Title" ows_Modified="2003-06-19 20:31:21"
         ows_Created="2003-06-18 10:15:58" ows_Author="3;#User1_Display_Name"
         ows_Editor="7;#User2_Display_Name" ows_owshiddenversion="3" ows_Attachments="-1"
         ows__ModerationStatus="0" ows_LinkTitleNoMenu="Title" ows_LinkTitle="Title"
         ows_SelectTitle="4" ows_Order="400.000000000000"
         ows_GUID="{4962F024-BBA5-4A0B-9EC1-641B731ABFED}"
         ows_DateColumn="2003-09-04 00:00:00" ows_NumberColumn="791.00000000000000"
         xmlns:z="#RowsetSchema" />
   </Result>
   <Result ID="2,Update">
      <ErrorCode>0x00000000</ErrorCode>
      <z:row ows_ID="6" ows_Title="Title" ows_Modified="2003-06-19 20:31:22"
         ows_Created="2003-06-18 19:07:14" ows_Author="2;#User1_Display_Name"
         ows_Editor="6;#User2_Display_Name" ows_owshiddenversion="4"
         ows_Attachments="0" ows__ModerationStatus="0" ows_LinkTitleNoMenu="Title"
         ows_LinkTitle="Title" ows_SelectTitle="6" ows_Order="600.000000000000"
         ows_GUID="{2E8D2505-98FD-4E3E-BFDA-0C3DEBE483F7}"
         ows_DateColumn="2003-06-23 00:00:00" ows_NumberColumn="9001.00000000000000"
         xmlns:z="#RowsetSchema" />
   </Result>
   .
   .
   .
</Results>

In this example, the ows_Author and ows_Editor attributes pertain to lookup fields to another list in the database, representing the integer IDs of items in the UserInfo table and the actual values contained by these items within the table.

Example

The following code example modifies the values of two different field values within two items in a list on the current site. The example uses an XmlDocument object to create XmlNode objects for parameters.

This example requires that a using (C#) or Imports (Visual Basic .NET) directive be included for the System.Xml namespace.

Requirements

Platforms: Microsoft Windows Server 2003

Web Reference: http://Server_Name/[sites/][Site_Name/]_vti_bin/Lists.asmx