Skip to contents

Create, update, and delete a SharePoint list column

Source: R/sp_list.R
create_sp_list_column.Rd

create_sp_list_column() adds a column to a SharePoint list and delete_sp_list_column() removes a column to a SharePoint list. update_sp_list_column() updates a column definition for an existing column in a SharePoint list. Only properties that differ from the existing column are sent. Use sync_sp_list() for changes the Graph API can't make, such as switching a text column to multiple lines.

Usage

create_sp_list_column(
  sp_list = NULL,
  ...,
  column_name = NULL,
  column_definition = NULL,
  list_name = NULL,
  site_url = NULL,
  site = NULL,
  call = caller_env()
)

update_sp_list_column(
  sp_list = NULL,
  column_name = NULL,
  column_id = NULL,
  ...,
  list_name = NULL,
  site_url = NULL,
  site = NULL,
  column_definition = NULL,
  column_name_type = "name",
  call = caller_env()
)

delete_sp_list_column(
  sp_list = NULL,
  column_name = NULL,
  column_id = NULL,
  list_name = NULL,
  site_url = NULL,
  site = NULL,
  column_name_type = "name",
  call = caller_env()
)

Arguments

sp_list

A ms_list object. If supplied, list_name, list_id, site_url, site, drive_name, drive_id, drive, and any additional parameters passed to ... are all ignored.

...

Arguments passed on to create_column_definition

name

Column name. Graph property: name. The name can't be changed after a column is created.

display_as

Value displayed as option. For create_choice_column one ofc("checkBoxes", "dropDownMenu", "radioButtons"). For create_number_column, one of c("number", "percentage"). For create_datetime_column, one of c("default", "friendly", "standard"). Graph property: displayAs.

.col_type

Column type. Defaults to "text". Must be one of "boolean", "calculated", "choice", "currency", "dateTime", "lookup", "number", "personOrGroup", "text", "term", "hyperlinkOrPicture", "thumbnail", "contentApprovalStatus", or "geolocation".

enforce_unique

Enforce unique values in column. Graph property: enforceUniqueValues.

hidden

If TRUE, column will be hidden by default. Graph property: hidden.

deletable

If TRUE, column can't be deleted separate from the list. Graph property: isDeletable.

required

If TRUE, column will be required. Graph property: required.

default

Default value set by helper get_column_default() function. Graph property: defaultValue.

description

Column description. Graph property: description.

display_name

Column display name. Graph property: displayName.

displayname

[Deprecated] Use display_name.

validation

Column validation created with column_validation(). Graph property: validation.

indexed,sealed,propagate_changes,read_only,id

Additional arguments used by create_column_definition(). Graph properties: indexed, isSealed, propagateChanges, readOnly, and id.

multiple_lines

Logical. If TRUE, allow multiple lines of text. Graph property: allowMultipleLines.

append_changes

Logical. If TRUE, append changes to existing value for column. Graph property: appendChangesToExistingText.

lines

Whole number. Size of the text box. Graph property: linesForEditing.

max_length

Whole number. Max length in number of characters. Graph property: maxLength.

text_type

One of c("plain", "richText"). Graph property: textType.

choices

A character vector of choice options. Graph property: choices.

allow_na

If TRUE, allow NA values in choices.

na_replacement

Used as replacement by stringr::str_replace_na() on choices if they contain NA values.

allow_text

If TRUE, allow text entry in the choice column. Graph property: allowTextEntry.

decimal_places

One of c("automatic", "none", "one", "two", "three", "four", "five") or a whole number between 0 and 5. Graph property: decimalPlaces.

max,min

Minimum and maximum values allowed in number column. Graph properties: maximum and minimum.

decimals

[Deprecated] Use decimal_places.

format

For create_datetime_column(), "dateOnly" or "dateTime". Graph property: format.

locale

Locale used to set the currency symbol, e.g. "en-us". Graph property: locale.

formula

Required string with formula for calculated column definition. See examples of common formulas in lists. Reference existing columns using the display name enclosed in square brackets. The formula must start with an equals sign "=" which this function appends to the formula text if it is missing. The formula is processed with glue::glue(). Graph property: formula.

output_type

Value type returned by calculated formula. One of c("text", "boolean", "currency", "dateTime", "number"). Defaults to "text". Graph property: outputType.

lookup_list_column

Name of lookup column in the lookup list to use. Graph property: columnName.

lookup_list_id,lookup_list

Lookup list ID string or "ms_list" class object with id value in list properties. Graph property: listId.

allow_multiple_values

If TRUE, allow a lookup or term column to store multiple values. Graph property: allowMultipleValues.

allow_unlimited_length

If TRUE, allow lookup column to return any length value. Graph property: allowUnlimitedLength.

primary_lookup_column_id

If column definition is for a secondary column, the primary lookup column ID must be supplied. Graph property: primaryLookupColumnId.

allow_multiple

[Deprecated] Use allow_multiple_values for create_lookup_column() and create_term_column() or allow_multiple_selection for create_person_column() and create_group_column().

allow_multiple_selection

If TRUE, allow a person or group column to store multiple values. Graph property: allowMultipleSelection.

from_type

What type of resources to choose from. Defaults to "peopleOnly" for create_person_column() or "peopleAndGroups" for create_group_column(). Graph property: chooseFromType.

is_picture

Logical indicator for display of hyperlink value as link (FALSE, default for create_hyperlink_column()) or image (TRUE, default for create_picture_column()). Graph property: isPicture.

show_full_name

If TRUE, display the entire term path. Graph property: showFullyQualifiedName.

split

character vector (or object which can be coerced to such) containing regular expression(s) (unless fixed = TRUE) to use for splitting. If empty matches occur, in particular if split has length 0, x is split into single characters. If split has length greater than 1, it is re-cycled along x.

column_name, column_id

Column ID for column to delete.

column_definition

List with column definition created with create_column_definition() or a related function. Optional if column_name and any required additional parameters are provided. A custom element (e.g. from read_sp_list_yaml()) is dropped. A validation element is applied with the SharePoint REST API since the Graph API doesn't support it.

list_name

List name. Required if sp_list is NULL.

site_url

A SharePoint site URL in the format "https://[tenant name].sharepoint.com/sites/[site name]". Any SharePoint item or document URL can also be parsed to build a site URL using the tenant and site name included in the URL.

site

A ms_site object. If site is supplied, site_url, site_name, and site_id are ignored.

call

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

column_name_type

"name" or "displayName". Used to match column ID so column_name must be unique if column_name_type = "displayName".

Value

For create_sp_list_column(), a named list with the newly created columnDefinition resource. For update_sp_list_column(), invisibly returns the input sp_list. For delete_sp_list_column(), an empty list with a "status" attribute giving the HTTP response status code.

Details

See documentation: https://learn.microsoft.com/en-us/graph/api/list-post-columns?view=graph-rest-1.0&tabs=http