Lists.UpdateListItems Method (Lists)

UpdateListItems Method

Switch on low bandwidth view

Community Content

In this section

Statistics Annotations (0)

Click here to expand

Collapse All

Language Filter

Lists.UpdateListItems Method (Lists)

Adds, deletes, or updates the specified items in a list on the current site.

Web Service: ListsWeb Reference: http://<Site>/_vti_bin/Lists.asmx

Syntax

Visual Basic (Declaration)

<SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/soap/UpdateListItems", RequestNamespace:="http://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace:="http://schemas.microsoft.com/sharepoint/soap/", Use:=SoapBindingUse.Literal, ParameterStyle:=SoapParameterStyle.Wrapped)> _
Public Function UpdateListItems ( _
    listName As String, _
    updates As XmlNode _
) As XmlNode

Visual Basic (Usage)

Dim instance As Lists
Dim listName As String
Dim updates As XmlNode
Dim returnValue As XmlNode

returnValue = instance.UpdateListItems(listName, updates)

[SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/soap/UpdateListItems", RequestNamespace="http://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace="http://schemas.microsoft.com/sharepoint/soap/", Use=SoapBindingUse.Literal, ParameterStyle=SoapParameterStyle.Wrapped)] 
public XmlNode UpdateListItems (
    string listName,
    XmlNode updates
)

Parameters

listName: A string that contains the name of the list. It is recommended that you use the list GUID surrounded by curly braces (i.e., "{GUID}"), but you can also use the list display name.

updates

A Batch element that contains one or more methods for adding, modifying, or deleting items and that can be assigned to a System.Xml.XmlNode object.

The following example shows how to modify column values for two specified items.

Xml

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

An empty ViewName attribute in the Batch element causes the default view to be used. 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 format for adding a new item that contains both a Date value and a DateTime value.

Xml

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

The following example shows how to delete two items.

Xml

<Batch OnError="Continue" ListVersion="1" 
ViewName="270C0508-A54F-4387-8AD0-49686D685EB2">
   <Method ID="1" Cmd="Delete">
      <Field Name='ID'>2</Field>
   </Method>
   <Method ID="2" Cmd="Delete">
      <Field Name='ID'>8</Field>
   </Method>
</Batch>

Note:
IDs for deleted items are maintained after delete operations. Consequently, the example deletes the second and eighth items in the list, but 2 and 8 are not reassigned as the IDs of other items.

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

Xml

<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

Xml

<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

Xml

<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

Xml

<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

Xml

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

Xml

<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 (Visual C#) or Imports (Visual Basic) directive be included for the System.Xml namespace.

Visual Basic

Dim listService As New Web_Reference_Folder.Lists()
listService.Credentials = System.Net.CredentialCache.DefaultCredentials

Dim strBatch As String = "<Method ID='1' Cmd='Update'>" + _
    "<Field Name='ID'>4</Field>
        <Field Name='Field_Number'>999</Field></Method>" + _
    "<Method ID='2' Cmd='Update'><Field Name='ID' >6</Field>" + _
    "<Field Name='Field_DateTime'>
        2003-11-11T09:15:30Z</Field></Method>"

Dim xmlDoc = New System.Xml.XmlDocument()

Dim elBatch As System.Xml.XmlElement = xmlDoc.CreateElement("Batch")

elBatch.SetAttribute("OnError", "Continue")
elBatch.SetAttribute("ListVersion", "1")
elBatch.SetAttribute("ViewName", 
    "0d7fcacd-1d7c-45bc-bcfc-6d7f7d2eeb40")

elBatch.InnerXml = strBatch

Dim ndReturn As XmlNode = listService.UpdateListItems("List_Name", 
    elBatch)

MessageBox.Show(ndReturn.OuterXml)

								Web_Reference_Folder.Lists listService = new Web_Reference_Folder.Lists();
listService.Credentials= System.Net.CredentialCache.DefaultCredentials;

string strBatch = "<Method ID='1' Cmd='Update'>" + 
    "<Field Name='ID'>4</Field>" +
    "<Field Name='Field_Number'>999</Field></Method>" +
    "<Method ID='2' Cmd='Update'><Field Name='ID' >6</Field>" +
    "<Field Name='Field_DateTime'>
        2003-11-11T09:15:30Z</Field></Method>"; 

XmlDocument xmlDoc = new System.Xml.XmlDocument();

System.Xml.XmlElement elBatch = xmlDoc.CreateElement("Batch");

elBatch.SetAttribute("OnError","Continue");
elBatch.SetAttribute("ListVersion","1");
elBatch.SetAttribute("ViewName",
    "0d7fcacd-1d7c-45bc-bcfc-6d7f7d2eeb40");

elBatch.InnerXml = strBatch;

XmlNode ndReturn = listService.UpdateListItems("List_Name", elBatch);

MessageBox.Show(ndReturn.OuterXml);

Reference

Lists Class
Lists Members
Lists Web Service

Other Resources

How to: Update List Items

Tags

: Add a tag

Community Content

Add new content

Annotations

Minor versioning for update comand

Minor versioning for update comand | Edit | Show History

Hi,

I have problem with updating items in document library. I have major and minor versioning settings in document library enabled. If I call object API for update fields in list items, after update new version is incremented for minor version for example 1.0, 1.1, etc.

But if I call Lists.UpdateListItems method for update item fields, it increments major version for example 1.0, 2.0, etc.

I use this batch for update items in document library:

<Batch OnError='Continue'>
  <Method ID='1' Cmd='Update'>
    <Field Name='ID'>1</Field>
    <Field Name='State'>Imported</Field>
    <Field Name='LastStateDate'>2003-06-23 00:00:00</Field>
  </Method>
</Batch>

If anybody knows how to do that please let me know.

Thanks

Tags

: question (x) Add a tag

Flag as ContentBug

adding a item to a folder in a list?

Panvega ... nbacchus | Edit | Show History

Q.Does anybody know how to add a new item into an existing folder in a custom list by using the method updatelistitems?
A. Use the copy.asmx, using the destination as the "source".

[Noelle Mallory - MSFT] Please post questions to the MSDN Forums at http://forums.microsoft.com/msdn. You will likely get a quicker response through the forum than through the Community Content.

Tags

: question (x) Add a tag

Flag as ContentBug

RootFolder

chilberto ... Tanveer1909 | Edit | Show History

The RootFolder attribute on the Batch element controls the folder of the item. This can be used to access a sub-folder. The structure is Lists/list/folder where folder is optional.

For example, if the list being updated is Contacts and there are two sub-folders Work and Personal. To update an item in the Contacts list:

And to update an item in the Work folder:

<Batch OnError="Continue" PreCalc="TRUE" ListVersion="0" RootFolder="/Lists/Contacts/Work">
<Method ID="1" Cmd="Update">
<Field Name="ID">47821</Field>
<Field Name="RefID">479485</Field>
<Field Name="CustomerNumber">59613</Field>
</Batch>

Question:I am trying to move a file from a sub folder of a list to another subfolder of the same list, Using the above example i am not able to do that, any example , sample or reference that i can use?.

Tags

: lists.asmx (x) rootfolder (x) updatelistitems (x) Add a tag

Flag as ContentBug

Update Document Name

Jigar Tanna | Edit | Show History

Hi,

I am trying to update the document's name in a Document Library using Lists.UpdateListItems method,but it seems document name is not getting updated as we can do it using browser interface...

Here is the sample query that i am using..

strBatch = "<Method ID='1' Cmd='Update'>" +
"<Field Name='ID'>1</Field>" +
"<Field Name='Title'>Updated Title11</Field>" +
"<Field Name='BaseName'>Name</Field>" +
"</Method>";

Any guidance on this would be of great help ...

Tags

: document (x) name (x) update (x) Add a tag

Flag as ContentBug

Beware - Capitalization in your caml matters

ponderitsome | Edit | Show History

I was trying to create a new folder and kept getting a SoapException stating:

Attribute ID or Cmd of element Method in parameter updates is missing or invalid

The problem was that I didnt see that my capitalization was wrong. Follow the examples listed on this MSDN page carefully and remember that XML is case-sensitive.

Incorrect code snippet:

strBatch = "<Method id='1' Cmd='New'>" + _

                "<Field Name='ID'>New</Field>" + _

                "<Field Name='FSObjType'>1</Field>" + _

                "<Field Name='BaseName'>NewFolderName</Field>" + _

            "</Method>"

Corrected code snippet (note the capitalized Method ID):

strBatch = "<Method ID='1' Cmd='New'>" + _

                "<Field Name='ID'>New</Field>" + _

                "<Field Name='FSObjType'>1</Field>" + _

                "<Field Name='BaseName'>NewFolderName</Field>" + _

            "</Method>"

Tags

: createfolder (x) lists.asmx (x) updatelistitems (x) Add a tag

Flag as ContentBug

Incorrect end-tag in first example

James. Tsai | Edit | Show History

In the first example of showing how to modify column values for two specified items.

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

<Field Name="ID">4<Field>
Should be
<Field Name="ID">4</Field>

If you copy and paste above example into your code without correct it first. You will get Error 400.

James Tsai | MCPD | SharePoint Consultant
My SharePoint Blog www.jamestsai.net/blog

Tags

: bug (x) content (x) lists.asmx (x) msdn (x) service (x) sharepoint (x) web (x) xml (x) Add a tag

Flag as ContentBug

Updating business Data Column using UpdateListItems

Mohd ABC | Edit | Show History

I am trying to update one of the columns in my list using UpdateListItems methods in lists.asmx webservice, but I am not sure what to send in the caml query here, note that I cannot do much coding because I am using infopath to achieve this, Please help I need it urgently?

Tags

: business (x) column (x) data (x) lists.asmx (x) updatelistitems (x) Add a tag

Flag as ContentBug