> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vodex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ๐งฎ Computation Custom Fields
> Learn how to use advanced computation features including math calculations, date operations, end-of-week, end-of-month, next-date, and date-range utilities in your custom fields
**Beta Feature:** Computation custom fields are currently in beta. While fully functional, this feature may receive updates and improvements. Please test thoroughly before using in production environments.
**What you'll learn:** How to perform mathematical calculations, date manipulations, end-of-week calculations, end-of-month calculations, next-date calculations, and date range calculations directly within your custom fields using `mathutil`, `dateutil`, `end_of_week`, `end_of_month`, `next_date`, and `date_range` utilities.
## What Are Computation Custom Fields?
Computation custom fields are **advanced dynamic placeholders** that can perform calculations and manipulations on your data in real-time. Instead of just inserting static values, these fields can:
* **Perform mathematical operations** (addition, subtraction, multiplication, division)
* **Calculate dates** (add or subtract days, months, years, hours, minutes, seconds)
* **Find next specific weekday** (next Monday, Friday, Sunday, etc.)
* **Calculate end of month** (last day of current month)
* **Find next occurrence of day of month** (next 5th, 15th, 28th, etc.)
* **Calculate date ranges** (formatted list of days from start date + number of days)
* **Create dynamic values** based on existing custom field data
Think of them as **smart calculators** embedded within your custom fields that automatically compute values when your AI conversations start.
## Why Use Computation Custom Fields? ๐ฏ
### **The Problem:**
* Need to calculate payment amounts with interest or fees
* Want to set reminder dates based on due dates
* Require dynamic pricing based on existing values
* Need follow-up dates calculated automatically
### **The Solution:**
* Real-time calculations within your prompts
* No manual math or date calculations needed
* Dynamic values that update automatically
* Professional, accurate, and consistent results
## Math Utility (mathutil) ๐ข
The `mathutil` function lets you perform mathematical operations on numeric custom fields.
### **Basic Syntax**
```
{mathutil:{FieldName}[operation][value]}
```
### **Supported Operations**
| Operation | Symbol | Description | Example |
| ------------------ | ------ | -------------------- | ----------------------------- |
| **Addition** | `+` | Add a number | `{mathutil:{AmountDue}+50}` |
| **Subtraction** | `-` | Subtract a number | `{mathutil:{AmountDue}-25}` |
| **Multiplication** | `*` | Multiply by a number | `{mathutil:{AmountDue}*1.05}` |
| **Division** | `/` | Divide by a number | `{mathutil:{AmountDue}/2}` |
### **Math Examples**
#### **Adding Late Fees**
```
Original Amount: {AmountDue}
With Late Fee: {mathutil:{AmountDue}+25}
```
**Result:**
```
Original Amount: $500.00
With Late Fee: $525.00
```
#### **Calculating Interest**
```
Principal: {LoanAmount}
With 5% Interest: {mathutil:{LoanAmount}*1.05}
```
**Result:**
```
Principal: $10,000.00
With 5% Interest: $10,500.00
```
#### **Payment Plans**
```
Total Amount: {AmountDue}
Monthly Payment (12 months): {mathutil:{AmountDue}/12}
```
**Result:**
```
Total Amount: $1,200.00
Monthly Payment (12 months): $100.00
```
#### **Discounts**
```
Original Price: {ProductPrice}
After 20% Discount: {mathutil:{ProductPrice}*0.8}
```
**Result:**
```
Original Price: $250.00
After 20% Discount: $200.00
```
### **Advanced Math Examples**
#### **Complex Financial Calculations**
```
"Hello {FirstName}, your account {AccountNumber} has an outstanding balance
of {AmountDue}. With the late fee of $25, your total amount due is
{mathutil:{AmountDue}+25}. We can offer you a payment plan of
{mathutil:{AmountDue}/6} per month for 6 months."
```
#### **Pricing Adjustments**
```
"Based on your subscription to {PlanName} at {MonthlyRate} per month,
your annual cost would be {mathutil:{MonthlyRate}*12}. However, if you
upgrade to our annual plan, you'd pay only {mathutil:{MonthlyRate}*10}
for the entire year."
```
## Date Utility (dateutil) ๐
The `dateutil` function lets you calculate dates by adding or subtracting time periods from existing dates.
### **Basic Syntax**
```
{dateutil:{FieldName}[+/-][amount][unit]}
```
### **Supported Time Units**
| Unit | Symbol | Description | Example |
| ----------- | ------ | --------------- | --------------------------- |
| **Days** | `d` | Calendar days | `+5d` (5 days later) |
| **Months** | `m` | Calendar months | `-2m` (2 months ago) |
| **Years** | `y` | Calendar years | `+1y` (1 year later) |
| **Hours** | `h` | Hours | `+24h` (24 hours later) |
| **Minutes** | `min` | Minutes | `+30min` (30 minutes later) |
| **Seconds** | `s` | Seconds | `+3600s` (1 hour later) |
### **Special Date References**
| Reference | Description | Usage |
| ------------- | ----------------- | -------------------------- |
| `{today}` | Current date/time | `{dateutil:{today}+7d}` |
| `{FieldName}` | Any date field | `{dateutil:{DueDate}+30d}` |
### **Date Examples**
#### **Payment Reminders**
```
Today: {today}
Payment Due: {DueDate}
Final Notice Date: {dateutil:{DueDate}+30d}
```
**Result:**
```
Today: March 15, 2024
Payment Due: March 30, 2024
Final Notice Date: April 29, 2024
```
#### **Appointment Scheduling**
```
Current Date: {today}
Next Available: {dateutil:{today}+3d}
Follow-up Date: {dateutil:{AppointmentDate}+14d}
```
**Result:**
```
Current Date: March 15, 2024 09:30:00
Next Available: March 18, 2024 09:30:00
Follow-up Date: April 2, 2024 14:00:00
```
#### **Contract Periods**
```
Contract Start: {StartDate}
Contract End: {dateutil:{StartDate}+1y}
Renewal Notice: {dateutil:{StartDate}+10m}
```
**Result:**
```
Contract Start: January 1, 2024
Contract End: January 1, 2025
Renewal Notice: November 1, 2024
```
### **Advanced Date Examples**
#### **Debt Collection Timeline**
```
"Hello {FirstName}, your payment of {AmountDue} was due on {DueDate}.
It's now {dateutil:{DueDate}+15d} past due. If we don't receive payment
by {dateutil:{today}+7d}, we'll need to escalate this matter."
```
#### **Subscription Management**
```
"Your {PlanName} subscription started on {SubscriptionStart} and will
renew on {dateutil:{SubscriptionStart}+1m}. Your next billing date is
{dateutil:{today}+{DaysUntilBilling}d}."
```
## End of Week Utility (end\_of\_week) ๐
The `end_of_week` function calculates the next occurrence of a specific day of the week from today's date.
### **Basic Syntax**
```
{end_of_week:[day_number]}
```
### **Day Numbers (Python Convention)**
| Day Number | Day of Week | Description |
| ---------- | ----------- | ---------------------- |
| `0` | Monday | Next Monday |
| `1` | Tuesday | Next Tuesday |
| `2` | Wednesday | Next Wednesday |
| `3` | Thursday | Next Thursday |
| `4` | Friday | Next Friday |
| `5` | Saturday | Next Saturday |
| `6` | Sunday | Next Sunday |
| `7` | Sunday | Alternative for Sunday |
The day numbers follow Python's `weekday()` convention where Monday is 0 and Sunday is 6. You can also use `7` for Sunday.
### **How It Works**
The `end_of_week` utility calculates the **next occurrence** of the specified day:
* If today is Tuesday and you specify `{end_of_week:0}` (Monday), you'll get the date for next Monday (6 days later)
* If today is Monday and you specify `{end_of_week:0}` (Monday), you'll get the date for next Monday (7 days later, not today)
* The function always returns a future date, never today's date
### **End of Week Examples**
#### **Setting Deadlines by Day**
```
Today: {today}
By Next Monday: {end_of_week:0}
By Next Friday: {end_of_week:4}
By Next Sunday: {end_of_week:6}
```
**Result (assuming today is Wednesday, March 13, 2024):**
```
Today: 13 Mar 2024
By Next Monday: 18 Mar 2024
By Next Friday: 15 Mar 2024
By Next Sunday: 17 Mar 2024
```
#### **Weekly Payment Reminders**
```
"Hello {FirstName}, your payment of {AmountDue} is due by this coming
Friday, {end_of_week:4}. Please ensure payment is received by end of day."
```
#### **Appointment Scheduling with Specific Days**
```
"We have availability next Monday ({end_of_week:0}) or next Thursday
({end_of_week:3}). Which day works better for you?"
```
### **Practical Use Cases**
#### **Weekly Follow-ups**
```
"Hello {CustomerName}, we'll follow up with you by {end_of_week:4}
regarding your account {AccountNumber}."
```
#### **Business Week Deadlines**
```
"Your order {OrderNumber} will be shipped by end of business week on
{end_of_week:4} (Friday)."
```
#### **Weekend Coordination**
```
"This weekend opportunity ends on {end_of_week:6} (Sunday) at midnight.
Don't miss out on this special offer of {mathutil:{ProductPrice}*0.8}!"
```
## End of Month Utility (end\_of\_month) ๐
The `end_of_month` function calculates the last day of the current month.
### **Basic Syntax**
```
{end_of_month}
```
The `end_of_month` utility is straightforward - it simply returns the last day of the current month. No parameters needed!
### **How It Works**
* Automatically calculates the last day of the current month
* Handles varying month lengths (28, 29, 30, or 31 days)
* Accounts for leap years in February
* Returns date in format: "DD MMM YYYY" (e.g., "31 Mar 2024")
### **End of Month Examples**
#### **Monthly Deadlines**
```
Today: {today}
End of This Month: {end_of_month}
```
**Result (assuming today is March 15, 2024):**
```
Today: 15 Mar 2024
End of This Month: 31 Mar 2024
```
#### **Monthly Payment Reminders**
```
"Hello {FirstName}, your monthly payment of {MonthlyPayment} is due by
the end of this month on {end_of_month}. Please ensure timely payment
to avoid late fees."
```
#### **Subscription Billing**
```
"Your {PlanName} subscription will renew at the end of this month
({end_of_month}) for {mathutil:{MonthlyRate}*1}."
```
### **Practical Use Cases**
#### **End of Month Campaigns**
```
"Hello {CustomerName}, our end-of-month sale ends on {end_of_month}!
Get {ProductName} for only {mathutil:{ProductPrice}*0.85} - that's 15% off
the regular price."
```
#### **Billing Cycles**
```
"Your account {AccountNumber} has a balance of {AmountDue}. Payment is
due by {end_of_month} to maintain your service without interruption."
```
#### **Performance Targets**
```
"Team, we have until {end_of_month} to reach our monthly goal. Let's
push forward!"
```
#### **Financial Deadlines**
```
"Hello {FirstName}, your quarterly payment of {QuarterlyAmount} must be
received by end of month ({end_of_month}). This covers your service
through {dateutil:{today}+3m}."
```
## Next Date Utility (next\_date) ๐
The `next_date` function calculates the next occurrence of a specific day of the month, making it perfect for setting deadlines, billing dates, and recurring monthly events.
### **Basic Syntax**
```
{next_date:[start_date]+[day_number]}
```
### **Parameters**
| Parameter | Description | Example | Required |
| ------------ | ------------------------------------- | -------------------------- | -------- |
| `start_date` | Starting date (field name or {today}) | `{StartDate}` or `{today}` | โ
Yes |
| `day_number` | Target day of the month (1-31) | `5`, `15`, `28` | โ
Yes |
### **How It Works**
The `next_date` utility calculates the next occurrence of a specific day of the month:
* **Start Date**: Can be any custom field containing a date or `{today}`
* **Day Number**: The target day of the month (1-31)
* **Logic**:
* If current day โค target day: Returns target day in the **current month**
* If current day > target day: Returns target day in the **next month**
* **Result**: Returns the date in "DD MMM YYYY, (DayName)" format
### **Next Date Examples**
#### **From Today for Next 5th**
```
Today: {today}
Next 5th: {next_date:{today}+5}
```
**Result (assuming today is November 1, 2024):**
```
Today: 01 Nov 2024
Next 5th: 05 Nov 2024, (Tuesday)
```
**Result (assuming today is November 15, 2024):**
```
Today: 15 Nov 2024
Next 5th: 05 Dec 2024, (Thursday)
```
#### **From Start Date for Next 10th**
```
Start Date: {StartDate}
Next 10th: {next_date:{StartDate}+10}
```
**Result (if StartDate is January 8, 2024):**
```
Start Date: 08 Jan 2024
Next 10th: 10 Jan 2024, (Wednesday)
```
**Result (if StartDate is January 20, 2024):**
```
Start Date: 20 Jan 2024
Next 10th: 10 Feb 2024, (Saturday)
```
#### **Monthly Billing Date**
```
Current Date: {today}
Next Billing: {next_date:{today}+15}
```
**Result:**
```
Current Date: 05 Mar 2024
Next Billing: 15 Mar 2024, (Friday)
```
**Result (if today is March 20, 2024):**
```
Current Date: 20 Mar 2024
Next Billing: 15 Apr 2024, (Monday)
```
### **Advanced Next Date Examples**
#### **Monthly Payment Deadlines**
```
"Hello {FirstName}, your payment of {AmountDue} is due on the 5th of each month.
Your next payment deadline is {next_date:{today}+5}. Please ensure payment is
received by then to avoid late fees."
```
#### **Billing Cycle Management**
```
"Your {ServiceName} subscription bills on the 15th of each month.
Your next billing date is {next_date:{today}+15} for {mathutil:{MonthlyRate}*1}.
This will be automatically charged to your account."
```
#### **Recurring Deadlines**
```
"Project {ProjectName} has a monthly review on the 28th.
Your next review deadline is {next_date:{today}+28}.
Please submit your progress report by then."
```
### **Practical Use Cases**
#### **Monthly Payment Reminders**
```
"Hello {CustomerName}, your account {AccountNumber} has a monthly payment
due on the 5th. Your next payment of {AmountDue} is due on
{next_date:{today}+5}. Please ensure payment is received by end of day."
```
#### **Subscription Renewals**
```
"Your {PlanName} subscription renews on the 1st of each month.
Your next renewal date is {next_date:{today}+1} for
{mathutil:{MonthlyRate}*1}. Your service will continue automatically."
```
#### **Report Submission Deadlines**
```
"Your monthly report is due on the 10th of each month.
The next submission deadline is {next_date:{today}+10}.
Please ensure all data is submitted by end of day."
```
#### **Rent Payment Due Dates**
```
"Your rent payment of {RentAmount} is due on the 1st of each month.
Your next payment is due on {next_date:{today}+1}.
Late payments after the 5th will incur a fee of {mathutil:{RentAmount}*0.05}."
```
## Date Range Utility (date\_range) ๐
The `date_range` function calculates a date range FROM a start date FOR a specified number of days, making it perfect for creating time-based windows, billing periods, and scheduling ranges.
### **Basic Syntax**
```
{date_range:[start_date]-[number_of_days]}
```
### **Parameters**
| Parameter | Description | Example | Required |
| ---------------- | ------------------------------------------ | -------------------------- | -------- |
| `start_date` | Starting date (field name or {today}) | `{StartDate}` or `{today}` | โ
Yes |
| `number_of_days` | Number of days from start date (inclusive) | `5`, `30`, `90` | โ
Yes |
### **How It Works**
The `date_range` utility calculates a date range starting from a specified date:
* **Start Date**: Can be any custom field containing a date or `{today}`
* **Number of Days**: Specifies how many days forward from the start date (inclusive)
* **Result**: Returns a formatted list showing each day in the range with date and day of week
* **Inclusive**: The range includes both the start date and the end date
* **Format**: Each day shows as "DD MMM YYYY, DayName"
### **Date Range Examples**
#### **From Today for 6 Days**
```
Today: {today}
Range: {date_range:{today}-6}
```
**Result (assuming today is October 21, 2025):**
```
Today: 21 Oct 2025
Range:
1: 22 Oct 2025, Wednesday
2: 23 Oct 2025, Thursday
3: 24 Oct 2025, Friday
4: 25 Oct 2025, Saturday
5: 26 Oct 2025, Sunday
6: 27 Oct 2025, Monday
```
#### **From Start Date for 5 Days**
```
Start Date: {StartDate}
Range: {date_range:{StartDate}-5}
```
**Result:**
```
Start Date: 01 Jan 2024
Range:
1: 02 Jan 2024, Tuesday
2: 03 Jan 2024, Wednesday
3: 04 Jan 2024, Thursday
4: 05 Jan 2024, Friday
5: 06 Jan 2024, Saturday
```
#### **Payment Window**
```
Payment Due: {DueDate}
Grace Period: {date_range:{DueDate}-7}
```
**Result:**
```
Payment Due: 15 Mar 2024
Grace Period:
1: 16 Mar 2024, Saturday
2: 17 Mar 2024, Sunday
3: 18 Mar 2024, Monday
4: 19 Mar 2024, Tuesday
5: 20 Mar 2024, Wednesday
6: 21 Mar 2024, Thursday
7: 22 Mar 2024, Friday
```
### **Advanced Date Range Examples**
#### **Billing Cycle Window**
```
"Hello {FirstName}, your billing cycle starts today ({today}) and runs
for 7 days. Here are your billing days:
{date_range:{today}-7}
Your next payment of {mathutil:{MonthlyRate}*1} is due by the last day."
```
#### **Trial Period Tracking**
```
"Your {ServiceName} trial started on {TrialStart} and runs for 14 days:
{date_range:{TrialStart}-14}
You have until the last day to upgrade to avoid service interruption."
```
#### **Project Timeline**
```
"Project {ProjectName} started on {ProjectStart} and has a 5-day timeline:
{date_range:{ProjectStart}-5}
Please complete all tasks within this timeframe."
```
### **Practical Use Cases**
#### **Payment Grace Period**
```
"Hello {FirstName}, your payment of {AmountDue} was due on {DueDate}.
You have a 5-day grace period:
{date_range:{DueDate}-5}
After the last day, late fees of {mathutil:{AmountDue}*0.05} will apply."
```
#### **Subscription Trial**
```
"Your {PlanName} trial started on {TrialStart} and runs for 14 days:
{date_range:{TrialStart}-14}
To continue service, please upgrade by the last day."
```
#### **Campaign Duration**
```
"Our {CampaignName} campaign runs from {CampaignStart} for 7 days:
{date_range:{CampaignStart}-7}
Don't miss this limited-time offer!"
```
#### **Warranty Period**
```
"Your {ProductName} warranty is valid from {PurchaseDate} for 30 days:
{date_range:{PurchaseDate}-30}
Any claims must be submitted before the warranty expires."
```
## Combining Multiple Utilities ๐
You can combine math, date, end-of-week, end-of-month, next-date, and date-range utilities in the same prompt for sophisticated calculations:
### **Dynamic Payment Scheduling**
```
"Hello {FirstName}, your total amount of {AmountDue} can be split into
3 payments of {mathutil:{AmountDue}/3} each. The payment schedule would be:
- First payment: {mathutil:{AmountDue}/3} due {dateutil:{today}+7d}
- Second payment: {mathutil:{AmountDue}/3} due {dateutil:{today}+37d}
- Final payment: {mathutil:{AmountDue}/3} due {dateutil:{today}+67d}"
```
### **Interest Calculations with Dates**
```
"Your loan of {LoanAmount} has been outstanding since {LoanDate}.
With interest, your current balance is {mathutil:{LoanAmount}*1.05}.
If paid by {dateutil:{today}+30d}, you can settle for
{mathutil:{LoanAmount}*0.95}."
```
### **Weekly and Monthly Deadlines with Discounts**
```
"Hello {FirstName}, your account {AccountNumber} shows a balance of {AmountDue}.
Pay by this Friday ({end_of_week:4}): {mathutil:{AmountDue}*0.95} (5% discount)
Pay by end of month ({end_of_month}): {mathutil:{AmountDue}*0.98} (2% discount)
Pay after {end_of_month}: Full amount of {AmountDue} plus {mathutil:{AmountDue}*0.05} late fee"
```
### **Comprehensive Campaign with All Utilities**
```
"Hi {CustomerName}, special offer ending {end_of_week:6}!
Original Price: {ProductPrice}
Today's Discount: {mathutil:{ProductPrice}*0.80} (20% off)
Monthly Plan: {mathutil:{ProductPrice}/12} per month
First payment due: {end_of_week:4}
Final payment: {dateutil:{today}+11m}
Offer expires: {end_of_month}"
```
### **Advanced Analytics with Date Ranges**
```
"Hello {CustomerName}, your trial period started on {TrialStart} and
runs for 14 days:
{date_range:{TrialStart}-14}
Your subscription of {mathutil:{MonthlyRate}*12} annually will begin
after the trial ends.
Upgrade by the last day to avoid service interruption."
```
### **Monthly Billing with Next Date**
```
"Hello {FirstName}, your {ServiceName} subscription bills monthly on the 5th.
Your next billing date is {next_date:{today}+5} for {mathutil:{MonthlyRate}*1}.
Your account {AccountNumber} has been active since {AccountStart}.
Payment will be automatically charged on {next_date:{today}+5}.
If payment fails, you have until {dateutil:{next_date:{today}+5}+7d} to update your payment method."
```
## Required Fields and Dependencies ๐
### **For Date Utilities (dateutil, end\_of\_week, end\_of\_month, next\_date, date\_range):**
**Mandatory Fields for Date Operations:** When using any date utilities (`dateutil`, `end_of_week`, `end_of_month`, `next_date`, or `date_range`), both `{today}` and `{time_zone}` fields are **mandatory** and must be included in your prompt. During testing or when uploading audience data, you **must** provide the `time_zone` field, while `today` will be filled automatically by Vodex.
#### **Required Fields:**
* `today` - Current date/time (automatically provided by Vodex)
* `raw_today` - Raw timestamp format (automatically provided, used by end\_of\_week, end\_of\_month, and next\_date)
* `time_zone` - User's timezone (must be provided)
* **Date fields** - For `date_range` and `next_date`, start date fields must exist and contain valid dates
#### **Valid Timezone Formats:**
```
Asia/Kolkata โ
Correct
+05:30 โ
Correct
-08:00 โ
Correct
EST โ Avoid (use full timezone names)
```
**Important:** The `time_zone` field must be a valid timezone. Invalid timezones will cause "Something went wrong" errors.
The field `today` should be left blank when making calls via Agent Call, Campaign Run, or API. Vodex will fill it automatically using the `time_zone` field. For more details about these base fields, see our [Custom Fields Introduction](/custom-fields/introduction).
### **For Math Utilities:**
* The referenced field must contain numeric data
* Field must exist in your custom fields data
* Values must be convertible to numbers
## Error Handling and Validation โ ๏ธ
### **Common Math Errors**
| Error Scenario | Cause | Solution |
| --------------------- | ------------------------------ | ------------------------------------- |
| **Division by zero** | `{mathutil:{Amount}/0}` | Use non-zero divisors |
| **Invalid operation** | `{mathutil:{Amount}%5}` | Use supported operators (+, -, \*, /) |
| **Non-numeric field** | Field contains text | Ensure field has numeric data |
| **Missing field** | Referenced field doesn't exist | Verify field name and data |
### **Common Date Errors**
| Error Scenario | Cause | Solution |
| ------------------------- | ----------------------------------------- | ---------------------------------- |
| **Missing today field** | `today` not provided | Vodex provides this automatically |
| **Missing raw\_today** | Required for end\_of\_week/end\_of\_month | Vodex provides this automatically |
| **Invalid timezone** | Wrong timezone format | Use valid timezone strings |
| **Invalid date format** | Can't parse source date | Use standard date formats |
| **Missing time unit** | `{dateutil:{today}+5}` | Include unit: `+5d` |
| **Invalid day number** | `{end_of_week:8}` | Use 0-7 only (0=Mon, 6=Sun) |
| **Missing date field** | `{date_range:{MissingField}-5}` | Ensure start date field exists |
| **Invalid number format** | `{date_range:{today}-abc}` | Use numeric values only |
| **Negative days** | `{date_range:{today}--5}` | Use positive numbers only |
| **Invalid day of month** | `{next_date:{today}+32}` | Use 1-31 only (valid day of month) |
| **Missing start date** | `{next_date:{MissingField}+5}` | Ensure start date field exists |
| **Invalid date format** | `{next_date:{InvalidDate}+5}` | Use valid date format |
### **Error Examples**
#### **Math Error - Division by Zero:**
```
โ Wrong: {mathutil:{AmountDue}/0}
โ
Correct: {mathutil:{AmountDue}/12}
```
#### **Date Error - Missing Unit:**
```
โ Wrong: {dateutil:{today}+30}
โ
Correct: {dateutil:{today}+30d}
```
#### **Field Missing Error:**
```
โ Wrong: {mathutil:{NonExistentField}+100}
โ
Correct: {mathutil:{AmountDue}+100}
```
#### **End of Week Error - Invalid Day Number:**
```
โ Wrong: {end_of_week:8}
โ
Correct: {end_of_week:0} (Monday) or {end_of_week:6} (Sunday)
```
#### **Missing Required Field Error:**
```
โ Wrong: Using {end_of_month} without time_zone in audience data
โ
Correct: Provide time_zone field in your audience upload
```
#### **Date Range Error - Missing Field:**
```
โ Wrong: {date_range:{NonExistentField}-5}
โ
Correct: {date_range:{StartDate}-5}
```
#### **Date Range Error - Invalid Number:**
```
โ Wrong: {date_range:{today}-abc}
โ
Correct: {date_range:{today}-5}
```
#### **Date Range Error - Negative Days:**
```
โ Wrong: {date_range:{today}--5}
โ
Correct: {date_range:{today}-5}
```
#### **Next Date Error - Invalid Day of Month:**
```
โ Wrong: {next_date:{today}+32}
โ
Correct: {next_date:{today}+5} (valid day 1-31)
```
#### **Next Date Error - Missing Field:**
```
โ Wrong: {next_date:{NonExistentField}+5}
โ
Correct: {next_date:{StartDate}+5}
```
## Best Practices for Computation Fields ๐
### **1. Always Validate Your Data**
* Ensure numeric fields contain valid numbers
* Verify date fields have proper date formats
* Test with sample data before going live
### **2. Use Descriptive Field Names**
```
โ
Good: {mathutil:{MonthlyPayment}*12}
โ Avoid: {mathutil:{MP}*12}
```
### **3. Handle Edge Cases**
* Plan for missing data scenarios
* Consider what happens with zero values
* Test with various data types
### **4. Keep Calculations Simple**
* Use straightforward operations when possible
* Break complex calculations into multiple fields
* Make calculations easy to understand and verify
### **5. Test Thoroughly**
* Test with different numeric values
* Try various date scenarios
* Verify timezone handling
## Real-World Use Cases ๐
### **Debt Collection Agency**
```
"Hello {FirstName}, your account {AccountNumber} shows an outstanding
balance of {AmountDue}. This amount has been past due since {DueDate},
which is now {dateutil:{DueDate}+{DaysPastDue}d} overdue.
We can offer you a settlement of {mathutil:{AmountDue}*0.8} if paid by
this Friday ({end_of_week:4}), or a payment plan of {mathutil:{AmountDue}/6}
per month for 6 months with first payment due by {end_of_month}."
```
### **Healthcare Appointment Reminders**
```
"Hi {PatientName}, this is a reminder for your appointment with
Dr. {DoctorName} on {AppointmentDate}. Please arrive 15 minutes early.
Your next follow-up should be scheduled for approximately
{dateutil:{AppointmentDate}+3m}. Your estimated co-pay is
{mathutil:{BaseCopay}+{AdditionalFees}}."
```
### **Subscription Services**
```
"Hello {CustomerName}, your {PlanName} subscription of {MonthlyRate}
per month will renew on {end_of_month}.
Your annual cost is {mathutil:{MonthlyRate}*12}, but you can save
{mathutil:{MonthlyRate}*2} by switching to our annual plan before
{end_of_week:4} (this Friday)."
```
### **Real Estate Follow-ups**
```
"Hi {ClientName}, it's been {dateutil:{LastContact}+{DaysSince}d} since
we last spoke about the {PropertyAddress} listing at {ListingPrice}.
Based on current market conditions, a competitive offer would be around
{mathutil:{ListingPrice}*0.95}. Would you like to schedule a viewing
for {dateutil:{today}+2d}?"
```
## Testing Your Computation Fields ๐งช
### **Testing Checklist**
* [ ] **Math operations work correctly** - Test all four operations (+, -, \*, /)
* [ ] **Date calculations are accurate** - Verify dateutil arithmetic
* [ ] **End of week calculations** - Test all day numbers (0-7)
* [ ] **End of month calculations** - Test across different months and leap years
* [ ] **Next date calculations** - Test with different days of month (1-31)
* [ ] **Date range calculations** - Test with different day ranges
* [ ] **Field references resolve** - Ensure all fields exist
* [ ] **Error handling works** - Test with invalid data
* [ ] **Timezone handling correct** - Test with different timezones
* [ ] **Conversation flows naturally** - Verify the computed values make sense
* [ ] **Combined utilities work** - Test mixing multiple utility types
### **Sample Test Data**
```json theme={null}
{
"FirstName": "John",
"AmountDue": "500.00",
"DueDate": "2024-03-30",
"MonthlyRate": "99.99",
"time_zone": "America/New_York"
}
```
### **Expected Results**
```
{mathutil:{AmountDue}+25} = 525.00
{mathutil:{MonthlyRate}*12} = 1199.88
{dateutil:{DueDate}+30d} = 2024-04-29
{dateutil:{today}+7d} = [7 days from current date]
{end_of_week:4} = [Next Friday's date]
{end_of_week:0} = [Next Monday's date]
{end_of_month} = [Last day of current month]
{next_date:{today}+5} = "05 Nov 2024, (Tuesday)" (if today is Nov 1) or "05 Dec 2024, (Thursday)" (if today is Nov 15)
{date_range:{StartDate}-5} = "1: 02 Jan 2024, Tuesday \n2: 03 Jan 2024, Wednesday \n3: 04 Jan 2024, Thursday \n4: 05 Jan 2024, Friday \n5: 06 Jan 2024, Saturday"
{date_range:{today}-6} = "1: 22 Oct 2025, Wednesday \n2: 23 Oct 2025, Thursday \n3: 24 Oct 2025, Friday \n4: 25 Oct 2025, Saturday \n5: 26 Oct 2025, Sunday \n6: 27 Oct 2025, Monday"
```
## Troubleshooting Guide ๐ง
### **Math Issues**
**Problem:** Field shows wrong calculation
* Check field contains numeric data
* Verify operation syntax
* Test with simple values first
**Problem:** Division returns unexpected results
* Ensure you're not dividing by zero
* Check for decimal vs integer division
* Verify the divisor value
### **Date Issues**
**Problem:** Date calculation fails
* Verify timezone is properly set
* Check source date format
* Ensure time unit is included
* Confirm raw\_today is available (for end\_of\_week/end\_of\_month)
**Problem:** Wrong date returned
* Confirm timezone is correct
* Check if daylight saving affects calculation
* Verify source date is accurate
### **End of Week Issues**
**Problem:** Wrong weekday calculated
* Verify day number (0=Monday, 6=Sunday)
* Check that raw\_today field exists
* Confirm timezone is set correctly
**Problem:** Returns today instead of next occurrence
* System always returns next occurrence, not current day
* If you need current day, use {today} instead
### **End of Month Issues**
**Problem:** Wrong last day calculated
* Verify raw\_today field exists
* Check timezone setting
* Confirm current month/year is correct
**Problem:** Leap year not handled
* System automatically handles leap years
* Verify raw\_today format is correct
### **Next Date Issues**
**Problem:** Wrong date calculated
* Verify start date field exists and contains valid date
* Check that day number is between 1-31
* Confirm timezone is set correctly
**Problem:** Invalid day of month error
* Use only valid days of the month (1-31)
* Avoid days that don't exist in certain months (e.g., Feb 30)
* System will automatically handle month boundaries
**Problem:** Missing field error
* Ensure the start date field exists in your custom fields
* Verify field name spelling and case sensitivity
**Problem:** Date parsing error
* Start date must be in a valid date format
* System handles various date formats automatically
* Check that raw\_today is available when using {today}
### **Date Range Issues**
**Problem:** Wrong end date calculated
* Verify start date field exists and contains valid date
* Check that number of days is a positive integer
* Confirm timezone is set correctly
**Problem:** Invalid number error
* Use only numeric values for days (5, 30, 90)
* Avoid non-numeric characters or negative numbers
**Problem:** Missing field error
* Ensure the start date field exists in your custom fields
* Verify field name spelling and case sensitivity
**Problem:** Date format issues
* Start date must be in a valid date format
* System handles various date formats automatically
## Next Steps ๐
Now that you understand computation custom fields:
1. **Start with simple calculations** - Begin with basic math operations
2. **Test thoroughly** - Verify calculations with sample data
3. **Add date computations** - Include timeline calculations with dateutil
4. **Use weekday and month-end features** - Leverage end\_of\_week and end\_of\_month
5. **Set monthly deadlines** - Use next\_date for recurring monthly dates
6. **Calculate time periods** - Use date\_range for duration analysis
7. **Combine all utilities** - Create sophisticated prompts with multiple computation types
8. **Monitor and optimize** - Track performance and accuracy
## Quick Reference Summary ๐
| Utility | Syntax | Example | Output Format |
| ---------------- | -------------------------------------- | -------------------------- | --------------------------------------------------------- |
| **Math** | `{mathutil:{Field}[op][value]}` | `{mathutil:{Amount}*1.05}` | Number |
| **Date** | `{dateutil:{Field}[+/-][count][unit]}` | `{dateutil:{today}+7d}` | Full datetime |
| **End of Week** | `{end_of_week:[0-7]}` | `{end_of_week:4}` | DD MMM YYYY |
| **End of Month** | `{end_of_month}` | `{end_of_month}` | DD MMM YYYY |
| **Next Date** | `{next_date:{start}+{day}}` | `{next_date:{today}+5}` | "05 Nov 2024, (Tuesday)" |
| **Date Range** | `{date_range:{start}-{days}}` | `{date_range:{today}-6}` | "1: 22 Oct 2025, Wednesday \n2: 23 Oct 2025, Thursday..." |
**Ready to supercharge your custom fields?** Computation fields unlock powerful dynamic capabilities that make your AI conversations more intelligent, accurate, and useful. Start implementing them today to create more sophisticated and helpful interactions.
***
**Need the basics first?** Check out our [Custom Fields Introduction](/custom-fields/introduction) and [Best Practices](/custom-fields/best-practices) guides before diving into computation features.