{updateitem:...}

Description

Updates one or more fields of an existing item, given its long (32-character) item id. This is the write companion to newitem (which creates a new item from a template) and ensureitem (which finds an item or creates it). updateitem changes an item that already exists. Pass the item id first, then field/value pairs: a 16-character field id followed by the new value. To replace the field value give the value directly; to add another value to a multi-value field, append a plus sign to the field id. A value may be a single scalar, or a JSON array for several values at once. Security: this only writes on slices whose Allow anonymous editing of items setting is All items (or Only by Planned tasks when run from cron). On any other slice updateitem makes no change and returns nothing. The plan is to honour per-field permissions in the future. Conditional update: if the item id is empty or not a valid id, nothing is updated. This lets you drive an update from a lookup - feed an ids lookup as the id and the update only fires when the lookup matches. Returns the item id when an item was updated, and nothing otherwise. On this Czech-localized demo install the test-data slice forbids anonymous editing, so the examples below return an empty result and never change the fixture; the field-changing forms are shown as illustrative.

Parameters

long_item_id required default (empty string)

The 32-character long id of the item to update. If it is empty or not a valid id, nothing is updated - this is how you make the update conditional (feed an ids lookup and the update only fires on a match).

field optional default (empty string)

A 16-character field id naming the field to write. Append a plus sign to the field id to ADD the value to a multi-value field instead of replacing it.

new_value optional default (empty string)

The value to write into the field. A single scalar (for a one-value field like the headline), or a JSON array such as ["a","b"] to set several values at once. With a plus sign on the field id, this value is added rather than replacing the existing ones.

field_n:new_value_n optional default (empty string)

Optional further field/value pairs. updateitem accepts any number of field/value pairs after the id, so one call can change several fields of the same item at once.

Examples

test[{updateitem:}]

Expected[]

Actual[]

With no item id, updateitem does nothing and returns an empty string. The surrounding square brackets are only here to make the empty result visible.

test[{updateitem:not-a-real-id:headline........:X}]

Expected[]

Actual[]

When the first argument is not a valid 32-character item id, updateitem does nothing and returns nothing.

test[{updateitem:5726c2c6b035d7aab450d1794e9e90d7:headline........:Changed}]

Expected[]

Actual[]

This points at a real item in the test-data slice, but that slice has Allow anonymous editing of items set to Not allowed, so updateitem writes nothing and returns an empty string. The fixture item is left untouched. Enable anonymous editing on a slice to allow updates.

test[{updateitem:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-headline........-==-NoSuchItem}:integer.........:0}]

Expected[]

Actual[]

Feeding an ids lookup as the item id makes the update conditional. Here the lookup matches no item, so updateitem receives an empty id and does nothing. This is the idiom for update-only-if-found.

virtual{updateitem:c239cb267837a25b4efb5892ca4f4324:headline........:New title}

Expected(returns the item id, e.g. c239cb267837a25b4efb5892ca4f4324)

On a slice that permits anonymous editing, this sets the headline of item c239... to New title and returns the item id. Shown illustratively; it is not run as a test.

virtual{updateitem:c239cb267837a25b4efb5892ca4f4324:category........+:["news"]}

Expected(returns the item id)

Appending a plus sign to the field id adds news to the multi-value category field instead of replacing the existing values. Illustrative; not run as a test.

virtual{updateitem:c239cb267837a25b4efb5892ca4f4324:headline........:New title:category........:["news","events"]}

Expected(returns the item id)

One call can change several fields. headline gets a single value; category gets two values via a JSON array. Illustrative; not run as a test.

virtual{updateitem:{ids:5d56f1faa24d5d723bb4c921289a0654:d-token...........-==-{qss:token}}:status_code.....:3}

Expected(empty, or the item id when the token matches a subscriber)

A production newsletter unsubscribe: look up the subscriber whose token matches the one from the query string, and if found set its status to 3 (trash). When nothing matches, the empty id makes updateitem a no-op. Slice id and field anonymized; runtime-dependent, so illustrative.

← All expressions