Setting Fields with Formulas

Organizations can ensure data integrity and simplify user interactions by automatically setting field values on a document or object record.

Some example uses include:

  • Generating “intelligent job numbers” that incorporate other document fields like Product Name and Approval Date
  • Calculating a periodic review date by adding day, month, or year offsets from another date
  • Incrementing a field like Times in Review by adding one (1) each time the object record enters the In Review state
  • Setting the date and time a user moves a document into its Approved state, according to the user’s timezone

This functionality uses Vault’s formula language with lifecycle state entry actions, event actions, and workflow steps.

How to Configure the Entry Actions

The Set field using formula and Update Record Field entry actions allow you to set the value of a document or object field during a state change.

Set Field Using Formula Entry Action for Documents

To configure an entry action that uses the Set field using formula entry action:

  1. In the Entry Actions page, select the Set field using formula action and a document field to update.
  2. Click the calculator icon to open the formula builder.
  3. Use items from the Fields, Functions, and Operators lists to create an expression in the formula field. To move an item from these lists to the formula field, double-click on it. The formula field operates like a basic text editor. Learn about functions and valid operators in the Vault Formula Reference Guide.
  4. Click Check Syntax. Vault will let you know if your expression is valid.
  5. View the Advanced Settings by clicking on the heading.
  6. Optional: Choose a type of Run-Time Error Handling. This dictates what occurs when there are errors that prevent Vault from executing the formula.
  7. Optional: Choose an option for Blank Value Handling. This dictates how Vault handles blank field values within the formula.
  8. Click Save to close the formula builder.

Update Record Field Entry Action for Object Records

To configure an entry action that uses the Update Record Field entry action:

  1. In the Entry Actions page, select the Update Record Field action and an object record field to update.
  2. Click the calculator icon to open the formula builder.
  3. Use items from the Fields, Functions, and Operators tabs to create an expression in the formula field. Click on an item to move it to the formula field. The formula field operates like a basic text editor. Learn about functions and valid operators in the Vault Formula Reference Guide.
  4. Click Check Syntax. Vault will let you know if your expression is valid.
  5. Click Save to close the formula builder.

How to Configure an Update Field Step

To configure an Update Record Field workflow step using the formula builder:

  1. Click into the Action workflow step.
  2. From the step’s Actions menu, click Edit.
  3. Select a Field to update in the workflow step.
  4. Click the calculator icon to open the formula builder.
  5. Use items from the Fields, Functions, and Operators tabs to create an expression in the formula field. Click on an item to move it to the formula field. The formula field operates like a basic text editor. Learn about functions and valid operators in the Vault Formula Reference Guide.
  6. Click Check Syntax. Vault will let you know if your expression is valid.
  7. Click Save to close the formula builder.

Supported Field Types

This functionality supports the following field types:

  • Date
  • Number
  • Text
  • Long Text
  • Rich Text
  • Yes/No
  • Picklist
  • DateTime (only available through document lifecycle entry actions)

Some standard fields are not supported. Unsupported fields include: Merge Fields (merge_fields__v).

When defining the formula, be sure that the operators, functions, fields, and values in the formula match the field’s data type. For Date and DateTime field types, see information on time-zone handling.

Run-Time Error Handling

These options control what occurs when Vault cannot solve the formula expression. For each entry action, you can choose the type of error handling to apply:

  • Strict Handling: If there are any errors when calculating the value, Vault does not allow the document to change states. Instead, the document stays in its original state. If the state change is part of a workflow, the workflow cannot progress.
  • Flexible Handling: If there are errors when calculating the value, Vault modifies the results to allow the formula calculation to complete. This means that Vault may set the field value to “0” or blank.
Error Result with Flexible Handling
Calculated value is over the field's maximum value Set the field to the maximum value
Calculated value is under the field's minimum value Set the field to the minimum value
Calculated text value is over the field's maximum length Truncate the value at the maximum length
Calculation results in division by zero Division results in zero
Calculation results in a blank value for a required field Ignore the "Required" setting

Blank Value Handling

This dictates how Vault handles blank field values within the formula:

  • With Treat blank values as zeros, Vault substitutes a zero for the blank value, allowing you to complete the formula calculation.
  • With Treat blank values as blanks, one blank field value causes the entire expression to return a null/blank value.

Example

Formula: Document.days_in_draft__c + Document.days_pending_qc__c

Days in Draft Days Pending QC "Blanks as zeros" Result "Blanks as blanks" Result
5 5 5
9 blank 9 blank

Blanks in Multi-Function Formulas

Vault always treats blank values as blanks (not zeros) for a formula field if that formula contains multiple functions, for example, numTimesInValue(Document.status__v,”Draft”) + numTimesInValue(Document.status__v, “Pending QC”).