# 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 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 <a href="/en/gr/42857/">Vault's formula language</a> with lifecycle state entry actions, event actions, and workflow steps.

## How to Configure the Entry Actions

The _Set field using formula_ and _Update 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 <a href="/en/gr/52324/">Vault Formula Reference Guide</a>.
  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][3] that prevent Vault from executing the formula.
  7. Optional: Choose an option for **Blank Value Handling**. This dictates how Vault handles [blank][4] field values within the formula.
  8. Click **Save** to close the formula builder.

### Update Field Entry Action for Object Records

To configure an entry action that uses the _Update Field_ objet record entry action:

  1. In the **Entry Actions** page, select the **Update 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 <a href="/en/gr/52324/">Vault Formula Reference Guide</a>.
  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 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**, **Operators**, and **Workflow** 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 <a href="/en/gr/52324/">Vault Formula Reference Guide</a>.
  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 <a href="/en/gr/42857/#time-zone-handling">time-zone handling.</a>

## Run-Time Error Handling {#errors}

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.

<table class="wbord">
  <tr>
    <td>
      <strong>Error</strong>
    </td>
    <td>
      <strong>Result with Flexible Handling</strong>
    </td>
  </tr>
  <tr>
    <td>
      Calculated value is over the field's maximum value
    </td>
    <td>
      Set the field to the maximum value
    </td>
  </tr>
  <tr>
    <td>
      Calculated value is under the field's minimum value
    </td>
    <td>
      Set the field to the minimum value
    </td>
  </tr>
  <tr>
    <td>
      Calculated text value is over the field's maximum length
    </td>
    <td>
      Truncate the value at the maximum length
    </td>
  </tr>
  <tr>
    <td>
      Calculation results in division by zero
    </td>
    <td>
      Division results in zero
    </td>
  </tr>
  <tr>
    <td>
      Calculation results in a blank value for a required field
    </td>
    <td>
      Ignore the "Required" setting
    </td>
  </tr>
</table>

## Blank Value Handling {#blank}

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_

<table class="wbord">
  <tr>
    <td>
      <strong>Days in Draft</strong>
    </td>
    <td>
      <strong>Days Pending QC</strong>
    </td>
    <td>
      <strong>"Blanks as zeros" Result</strong>
    </td>
    <td>
      <strong>"Blanks as blanks" Result</strong>
    </td>
  </tr>
  <tr>
    <td>
      5
    </td>
    <td>
    </td>
    <td>
      5
    </td>
    <td>
      5
    </td>
  </tr>
  <tr>
    <td>
      9
    </td>
    <td>
      blank
    </td>
    <td>
      9
    </td>
    <td>
      blank
    </td>
  </tr>
</table>

### 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")_.

 [3]: #errors
 [4]: #blank