Changes data

quotecloud_add_document_data_item

Add a data item (merge field) to one document, optionally set its value and convert its placeholders, all in one call. Supply exactly one of dataItemId: link an existing company-wide definition into the document: or definition: create a new item that exists only on this document (on a template, only on that template). value sets the document’s value for the item in the item’s own type. convertPlaceholders true converts every {{Label}} placeholder in the document’s text blocks, table cells and header or footer blocks; an array converts only the listed labels. A placeholder is the text {{Label}} in a text block, a table cell, or a header or footer block, where Label is the exact label (case-sensitive) of a data item on the document or of a system item such as Document ID, Document Title, Your Company Name or Recipient First Name: list them with quotecloud_list_custom_data_definitions (connection document, includeSystemItems true). Each placeholder becomes the merge-field node the renderer resolves. If any placeholder matches no item, or matches more than one (a short system label such as First Name or Company Name belongs to both the sender and the recipient; use the item’s uniqueLabel, such as Recipient First Name or Recipient Company Name), the whole call is refused and nothing is written. All-or-nothing: any refusal leaves the document unchanged. Works in either contentMode and on documents stored only in the data file. Acquires the editor lease and the settings lock. Requires documents:write and only runs when documents.edit is enabled; on a template also templates.contentEdits and manageDocumentTemplates. Not dangerous: no confirmation is required.

Inputs

documentIdRequired
Convex document ID or company-scoped numeric display ID. string
lockTokenRequired
Stable opaque token for this agent edit session. Reuse it to heartbeat owned element locks. string
dataItemIdOptional
An existing company-wide definition to link into the document. string
definitionOptional
A new definition scoped to this document only. object
valueOptional
The document’s value for the item. null clears it. value
convertPlaceholdersOptional
true converts every {{Label}} placeholder in the document; an array of labels converts only those. value