Perform Calculations

What Are Arithmetic Functions?

Arithmetic functions in S-Docs allow you to perform mathematical calculations directly within your document templates. Instead of pre-calculating values in Salesforce formulas, you can dynamically compute results using static numbers, numeric fields, or even date values at the time of document generation.

How Are They Used in S-Docs?

Arithmetic functions enable you to:

• Perform calculations with numeric fields from Salesforce records
• Add, subtract, multiply, or divide values inline
• Calculate date differences or project future dates
• Apply conditional logic based on calculated results
• Format numbers and dates for professional presentation

Common use cases include calculating totals, discounts, days until expiration, payment schedules, and dynamic pricing.

---

Basic Arithmetic Syntax

To use arithmetic functions in your S-Docs templates, enclose your calculation within <MATH> tags.

Static Numbers

html

<MATH>(2 + 1) / 3</MATH>

Using Salesforce Fields

html

<MATH>( {{!Opportunity.Num1__c}} + {{!Opportunity.Num2__c}} ) / {{!Opportunity.Num3__c}}</MATH>

Important: S-Docs evaluates all functions using the standard mathematical order of operations (PEMDAS).

---

Working With Negative Numbers

You can use negative numbers in your calculations, but be mindful of spacing to avoid confusion between subtraction and negative values.

Correct Syntax

html

<MATH>3 - 2</MATH>

This clearly performs subtraction.

Avoid This

html

<MATH>3 -2</MATH>

Without proper spacing, the operation may be misinterpreted.

---

Formatting Numbers

To format calculation results with commas, decimals, or other number patterns, use the format-number attribute within the <MATH> tag.

html

<MATH format-number="#,###.##">{{!Opportunity.Amount}} - {{!Opportunity.ExpectedRevenue}}</MATH>

Note: When inserting numeric fields using the Insert Field button, S-Docs automatically adds number formatting to merge fields. Be sure to remove this formatting when using merge fields within arithmetic functions to avoid conflicts.

---

Arithmetic Functions With Date Fields

S-Docs supports two main types of date calculations:

• Adding/subtracting time from a date (e.g., future-dating documents)
• Calculating time between two dates

Both require the type="date" attribute within your <MATH> tag.

Important: Static dates must follow the yyyy-MM-dd format (e.g., 2021-01-01 for January 1, 2021).

Adding or Subtracting Time

To add or subtract days, months, or years from a date field:

html

<MATH type="date">{{!Opportunity.CloseDate}} + DAYS(30) - MONTHS(1) + YEARS(2)</MATH>

Calculating Time Between Dates

To find the difference between two dates:

html

<MATH type="date">DaysBetween({{!Opportunity.createdByDate}}, {{!Opportunity.CloseDate}})</MATH>
<MATH type="date">MonthsBetween({{!Opportunity.createdByDate}}, {{!Opportunity.CloseDate}})</MATH>
<MATH type="date">YearsBetween({{!Opportunity.createdByDate}}, {{!Opportunity.CloseDate}})</MATH>

Note: if you encounter the error: ”ERROR:Incorrect format, first argument in date arithmetic should be a date” the field may not be a date field, is missing, or is a date-time field instead of a date field. Verify that all fields used in <MATH> tags with type="date" or date functions are date type only.

Formatting Dates

To format date calculation results, use the format-date attribute:

html

<MATH type="date" format-date="M/dd/yyyy">{{!Opportunity.createdByDate}} + DAYS(30)</MATH>

Note: When using the Insert Field button for date fields, S-Docs automatically adds date formatting to merge fields. Remove this formatting when using date fields within arithmetic functions.

---

Arithmetic Functions With Conditional Logic

You can use arithmetic functions within conditional logic (RENDER) statements. S-Docs processes the arithmetic before evaluating the condition.

html

<!--RENDER=((<MATH>{{!Opportunity.My_Num__c}} + {{!Opportunity.My_Num_2__c}}</MATH>) > 100) -->
The sum of my numbers is more than 100!
<!--ENDRENDER-->

Rounding For Conditional Logic

By default, arithmetic results are evaluated without rounding in conditional logic statements. To force rounding, use the format-number attribute.

Without Rounding (Evaluates to False):

html

<MATH>2 / 3</MATH> == 0.67

Since 2/3 = 0.666666..., this condition is false.

With Rounding (Evaluates to True):

html

<MATH format-number="#,###.##">2 / 3</MATH> == 0.67

The format-number attribute rounds the result to 0.67, making the condition true.

---

Handling Null Values in Math Tags

Problem

When generating documents, you may encounter error messages like:

• ERROR: Ending position out of bounds: 22 STACK
• Invalid double

These errors typically occur when merge fields within <MATH> tags contain null values rather than numeric values.

Solutions

1

Solution 1: Replace Null With Zero

Add the replaceall attribute to merge fields to replace null values with zero:

html

<MATH>{{!Opportunity.Amount replaceall=" ,0"}} + {{!Opportunity.CustomField__c replaceall=" ,0"}}</MATH>

This ensures that if a field is null, it's treated as 0 in the calculation.

2

Solution 2: Conditional Logic With Named Queries

Use conditional logic combined with named queries to check for data existence before performing calculations:

html

<!--{{!<LineItemsSOQL>
<class>none</class>
<queryname>myQuery1</queryname>
<soql>SELECT count(ID) cid from opportunity where accountid = '{{!Account.ID}}'</soql>
</LineItemsSOQL>}}-->

<!--{{!<LineItemsSOQL>
<class>none</class>
<queryname>myQuery2</queryname>
<soql>SELECT SUM(amount) total, SUM(customfield__c) reduce from opportunity where accountid = '{{!Account.ID}}'</soql>
</LineItemsSOQL>}}-->

<!--RENDER='{{!myQuery1.cid}} > 0' -->
<MATH>{{!myQuery2.total}} + {{!myQuery2.reduce}}</MATH>
<!--ENDRENDER-->

This approach:

1. First checks if any records exist
2. Only performs the calculation if records are found
3. Prevents null value errors by avoiding calculations when no data exists

Note: This solution also addresses the common "Invalid double" error message associated with null values in numeric fields.

---

DOCX Template Syntax

When using arithmetic functions in DOCX templates, follow these rules:

1. Use <math> or <MATH> tags (not case sensitive)
2. Enclose the entire function within square brackets (For DOCX templates, all dynamic content must be enclosed in square brackets)

Examples

html

[<math>(2 + 1) / 3</math>]
[<math>( {{!Opportunity.Num1__c}} + {{!Opportunity.Num2__c}} ) / {{!Opportunity.Num3__c}}</math>]

---

Best Practices

• Remove auto-formatting: When inserting fields via the Insert Field button, remove any automatic number or date formatting before using them in <MATH> tags.
• Use proper spacing: Include spaces around operators (especially minus signs) to ensure correct interpretation.
• Format intentionally: Apply format-number or format-date attributes at the <MATH> tag level, not within individual merge fields.
• Test conditional logic: When using arithmetic in RENDER statements, verify rounding behavior to ensure conditions evaluate as expected.
• Handle null values: Always account for the possibility of null values in numeric fields by using replaceall or conditional logic to prevent generation errors.

---

Arithmetic functions in S-Docs provide powerful, flexible calculation capabilities that enhance document automation and reduce the need for pre-calculated formula fields in Salesforce.