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
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) 🔢
Themathutil function lets you perform mathematical operations on numeric custom fields.
Basic Syntax
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
Calculating Interest
Payment Plans
Discounts
Advanced Math Examples
Complex Financial Calculations
Pricing Adjustments
Date Utility (dateutil) 📅
Thedateutil function lets you calculate dates by adding or subtracting time periods from existing dates.
Basic Syntax
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
Appointment Scheduling
Contract Periods
Advanced Date Examples
Debt Collection Timeline
Subscription Management
End of Week Utility (end_of_week) 📆
Theend_of_week function calculates the next occurrence of a specific day of the week from today’s date.
Basic Syntax
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
Theend_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
Weekly Payment Reminders
Appointment Scheduling with Specific Days
Practical Use Cases
Weekly Follow-ups
Business Week Deadlines
Weekend Coordination
End of Month Utility (end_of_month) 📅
Theend_of_month function calculates the last day of the current month.
Basic Syntax
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
Monthly Payment Reminders
Subscription Billing
Practical Use Cases
End of Month Campaigns
Billing Cycles
Performance Targets
Financial Deadlines
Next Date Utility (next_date) 📆
Thenext_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
Parameters
| Parameter | Description | Example | Required |
|---|---|---|---|
start_date | Starting date (field name or ) | {StartDate} or {today} | ✅ Yes |
day_number | Target day of the month (1-31) | 5, 15, 28 | ✅ Yes |
How It Works
Thenext_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
From Start Date for Next 10th
Monthly Billing Date
Advanced Next Date Examples
Monthly Payment Deadlines
Billing Cycle Management
Recurring Deadlines
Practical Use Cases
Monthly Payment Reminders
Subscription Renewals
Report Submission Deadlines
Rent Payment Due Dates
Date Range Utility (date_range) 📊
Thedate_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
Parameters
| Parameter | Description | Example | Required |
|---|---|---|---|
start_date | Starting date (field name or ) | {StartDate} or {today} | ✅ Yes |
number_of_days | Number of days from start date (inclusive) | 5, 30, 90 | ✅ Yes |
How It Works
Thedate_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
From Start Date for 5 Days
Payment Window
Advanced Date Range Examples
Billing Cycle Window
Trial Period Tracking
Project Timeline
Practical Use Cases
Payment Grace Period
Subscription Trial
Campaign Duration
Warranty Period
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
Interest Calculations with Dates
Weekly and Monthly Deadlines with Discounts
Comprehensive Campaign with All Utilities
Advanced Analytics with Date Ranges
Monthly Billing with Next Date
Required Fields and Dependencies 📋
For Date Utilities (dateutil, end_of_week, end_of_month, next_date, date_range):
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_rangeandnext_date, start date fields must exist and contain valid dates
Valid Timezone Formats:
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.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:
Date Error - Missing Unit:
Field Missing Error:
End of Week Error - Invalid Day Number:
Missing Required Field Error:
Date Range Error - Missing Field:
Date Range Error - Invalid Number:
Date Range Error - Negative Days:
Next Date Error - Invalid Day of Month:
Next Date Error - Missing Field:
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
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
Healthcare Appointment Reminders
Subscription Services
Real Estate Follow-ups
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
Expected Results
Troubleshooting Guide 🔧
Math Issues
Problem: Field shows wrong calculation- Check field contains numeric data
- Verify operation syntax
- Test with simple values first
- 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)
- 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
- System always returns next occurrence, not current day
- If you need current day, use instead
End of Month Issues
Problem: Wrong last day calculated- Verify raw_today field exists
- Check timezone setting
- Confirm current month/year is correct
- 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
- 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
- Ensure the start date field exists in your custom fields
- Verify field name spelling and case sensitivity
- Start date must be in a valid date format
- System handles various date formats automatically
- Check that raw_today is available when using
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
- Use only numeric values for days (5, 30, 90)
- Avoid non-numeric characters or negative numbers
- Ensure the start date field exists in your custom fields
- Verify field name spelling and case sensitivity
- Start date must be in a valid date format
- System handles various date formats automatically
Next Steps 🚀
Now that you understand computation custom fields:- Start with simple calculations - Begin with basic math operations
- Test thoroughly - Verify calculations with sample data
- Add date computations - Include timeline calculations with dateutil
- Use weekday and month-end features - Leverage end_of_week and end_of_month
- Set monthly deadlines - Use next_date for recurring monthly dates
- Calculate time periods - Use date_range for duration analysis
- Combine all utilities - Create sophisticated prompts with multiple computation types
- 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 and Best Practices guides before diving into computation features.