Skip to main content

Formulas & Variables

Overview​

The Formulas API allows creating custom calculation formulas using variables for advanced cost modeling scenarios. Formulas can reference global variables, bid-specific values, and perform mathematical operations.

Formula Variables​

List Variables​

GET /api/formulas/variables
Cookie: sAccessToken=...; sRefreshToken=...

Roles: ADMIN, ESTIMATOR, PM

Create Variable​

POST /api/formulas/variables
Cookie: sAccessToken=...; sRefreshToken=...
Content-Type: application/json

{
"name": "labor_burden_rate",
"displayName": "Labor Burden Rate",
"value": 1.35,
"type": "NUMBER",
"description": "Multiplier for labor burden (35%)"
}

Roles: ADMIN, ESTIMATOR, PM

Variable Types:

  • NUMBER - Numeric value (e.g., 1.05, 42.5)
  • PERCENTAGE - Percentage value (e.g., 15 for 15%)
  • STRING - Text value

Delete Variable​

DELETE /api/formulas/variables/:id
Cookie: sAccessToken=...; sRefreshToken=...

Roles: ADMIN

warning

Deleting a variable will break any formulas that reference it. Check formula dependencies first.

Formulas​

List Formulas​

GET /api/formulas
Cookie: sAccessToken=...; sRefreshToken=...

Roles: ADMIN, ESTIMATOR, PM

Get Formula​

GET /api/formulas/:id
Cookie: sAccessToken=...; sRefreshToken=...

Roles: ADMIN, ESTIMATOR, PM

Create Formula​

POST /api/formulas
Cookie: sAccessToken=...; sRefreshToken=...
Content-Type: application/json

{
"name": "Total Labor Cost",
"expression": "hourly_rate _ hours _ labor_burden_rate",
"description": "Labor cost with burden",
"variables": ["hourly_rate", "hours", "labor_burden_rate"]
}

Roles: ADMIN, ESTIMATOR

Expression Syntax:

  • Arithmetic operators: +, -, *, /, ^ (power)
  • Parentheses: (, )
  • Variables: Reference by name (e.g., concrete_cost)
  • Functions: sqrt(), abs(), min(), max()

Example Expressions:

// Simple multiplication
quantity * unit_price;

// With waste factor
quantity *
  (1 + waste_factor) *
  unit_price(
    // Complex calculation
    labor_hours * hourly_rate * labor_burden,
  ) +
  equipment_hours * equipment_rate;

// Conditional-like (using min/max)
max(min_charge, quantity * unit_price);

Update Formula​

PUT /api/formulas/:id
Cookie: sAccessToken=...; sRefreshToken=...
Content-Type: application/json

{
"expression": "hourly_rate _ hours _ labor_burden_rate \* (1 + overhead_rate)",
"description": "Labor cost with burden and overhead"
}

Roles: ADMIN, ESTIMATOR

Delete Formula​

DELETE /api/formulas/:id
Cookie: sAccessToken=...; sRefreshToken=...

Roles: ADMIN, ESTIMATOR

Data Model​

interface FormulaVariable {
  id: string
  name: string              // Unique identifier for use in formulas
  displayName: string       // Human-readable name
  value: number | string
  type: VariableType        // NUMBER, PERCENTAGE, STRING
  description: string
  createdAt: DateTime
  updatedAt: DateTime
}

interface Formula {
  id: string
  name: string
  expression: string        // Mathematical expression
  description: string
  variables: string[]       // Variable names used in expression
  createdAt: DateTime
  updatedAt: DateTime
}

enum VariableType {
  NUMBER
  PERCENTAGE
  STRING
}

Use Cases​

1. Custom Waste Factors​

// Formula: Adjusted Material Quantity
quantity * (1 + waste_factor);

// Variables:
// - quantity: From material item
// - waste_factor: 0.05 (5% waste)

2. Labor Burden Calculations​

// Formula: True Labor Cost
base_labor_cost * (1 + burden_rate + overhead_rate);

// Variables:
// - base_labor_cost: From labor items
// - burden_rate: 0.35 (35% for taxes, insurance, benefits)
// - overhead_rate: 0.10 (10% company overhead)

3. Volume-Based Pricing Tiers​

// Formula: Tiered Pricing
quantity < 100 ? quantity * high_price : quantity * bulk_price;

// Note: Conditional logic requires using min/max functions
min(quantity * high_price, 100 * high_price + (quantity - 100) * bulk_price);