🔍 Code Extractor

A class representing the properties and value of a SharePoint list item field, used for updating list item form values with validation support.

Purpose

This class encapsulates the data structure required for updating SharePoint list item fields through form operations. It handles field names, values, validation exceptions, and error codes. The class extends ClientValue and provides special serialization for lookup fields and datetime values, making it suitable for SharePoint REST API operations involving list item updates.

Source Code

class ListItemFormUpdateValue(ClientValue):
    """Specifies the properties of a list item field and its value."""

    def __init__(self, name=None, value=None, has_exception=None, error_code=None):
        """
        :param str name: Specifies the field internal name for a field.
        :param str value: Specifies a value for a field.
        :param bool has_exception: Specifies whether there was an error result after validating the value for the field
        param int ErrorCode: Specifies the error code after validating the value for the field
        """
        super(ListItemFormUpdateValue, self).__init__()
        self.FieldName = name
        self.FieldValue = value
        self.HasException = has_exception
        self.ErrorCode = error_code

    def to_json(self, json_format=None):
        json = super(ListItemFormUpdateValue, self).to_json(json_format)
        if isinstance(self.FieldValue, FieldLookupValue):
            json["FieldValue"] = (
                "[{" + "'Key':'{0}'".format(self.FieldValue.LookupValue) + "}]"
            )
        elif isinstance(self.FieldValue, datetime):
            json["FieldValue"] = self.FieldValue.isoformat()
        return json

    @property
    def entity_type_name(self):
        return "SP.ListItemFormUpdateValue"

Parameters

Parameter Details

name: The internal name of the SharePoint field being updated. This should match the field's internal name in the SharePoint list schema (e.g., 'Title', 'Modified', 'CustomField'). Can be None if not yet specified.

value: The value to set for the field. Can be a string, FieldLookupValue object for lookup fields, datetime object for date/time fields, or other appropriate types depending on the field type. Can be None if not yet specified.

has_exception: Boolean flag indicating whether validation of the field value resulted in an error. True if there was a validation exception, False otherwise. Can be None if validation has not been performed.

error_code: Integer error code returned after field value validation. Provides specific error information when has_exception is True. Can be None if no error occurred or validation has not been performed.

Return Value

Instantiation returns a ListItemFormUpdateValue object that encapsulates field update information. The to_json() method returns a dictionary representation suitable for JSON serialization, with special handling for FieldLookupValue objects (formatted as SharePoint lookup syntax) and datetime objects (converted to ISO format strings). The entity_type_name property returns the string 'SP.ListItemFormUpdateValue'.

Class Interface

Methods

Attributes

Dependencies

• datetime
• office365

Required Imports

from datetime import datetime
from office365.runtime.client_value import ClientValue
from office365.sharepoint.fields.lookup_value import FieldLookupValue

Usage Example

from datetime import datetime
from office365.sharepoint.listitems.form_update_value import ListItemFormUpdateValue
from office365.sharepoint.fields.lookup_value import FieldLookupValue

# Simple text field update
text_update = ListItemFormUpdateValue(
    name='Title',
    value='New Item Title',
    has_exception=False,
    error_code=None
)

# Date field update
date_update = ListItemFormUpdateValue(
    name='DueDate',
    value=datetime(2024, 12, 31),
    has_exception=False,
    error_code=None
)

# Lookup field update
lookup_value = FieldLookupValue()
lookup_value.LookupValue = '5'
lookup_update = ListItemFormUpdateValue(
    name='AssignedTo',
    value=lookup_value,
    has_exception=False,
    error_code=None
)

# Serialize to JSON for API call
json_data = text_update.to_json()
print(json_data)

# Get entity type name
type_name = text_update.entity_type_name
print(type_name)  # Output: SP.ListItemFormUpdateValue

Best Practices

• Always set the 'name' parameter to match the exact internal field name in SharePoint, not the display name
• Use appropriate value types: FieldLookupValue for lookup fields, datetime objects for date/time fields, strings for text fields
• Check has_exception and error_code after validation operations to handle errors appropriately
• When working with lookup fields, ensure the FieldLookupValue object has the LookupValue property set to the target item ID
• The to_json() method automatically handles special formatting for lookup and datetime values, so no manual conversion is needed
• This class is typically used in collections when updating multiple fields at once in SharePoint list item operations
• Instantiate separate ListItemFormUpdateValue objects for each field being updated rather than reusing instances
• The class inherits from ClientValue, so it follows the Office365 library's serialization patterns for SharePoint operations

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class ListItemUpdateParameters 71.2% similar

  A parameter class for updating SharePoint list items, inheriting from ClientValue to represent client-side values in Office 365 operations.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/listitems/update_parameters.py

• class FieldLookupValue 69.7% similar

  Represents a lookup field value in SharePoint, encapsulating both the ID of the referenced list item and its display value.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/fields/lookup_value.py

• class ListItemVersionCollectionPosition 67.2% similar

  A class representing the position of a list item version within a collection in SharePoint/Office365, inheriting from ClientValue to provide client-side value representation.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/listitems/versions/collection_position.py

• class ListItemCreationInformation 67.1% similar

  A data class that encapsulates the properties required to create a new list item in SharePoint, including file/folder specification, name, and location.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/listitems/creation_information.py

• class ListHomeItem 66.9% similar

  A class representing a SharePoint List Home Item, inheriting from ClientValue to provide entity type information for SharePoint list home operations.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/listhome/item.py