hot.dev/microsoft-sharepoint / ::microsoft::sharepoint::lists

SharePoint lists and list items: list a site's lists, read items with the columns you choose, create, update and delete items, and subscribe to list changes.

A list is addressed by id or display name. Item columns live under fields; pick them with opts.fields (a Vec or comma-separated Str of internal column names such as "Title", "Status", "AssignedTo"), which becomes $expand=fields($select=...).

Filtering on fields/... needs an indexed column; otherwise pass allow-non-indexed: true to send Prefer: HonorNonIndexedQueriesWarningMayFailRandomly (works on lists under 5,000 items, may fail on larger ones).

Permissions. Sites.Read.All / Sites.ReadWrite.All, or Sites.Selected (site grant) / Lists.SelectedOperations.Selected (list grant) for app-only least privilege.

Values

LIST_LOCAL_KEYS

LIST_LOCAL_KEYS: Vec [
  "fields",
  "allow-non-indexed"
]

NON_INDEXED_PREFER

NON_INDEXED_PREFER: Str "HonorNonIndexedQueriesWarningMayFailRandomly"

Functions

create-item

fn (site-id: Str, list: Str, fields: Map): Map
fn (site-id: Str, list: Str, fields: Map, opts: Map): Map

POST /sites/{site}/lists/{list}/items - create an item from column values (internal names; nulls are dropped). Returns the item with its fields.

item ::microsoft::sharepoint::lists/create-item(site-id, "Tickets", {Title: "Printer jam", Status: "Open"})
item.id

delete-item

fn (site-id: Str, list: Str, item-id: Str): Bool
fn (site-id: Str, list: Str, item-id: Str, opts: Map): Bool

DELETE /sites/{site}/lists/{list}/items/{id} - move an item to the site recycle bin. Returns true.

field-list

fn (fields: Any): Str?

get-item

fn (site-id: Str, list: Str, item-id: Str): Map
fn (site-id: Str, list: Str, item-id: Str, opts: Map): Map

GET /sites/{site}/lists/{list}/items/{id} with its fields (opts.fields to choose columns).

get-list

fn (site-id: Str, list: Str): Map
fn (site-id: Str, list: Str, opts: Map): Map

GET /sites/{site}/lists/{list-id or display name}. opts.expand: "columns" includes the column definitions.

items-headers

fn (opts: Map): Map

The extra headers for an items query (pure): Prefer: HonorNonIndexedQueriesWarningMayFailRandomly when opts.allow-non-indexed is true.

items-query

fn (opts: Map): Map

The query parameters for reading list items (pure): expand is fields($select=...) from opts.fields (or fields for all columns), merged with an expand you pass; other OData options (filter, orderby, top, select) pass through.

::microsoft::sharepoint::lists/items-query({fields: ["Title", "Status"], top: 100})
// {expand: "fields($select=Title,Status)", top: 100}

list-all-items

fn (site-id: Str, list: Str): Vec
fn (site-id: Str, list: Str, opts: Map): Vec
fn (site-id: Str, list: Str, opts: Map, limit: Int?): Vec

Every item of a list (all pages), or at most limit. Takes the same opts as list-items; uses top: 200 unless set.

list-items

fn (site-id: Str, list: Str): Map
fn (site-id: Str, list: Str, opts: Map): Map

GET /sites/{site}/lists/{list}/items - one page of items with their fields: Graph's {value, @odata.nextLink?}. See items-query.

page ::microsoft::sharepoint::lists/list-items(site-id, "Tickets", {
  fields: ["Title", "Status", "Priority"],
  filter: "fields/Status eq 'Open'",
  allow-non-indexed: true,
  top: 50
})
map(page.value, (i) { i.fields.Title })

list-lists

fn (site-id: Str): Vec
fn (site-id: Str, opts: Map): Vec

GET /sites/{site}/lists - the site's lists and libraries (id, displayName, list.template), all pages. opts.filter e.g. "list/hidden eq false".

list-resource

fn (site-id: Str, list: Str): Str

The subscription resource for a list (pure): sites/{site}/lists/{list}.

subscribe-list

fn (site-id: Str, list: Str, notification-url: Str): Map
fn (site-id: Str, list: Str, notification-url: Str, opts: Map): Map

Subscribe notification-url to changes in a list (updated is the only change type lists support; notifications carry no item data, so read the changes with a delta query or by Modified). opts as for ::microsoft::graph::subscriptions/create-subscription (client-state, lifecycle-url, expires-in-minutes, up to 42,300).

update-item

fn (site-id: Str, list: Str, item-id: Str, fields: Map): Map
fn (site-id: Str, list: Str, item-id: Str, fields: Map, opts: Map): Map

PATCH /sites/{site}/lists/{list}/items/{id}/fields - change column values (only the ones you pass). Returns the updated field values. To clear a column, pass "" rather than null.

with-headers

fn (opts: Map): Map