Formula Field API

This document contains the Formula field API format, supported attributes, operations, and examples.

Use this page to add a formula field to template XML. A formula field is read-only and calculates its value from other fields.

Formula field example

<formula
    name="total_amount"
    placeholder="Total"
    search="true"
    precision="2"
    formatting="true"
    trailingZeros="true"
>SUM({line_total},{doc2::tax})</formula>

Required attributes

• name — field name. Use 1 to 128 characters. Do not use &, ", <, or >. Keep the value unique within one document.

• value — formula expression inside the element body. Use one supported operation per formula.

Optional attributes

• placeholder — placeholder text shown in the template and envelope. Use 0 to 1024 characters. If you omit it, the envelope shows the field name.

• search — set to true if the field value should be available in envelope search. If you omit it, the default value is false.

• precision — number of decimal places allowed. If you omit it, the default value is 2.

• formatting — set to true to display the value in the user's local number format.

• trailingZeros — set to true to keep decimal zeros after calculation. Use this attribute with precision.

Supported operations

• SUM

• PRODUCT

• SUBTRACT

• DIVIDE

• COUNTA

• MAX

• MIN

Examples

Cross-document formula

SUM({field1},{doc2::field2})

• {field1} — value from the same document.

• {doc2::field2} — value of field2 from document doc2.

Dynamic table formula

SUM({field1})

• {field1} — field name inside the dynamic table.

• The formula sums values from all rows.

Related topics

• Template Dynamic Fields API

• Dynamic Table API

• Number Field API

• Fill Envelope