@SetDocField (Formula Language)

Given the unique ID of a document, sets the value of a specific field on that document. The document must reside in the current database.

Syntax

@SetDocField( documentUNID ; fieldName ; newValue )

Parameters

documentUNID

Text. The unique ID of a document. @DocumentUniqueID specifies the unique ID of the current document. To specify the unique ID of the parent document, use $Ref as the first parameter. $Ref is a special field on a response document that contains the unique ID of the parent document.

fieldName

Text. The name of a field on the document, enclosed in quotation marks. If you store the field name in a variable, omit the quotation marks here.

newValue

Text, number, time-date, time-date range, or list thereof. The value you want to give to the field.

Usage

This function does not work in column or selection formulas. @SetDocField is particularly useful in field, button, and agent formulas.

Note: Starting with Release 6, you can use @SetDocField to set the value of a field in the current document, not just in other documents in the same database.

Examples

This formula, if placed on a button in a response form, changes the Subject of the parent document to "More people are commuting by bicycle." $Ref is a special field on a response document that contains the unique ID of the parent document.
```
@SetDocField($Ref; "Subject"; "More people are commuting by bicycle")
```
This button formula changes the value of the name field in the current document to Joseph Riley:
```
@SetDocField(@DocumentUniqueID; "name"; "Joseph Riley")
```
In a database, you want to update the parent Project document whenever its child Status document changes. Each Project document has one Status document. Specifically, you want to update the latestStatus field on the Project document so that it reflects the contents of the lastAction field on the child Status document.
You write this input translation formula for the lastAction field on the Status form:
```
@SetDocField($Ref; "latestStatus"; lastAction );
lastAction
```
This button formula uses @DbLookup to retrieve the unique ID of a particular document. It then changes the value of the "employee title" field in that document to "sales associate."
```
@SetDocField(@DbLookup(""; "Magnet":"Personnel.nsf"; "Staff"; "Joe Smith";
"uniqueid"); "Employee Title"; "Sales Associate")
```
This button formula changes the value of the name field in the current document to a list containing Joseph and Riley:
```
@SetDocField(@DocumentUniqueID; "name"; "Joseph" : "Riley")
```